# fTetWild: tetrahedral meshing that survives real-world geometry

> fTetWild is the fast tetrahedral mesher from the Wildmeshing group, built for surface meshes that are noisy, self-intersecting or otherwise untidy rather than for clean synthetic input, and it comes with a GPL-versus-MPL licensing question and a 32 GB memory warning attached. Its companion projects, TetWild and TriWild, cover the original algorithm and the curved-boundary case.

**wildmeshing/fTetWild** — Fast Tetrahedral Meshing in the Wild

- Repository: https://github.com/wildmeshing/fTetWild
- Website: https://yixin-hu.github.io/ftetwild.pdf
- Stars: 609 · Forks: 123
- Language: C++
- License: MPL-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/wildmeshing-ftetwild

## A mesher for geometry that is not clean

fTetWild is the fast tetrahedral mesher described in the SIGGRAPH 2020 paper Fast Tetrahedral Meshing in the Wild by Yixin Hu, Teseo Schneider, Bolun Wang, Denis Zorin and Daniele Panozzo, published in ACM Transactions on Graphics, volume 39, number 4.

The phrase in the wild is the whole thesis. A tetrahedral mesher takes a surface mesh and produces a volume mesh, and the difficulty is that real surface meshes are not clean. They have small self-intersections, holes, spikes, overlapping components and inconsistent winding. A mesher that assumes well-formed input will either fail or produce a volume mesh that a finite element solver cannot use, because the elements near a defect are wrong in ways that are hard to see in a render.

The README's own emphasis is on the algorithm rather than the tool. It says outright that if you are interested in the algorithm details, you should read the paper first, because the project provides plenty of examples and statistics in the paper. There is also a separate note to check the licence first, which is unusual prominence for a licence note and reflects a real difference in how this code is licensed compared to its siblings.

The project also points at two relatives. The original version of the mesher, TetWild, is maintained separately, and TriWild is the 2D version, which can handle both linear and curved constraints, with the note that the ability to mesh curves reliably now comes from TriWild. The family is a research group with a method, a fast implementation, a 2D variant and a data set, and fTetWild is the middle piece.

## Building it with CMake, and the GMP dependency

The code was originally developed on macOS and has been tested on Linux and Windows. The build is CMake, and the macOS instructions are the ones given.

Cloning and compiling is four commands:

```bash
git clone https://github.com/wildmeshing/fTetWild.git
```

```bash
cd fTetWild
mkdir build
cd build
cmake ..
make
```

CMake is in Release mode by default, which is what you want for a mesher.

The one system dependency is GMP, the arbitrary precision arithmetic library, and the README notes you may need to install it before compiling. On macOS that is a Homebrew install:

```bash
brew install gmp
```

On Unix it is a package manager install:

```bash
sudo apt-get install gmp
```

And on Windows the instructions use Conda, with the package named mpir:

```bash
conda install -c conda-forge mpir
```

There is a follow-up for the case where CMake cannot find GMP, in which case you export the environment variables GMP_INC and GMP_LIB pointing at the include and lib folders where you installed it, and the README gives a Conda path as the example. On Windows there is a runtime detail as well: the executable needs the file mpir.dll to be in the same directory as FloatTetwild_bin.exe, so once the code is compiled you copy mpir.dll from, for example, the Conda Library bin directory into the directory containing the executable.

The installation check is the help output:

```bash
./FloatTetwild_bin --help
```

That should print the list of fTetWild parameters, which doubles as the reference for what the tool can be asked to do.

## The pipeline is envelope, ideal edge length and filtering energy

The default behaviour is that you provide a surface triangle mesh and the mesher outputs a tetrahedral mesh, and the customisation options are the three numbers that control how hard the optimiser works.

The envelope of size epsilon defines a region around the surface that the mesher preserves. A smaller envelope preserves features better but takes longer, and the default is b/1000 where b is the length of the diagonal of the bounding box. There is also a Fast Envelope option, enabled by a CMake flag, to reduce running time.

