Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
💡💡💡 **If you are interested in the algorithm details, please refer to our [paper](https://arxiv.org/abs/1908.03581) first. We provide plenty of examples and statistics in the paper.**
💡💡💡 **Check our license first.**
💡💡💡 **Our algorithm is robust both in theory and in practice. If you do find fTetWild crash (on your laptop), please test it (on cluster) with more resource given. The most complex model I tested requires >32GB memory.**
💡💡💡 **The orientation of input faces is as important as the position of their vertices. Our algorithm is faithful to the input face position and orientation [check Tetwild](https://github.com/Yixin-Hu/TetWild#important-tips)**
## Dataset
Here is pre-generated tetmeshes and the extracted surface meshes for research-purpose usage. **Please kindly cite our paper when using our pre-generated data.**
- Compile the code using cmake (default in Release mode):
```bash
cd fTetWild
mkdir build
cd build
cmake ..
make
```
You may need to install `gmp` before compiling the code. You can install them via
-[homebrew](https://brew.sh/) on mac:
```bash
brew install gmp
```
- Package manager on Unix:
```
sudo apt-get install gmp
```
-[Conda](https://anaconda.org) on Windows:
```
conda install -c conda-forge mpfr
```
- Check the installation:
```bash
./FloatTetwild_bin --help
```
This command should show a list of fTetWild parameters.
## Usage
### Input/output Format
The inputs of our software are triangle surface meshes in `.off/.obj/.stl/.ply` format.
We support `.mesh/.msh` format output. The default output format is `.msh` with minimum dihedral angle recorded as element scalar field, which can be visualized by software [Gmsh](http://gmsh.info/). You can use `PyMesh::MshLoader` and `PyMesh::MshSaver` in `pymesh/` for read and write `.msh` meshes.
### Features
Our software is quite easy to use. Basically, users only need to provide a surface triangle mesh as input and our mesher would output a tetrahedral mesh by using default settings. If you want to customize your own tetmeshes, we also provide some options.
- Envelope of size *epsilon*
Using smaller envelope preserves features better but also takes longer time. The default value of *epsilon* is *b/1000*, where *b* is the length of the diagonal of the bounding box.
- Ideal edge length
Using smaller ideal edge length gives a denser mesh but also takes longer time. The default ideal edge length is *b/20*
- Filtering energy
Our mesher stops optimizing the mesh when maximum energy is smaller than filtering energy. Thus, larger filtering energy means less optimization and sooner stopping. If you do not care about quality, then give a larger filtering energy would let you get the result earlier. The energy we used here is conformal AMIPS whose range is from 3 to +inf. The default filtering energy is 10.
💡 We suggest not to set filtering energy smaller than 8 for complex input.
- Maximum number of optimization passes
Our mesher stops optimizing the mesh when the maximum number of passes is reached. The default number is 80.
- Smoothing open regions
Our method can fill gaps and holes but the tetmesh faces on those parts could be bumpy. We provide users an option to do Lapacian smoothing on those faces to get a smoother surface.
### Command Line Switches
Our software supports usage via command line or via a C++ function wrapper. Here is an overview of all command line switches:
--level INT Log level (0 = most verbose, 6 = off).
-q,--is-quiet Mute console output. (optional)
--skip-simplify
--not-sort-input
--correct-surface-orientation
--envelope-log TEXT
--smooth-open-boundary
--manifold-surface
--csg TEXT:FILE json file containg a csg tree
--max-threads UINT maximum number of threads used
```
<!--### Tips
TODO :)-->
## Acknowledgements
We used several useful libraries in our implement, testing, and rendering listed as follows. We would like to especially thank their authors for their great work and publishing the code.
