1# `mesh2faust` 2 3`mesh2faust` is an open-source modal physical model generator for the Faust 4programming language. `mesh2faust` takes a volumetric mesh of a 3D object as 5its main argument, carries out a finite element analysis, and generates the 6corresponding Faust modal physical model. A wide range of parameters can be 7configured to fine-tune the analysis as well as the behavior of the generated 8object. 9 10`mesh2faust` is based on [Vega FEM](http://run.usc.edu/vega/) and should work 11both on Linux and OSX. 12 13`mesh2faust` is part of the 14[Faust Physical Modeling Toolkit](https://ccrma.stanford.edu/~rmichon/pmFaust). 15Tutorials on how to make 16physical models of musical instruments can be found 17[here](https://ccrma.stanford.edu/~rmichon/faustTutorials/#making-physical-models-of-musical-instruments-with-faust). 18 19## Build/Installation 20 21`mesh2faust` relies on [Vega FEM](http://run.usc.edu/vega/) to turn the 22provided volumetric mesh into a 3D mesh and to carry out the finite element 23analysis on it. A lightweight adapted version of this library is part of this 24repository. 25 26Vega itself relies on some libraries that must be installed on your system in 27order to compile `mesh2faust`. This section walks you through the different 28steps to build and install `mesh2faust` on your system. 29 30### Linux 31 32* First, install the Intel MKL Library (<https://software.intel.com/en-us/intel-mkl>). 33Unfortunately, this library is not open source (but it's free), so you wont find 34it in your usual package manager. 35* Get `libarpack` with your package manager (`libarpack2-dev` in Ubuntu). 36* Go in `/vega/Makefile-headers/` and run "`selectLinux`", this will update the 37dynamic link of `Makefile-header` to the right Makefile for your system. 38* You might have to make some adjustments in 39`/vega/Makefile-headers/Makefile-header.linux` in the "MKL Paths" section 40(Intel tends to change the organization of this lib pretty often). 41* Run: `make` 42* Run: `sudo make install` 43* NOTE: Additional adjustments might have to be made to `Makefile-header.linux` 44(compilation was only tested on Linux Mint) 45 46### OSX 47 48* First, install the Intel MKL Library (<https://software.intel.com/en-us/intel-mkl>). 49Unfortunately, this library is not open source (but it's free), so you wont find 50it in your usual package manager. 51* Get `arpack`. The `mesh2faust` makefiles were configured to work with the MacPort 52version of `arpack`, so we advise you to use this package manager to get it 53(e.g., `port install arpack`). 54* Go in `/vega/Makefile-headers/` and run "`selectMacOSX`", this will update the 55dynamic link of `Makefile-header` to the right Makefile for your system. 56* You might have to make some adjustments in 57`/vega/Makefile-headers/Makefile-header.osx` in the "MKL Paths" and "ARPACK" sections 58depending on how you installed these 2 packages. 59* Run: `make` 60* Run: `sudo make install` 61* NOTE: Additional adjustments might have to be made to `Makefile-header.osx` 62(that's where you want to look at if you get some linker errors, etc.) 63 64### Windows 65 66Ever thought about using Linux? We heard it's great! :) 67 68## Using `mesh2faust` 69 70`mesh2faust` works as a command line program. The detailed list of options of 71`mesh2faust` can be printed at any time by running: 72 73``` 74mesh2faust --help 75``` 76 77This will print the following list of options: 78 79``` 80--help: prints this help 81--debug: verboses the output of mesh2faust 82--showfreqs: prints the list of frequencies of the calculated modes 83--infile: specifies the path to the volumetric mesh file. Dimensions of the mesh should be in meters. E.g.: --infile file.obj 84--freqcontrol: adds frequency control to the generated model by adding a freq parameter to it 85--name: specifies the name of the generated model (no spaces or special characters). E.g.: --name modelName 86--minmode: specifies the minimum frequency of the lowest mode. E.g.: --minmode 30 87--maxmode: specifies the maximum frequency of the highest mode. E.g.: --maxmode 9000 88--lmexpos: specifies the maximum number of excitation positions in the model. E.g.: --lmexpos 10 89--expos: specifies excitation positions as a list of vertex IDs. E.g.: --expos 89 63 45 90--nfemmodes: specifies the number of modes to be computed for the finite element analysis. E.g.: --nfemmodes 300 91--nsynthmodes: specifies the max number of modes to be added to the physical model and synthesized. E.g.: --nsynthmodes 50 92``` 93 94The only required argument of `mesh2faust` is the 95path to a volumetric mesh saved as an `.obj` file (the "world unit" of this file 96should be in meter). This path must be provided using the `--infile` flag. E.g.: 97 98``` 99mesh2faust --infile 3dObject.obj 100``` 101 102This will create a Faust library file (`.lib`) called `modalModel.lib` in the 103current folder, implementing the modal physical model corresponding to 104`3dObject.obj`, and using the default parameters of `mesh2faust`. 105 106The complexity of the object to analyze (mostly determined by its number of 107 vertices) will greatly impact the duration of this process. For complex objects 108 (e.g., > 3E4 vertices), this can easily take more than 30 mins on a "regular" 109 laptop. 110 111### Physical Model Name 112 113The default name of the Faust physical model generated by `mesh2faust` is 114`modalModel`. This name can be changed using the `--name` flag: 115 116``` 117mesh2faust --infile 3dObject.obj --name toneBar 118``` 119 120will generate a model called `toneBar` saved in a file named `toneBar.lib`. 121 122### Material Properties 123 124The material of the object to turn into a physical model can be configured by 125providing its Young's modulus (in N/m^2), Poisson's ratio (no unit), and 126density (in kg/m^3), in that order, using the `--material` flag as follows: 127 128``` 129mesh2faust --material 70E9 0.35 2700 --infile 3dObject.obj 130``` 131 132These values correspond to the default material (aluminum) used by `mesh2faust`, 133so providing `--material 70E9 0.35 2700` will not change anything. 134 135### Excitation Positions 136 137After the finite element analysis, the number of excitation position (the 138 place where energy is introduced) in the 139physical model is the same as the number of vertices in the provided volumetric 140mesh. Thus, the more vertices, the more excitation positions. The gain of each 141mode in the model is different for each excitation position, so the amount of 142data to be included in the generated Faust file exponentially increases with 143the number of vertices in the mesh. 144 145`mesh2faust` allows to limit the number of excitation positions in the model 146either by providing a maximum number of positions using the `--lmexpos` flag 147followed by an integer number, or by giving a list of vertices ID using the 148`--expos` flag. 149 150``` 151mesh2faust --infile 3dObject.obj --lmexpos 10 152``` 153 154will generate a physical model with 10 selectable randomly distributed 155excitation positions. 156 157``` 158mesh2faust --infile 3dObject.obj --expos 236 589 159``` 160 161will generate a physical model with 2 excitation positions corresponding to 162vertex ID 236 and 589. 163[Vertex IDs can be easily retrieved using meshlab.](https://ccrma.stanford.edu/~rmichon/faustTutorials/#making-physical-models-of-musical-instruments-with-faust) 164 165### Limiting the Number of Modes 166 167In most cases, it is necessary to limit the number of modes of the physical 168model generated by `mesh2faust`, either because they might be outside the 169human hearing range (or above Nyquist) or too many (the more modes in the 170model, the more computation). Several options allow to tune mode selection 171in `mesh2faust` and are presented in this section. 172 173* `--nfemmodes` controls the number of modes computed during the finite 174element analysis. By default, 200 modes are computed (unless the provided mesh 175has less than 200 vertices, in which case the number of computed modes will be 176the same as the number of vertices in the mesh). Modes are computed by frequency, 177so in this case, "200" corresponds to the first 200 modes. The more modes will 178be computed during the analysis, the more time it will take. 179* `--minmode` sets the minimum frequency of the lowest mode to be synthesized. 180Any mode below this frequency will be discarded (default is 20Hz). 181* `--maxmode` sets the maximum frequency of the highest mode to be synthesized. 182Any mode above this frequency will be discarded (default is 10KHz). 183* `--nsynthmodes` controls the number of modes to be synthesized (default is 20). 184Modes are selected by frequency starting at `--minmode`. `--nsynthmodes` is 185adjusted (clipped) to the number of modes available between `--minmode` and 186`-maxmode`. 187 188Typically, `-nfemmodes` should be greater than `--nsynthmodes` since some of the 189modes computed during the finite element analysis will be discarded depending 190on the value of the `--minmode` and `--maxmode`. 191 192``` 193mesh2faust --infile 3dObject.obj --nsynthmodes 50 --nfemmodes 200 --maxmode 12000 194``` 195 196will generate a model with a maximum number of 50 modes and will discard modes 197below 20Hz and above 12KHz. 198 199### Making a Transposable Model 200 201By default, `mesh2faust` generates a "static" model where the frequency of each 202mode is expressed as a frequency in Hz. However, it is possible to generate a 203model where mode frequencies are dynamically calculated in function of a given 204fundamental frequency (mode 0) simply by providing the `--freqcontrol` flag. 205 206Obviously, this will increase the amount of computation of the model and change 207its number of arguments (see [Using Generated Models](#using-generated-models)). 208 209### Debugging 210 211"Debug" mode can be activated simply by providing the `--debug` flag when 212calling `mesh2faust`. This will just make the process more verbose. 213 214Additionally, `--showfreqs` will display the frequency of the computed modes 215in the terminal. 216 217## Using the Generated Models 218 219Faust physical models generated by `mesh2faust` rely on some functions declared 220in the Faust libraries, thus they all import `stdfaust.lib`. 221 222Faust functions implementing the physical models generated by `mesh2faust` look 223like: 224 225``` 226_ : modalModel(exPos,t60,t60DecayRatio,t60DecaySlope) : _ 227``` 228 229The single audio input of the function can be used to provide an excitation 230signal to the model. 231 232### Excitation Position 233 234`exPos` is the excitation position expressed as an integer. For example, if the 235model has 5 excitation positions (e.g., configured using 236[`--expos`](#excitation-positions)), the range of `exPos` will be 0-4 . 237 238### Resonance Duration (t60) 239 240`mesh2faust` currently doesn't allow to the estimate the time of resonance of 241each mode (t60) in function of each other. While this feature will be added 242in a future version, the t60 of the modes of the generated models can be 243configured with 3 different parameters: `t60`, `t60DecayRatio`, and 244`t60DecaySlope` where: 245 246* `t60`: resonance duration of the lowest mode in seconds. 247* `t60DecayRatio`: decay of modes t60s in function of their frequency. The 248range of this parameter is 0-1. If 1, the t60 of the highest mode will be 249close to 0 second. 250* `t60DecaySlope`: controls the slope of the function used to compute the decay 251of modes t60 in function of their frequency. It essentially controls the power 252of this function. So if 1, decay will be linear, if 2, decay will be a power of 2532, etc. 254 255### Dynamic F0 Model 256 257The [Making a Transposable Model](making-a-transposable-model) section shows how to 258make a model with a dynamic fundamental frequency. Models generated using this 259option look like: 260 261``` 262_ : modalModel(freq,exPos,t60,t60DecayRatio,t60DecaySlope) : _ 263``` 264 265Where `freq` is the fundamental frequency ("f0") of the model. 266 267## Extra Help 268 269Feel free to contact Romain Michon if you need extra help: 270rmichon AT ccrma DOT stanford DOT edu. 271 272## License 273 274Copyright 2017, Romain Michon and Sara R. Martin. GRAME - Centre National 275de Creation Musicale (Lyon, France), CCRMA - Stanford University (USA) and 276Norwegian Technical University of Trondheim (Norway). 277 278Project partly funded by Research Council of Norway et NTNU (Norwegian Technical 279University of Trondheim). 280 281Permission is hereby granted, free of charge, to any person obtaining a copy 282of this software and associated documentation files (the "Software"), to deal 283in the Software without restriction, including without limitation the rights to 284use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 285of the Software, and to permit persons to whom the Software is furnished to do 286so, subject to the following conditions: 287 288The above copyright notice and this permission notice shall be included in all 289copies or substantial portions of the Software. 290 291THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 292IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 293FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 294AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 295LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 296OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 297SOFTWARE. 298