The ideal edge length controls density. Smaller gives a denser mesh and takes longer, with a default of b/20. The filtering energy is the stopping criterion: the mesher stops optimizing the mesh when the maximum energy is smaller than the filtering energy, so a larger value means less optimization and an earlier stop. The energy used is conformal AMIPS, whose range is from 3 to infinity, and the default filtering energy is 10, with a recommendation not to set it smaller than 8 for complex input. If you do not care about quality, a larger filtering energy gets you the result sooner.

The maximum number of optimization passes is the other stopping condition, defaulting to 80. There is also a sizing field, where you can supply a background tetmesh in .msh format carrying vertex scalar field values, and those scalars control edge length, with the values inside an element of the background mesh linearly interpolated. And a smoothing option exists for open regions, because the method can fill gaps and holes but the tetmesh faces on those parts could be bumpy, so Lapacian smoothing can be applied to those faces for a smoother surface.

Two of these defaults are worth questioning before you run anything. Filtering energy of 10 with a floor of 8 for complex input is a quality setting you may want to lower if you are relying on the result for analysis rather than visualisation, and the 80 pass limit means a hard model can stop mid-optimisation without telling you that quality was sacrificed.

## Command line switches and Boolean operations

The tool runs from the command line or through a C++ function wrapper, and the README gives an overview of the switches.

The switches are named and the defaults are stated, which is helpful. The help output is printed under the program name with a usage line for the binary, and the first options are the help flag, the input flag taking a file in .off, .obj, .stl or .ply format, the output flag taking a .msh path whose default is the input file name with a postfix, and a tag flag for marking input faces for a Boolean operation. The input takes the .off, .obj, .stl and .ply formats, and the output is .msh.

The Boolean operation flags are the part that goes beyond ordinary meshing. The --tag switch tags input faces, and the --op switch selects the operation, with 0 for union, 1 for intersection and 2 for difference. That means you can mesh two separately tagged regions and combine their tetrahedral meshes, which is a genuinely useful capability for a tool that has to cope with geometry that came in pieces.

The remaining switches follow the pattern of a tool with a lot of knobs. The ideal edge length can be given absolutely with -a and --la, or relatively with -l and --lr, and the two are mutually exclusive. The help text as reproduced in the README is cut off mid-line at the --lr entry, so the full list is worth reading from the binary itself rather than from the documentation.

## The dataset, the licence and the 32 GB warning

Three things in the README are worth reading carefully before you commit to this tool.

The dataset is provided for research use, with pre-generated tetmeshes and the extracted surface meshes. The 10k input is Thingi10k, and the 10k output is a shared drive link, with a separate link for the input and output figures and the scripts used in the paper. The request attached is to cite the paper when using the pre-generated data.

The licence is MPL-2.0, with the licence file named LICENSE.MPL2 in the repository root. MPL is a file-level copyleft licence, which is a materially different choice from the GPL under which the original TetWild is published, and it is one of the reasons the README tells you to check the licence before anything else.

The memory note is the one that affects whether you can run this at all. The README says the algorithm holds up both in theory and in practice, and that if you do find fTetWild crash, on your laptop, you should test it on a cluster with more resource given, because the most complex model the author tested requires more than 32 GB of memory. That is a specific and unusual admission, and it means the failure mode you are most likely to hit is an out of memory crash rather than a wrong answer.

There is also a correctness note that deserves as much attention as the resource one. The orientation of input faces is as important as the position of their vertices, and the algorithm is faithful to the input face position and orientation, with a pointer to the TetWild important tips for the detail. In other words, if your surface mesh has inconsistent winding, the mesher will faithfully reproduce the inconsistency rather than fix it.

## Where fTetWild is the wrong choice

The first limitation is the input domain. fTetWild is built for messy geometry, and for a clean, well-conditioned surface mesh a straightforward mesher will do the job faster and with less tuning. The envelope, the ideal edge length, the filtering energy and the pass limit all exist because the input is hard, and on easy input they are overhead you do not need.

The second limitation is curved boundaries. The README says TriWild is the 2D version and is able to deal with both linear and curved constraints, and that meshing curves reliably is now possible there. If your analysis needs boundary-conforming curved elements, the 2D sibling is the one that covers it, and the family is designed so you pick the right tool per geometry.

The third limitation is scale and shape of the problem. A mesher that needs more than 32 GB for the most complex model its author tested is a research-grade component, not something you drop into a build pipeline on a modest machine. It belongs in a batch analysis environment where a meshing step that takes minutes or hours is acceptable, not in an interactive tool.

The real alternative is to use the original TetWild, and the difference in approach is the point. TetWild is the first-generation implementation of the same research direction, and the README's framing is that fTetWild is the faster one. So the choice is between the speed of the newer implementation and the lineage of the older one, and for a codebase that already depends on TetWild's behaviour, moving to fTetWild means re-validating every result rather than just recompiling.

The other alternative, for many projects, is not to mesh at all. If your simulation does not need volumetric elements, a surface-only workflow removes the entire question. And if you do need volumes, the third path is a commercial or general-purpose mesher with a support contract behind it, which costs money and buys you predictable behaviour on a bad input model, a pipeline that does not need a 32 GB machine, and someone to call when the result is wrong. For a research group reproducing a paper, fTetWild with its dataset and its statistics is clearly the right instrument. For an engineering team putting meshes into production, the cost profile of the research tool is the thing to weigh.

## Conclusion

Adopt fTetWild if you are doing finite element analysis or simulation and your input geometry is genuinely messy, since the algorithm is built to survive defective input rather than to be fast on clean shapes. Do not adopt it if your geometry is already clean, if you need a curved boundary, since the 2D analogue TriWild covers that case, or if the MPL-2.0 licence conflicts with how you distribute the result. Before you start, check the orientation of your input faces, because the README is explicit that orientation matters as much as vertex position, and budget more than 32 GB of memory for the most complex models the author tested.

## FAQ

### What is fTetWild?

It is a C++ tetrahedral mesher for triangle surface meshes, from the Wildmeshing group, published as Fast Tetrahedral Meshing in the Wild in ACM Transactions on Graphics at SIGGRAPH 2020. It is designed for geometry that is not clean, including self-intersections, holes and spikes, and it is licensed under MPL-2.0.

### How do I build fTetWild?

Clone the repository, create a build directory, run cmake .. and make, with CMake in Release mode by default. You need GMP installed first, through Homebrew on macOS, a package manager on Unix, or Conda on Windows, and if CMake cannot find it you export GMP_INC and GMP_LIB. Verify the build with ./FloatTetwild_bin --help.

### What input and output formats does fTetWild use?

Inputs are triangle surface meshes in .off, .obj, .stl and .ply format, and the output is .mesh or .msh, with .msh as the default. The default .msh records the minimum dihedral angle as an element scalar field, which can be visualised with Gmsh, and PyMesh::MshLoader and PyMesh::MshSaver in the pymesh/ directory read and write those meshes.

### What are the main tuning options in fTetWild?

The envelope of size epsilon, which defaults to b/1000 where b is the bounding box diagonal, the ideal edge length, which defaults to b/20, the filtering energy, which defaults to 10 with a recommendation not to go below 8 for complex input, the maximum number of optimization passes, which defaults to 80, and a sizing field driven by a background tetmesh.

### Does fTetWild need a lot of memory, and how does it handle bad input?

The README says that if fTetWild crashes on your laptop you should test it on a cluster with more resources, because the most complex model the author tested requires more than 32 GB of memory. It also notes that the orientation of input faces matters as much as the position of their vertices, and that the algorithm is faithful to that input orientation.

## Sources

- [Issues](https://github.com/wildmeshing/fTetWild/issues)
- [License: MPL-2.0](https://github.com/wildmeshing/fTetWild/blob/master/LICENSE)
- [Project website](https://yixin-hu.github.io/ftetwild.pdf)
- [README](https://github.com/wildmeshing/fTetWild/blob/master/README.md)
- [wildmeshing/fTetWild on GitHub](https://github.com/wildmeshing/fTetWild)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wildmeshing-ftetwild