TetWild

You can customize the tetrahedralization process using several parameters to balance mesh quality, density, and computation time:

• Envelope size (--epsilon / args.eps_rel): Controls feature preservation. Smaller values preserve features better but increase computation time. Default is b/1000 (where b is the bounding box diagonal).
• Ideal edge length (--ideal-edge-length / args.initial_edge_len_rel): Controls mesh density. Smaller values result in a denser mesh but take longer. Default is b/20.
• Filtering energy (--filter-energy / args.filter_energy_thres): Determines when optimization stops. Higher values stop sooner with less optimization. Default is 10. Note: For complex inputs, do not set this lower than 8.
• Maximum optimization passes (--max-pass / args.max_num_passes): The maximum number of improvement passes. Default is 80.
• Targeted number of vertices (--targeted-num-v / args.target_num_vertices): Attempts to match a specific vertex count with a 5% error tolerance.
• Sizing field (--bg-mesh / args.background_mesh): Provide a background .msh mesh with a values scalar field to control edge lengths via linear interpolation.
• Laplacian smoothing (--is-laplacian / args.smooth_open_boundary): Applies Laplacian smoothing to the surface of output holes/gaps to prevent bumpy surfaces.

You can build TetWild from source using CMake.

Prerequisites

On macOS, you may need to install gmp, mpfr, or CGAL via Homebrew:

brew install gmp
brew install mpfr
# OR
brew install cgal

Build Steps

1. Clone the repository:

git clone https://github.com/Yixin-Hu/TetWild

2. Compile the code:

cd TetWild
mkdir build
cd build
cmake ..
make

Configuration Options

• Boost Dependency: If you do not have Boost installed (required for spdlog), enable the CMake option -DTETWILD_WITH_HUNTER=ON to let CMake download and configure Boost automatically using Hunter.
• ISPC Optimization: To use ISPC for parallel energy computation (which can reduce energy computation time by 50%), install ISPC and set the GTET_ISPC flag to ON in CMakeLists.txt.
• Non-critical warnings: Warnings regarding Matlab or Mosek during the CMake process can be ignored as they are not used by the application.

If you want to avoid file I/O or are already using libigl to load meshes, use the tetwild.h header to call the tetrahedralization directly in your C++ code.

Steps:

1. Include the header: #include <tetwild/tetwild.h>.
2. Configure parameters using a tetwild::Args struct.
3. Call tetwild::tetrahedralization using libigl-style matrices.

Parameter Mapping:

#include <tetwild/tetwild.h>
#include <Eigen/Core>

// ... load your mesh into v_in and f_in using libigl ...

tetwild::Args args;
args.eps_rel = 1e-3;
args.max_num_passes = 80;
// ... configure other args ...

// v_out, t_out, a_out are output matrices (vertices, tetrahedra, and potentially attributes)
// Use libigl-style matrices (e.g., Eigen::MatrixXd or Eigen::MatrixXf)
tetwild::tetrahedralization(v_in, f_in, v_out, t_out, a_out, args);

Use the TetWild executable to run the mesher from the terminal.

Usage:

./TetWild [OPTIONS] input [output]

Positionals:

• input: Required. Input surface mesh in .off/.obj/.stl/.ply format.
• output: Optional. Output tetmesh in .msh format. Defaults to input_file_postfix.msh.

Options:

-h,--help                   Print this help message and exit
--input TEXT REQUIRED       Input surface mesh INPUT in .off/.obj/.stl/.ply format. (string, required)
--output TEXT                Output tetmesh OUTPUT in .msh or .mesh format. (string, optional, default: input_file+postfix+'.msh')
--postfix TEXT               Postfix P for output files. (string, optional, default: '_')
-l,--ideal-edge-length FLOAT ideal_edge_length = diag_of_bbox * L. (double, optional, default: 0.05)
-e,--epsilon FLOAT           epsilon = diag_of_bbox * EPS. (double, optional, default: 1e-3)
--stage INT                  Run pipeline in stage STAGE. (integer, optional, default: 1)
--filter-energy FLOAT        Stop mesh improvement when the maximum energy is smaller than ENERGY. (double, optional, default: 10)
--max-pass INT               Do PASS mesh improvement passes in maximum. (integer, optional, default: 80)
--is-laplacian               Do Laplacian smoothing for the surface of output on the holes of input (optional)
--targeted-num-v INT        Output tetmesh that contains TV vertices. (integer, optional, tolerance: 5%)
--bg-mesh TEXT               Background tetmesh BGMESH in .msh format for applying sizing field. (string, optional)
--save-mid-result            0: save result before optimization, 1: save mid-results during optimization, 2: save result without winding number.
-q,--is-quiet               Mute console output. (optional)
--log TEXT                   Log info to given file.
--level INT                  Log level (0 = most verbose, 6 = off).

./TetWild input.obj output.msh --ideal-edge-length 0.1 --is-laplacian

The DelaunayTetrahedralization class is the core engine for performing Delaunay tetrahedralization within TetWild. It provides methods to initialize the triangulation with surface mesh data, generate voxel points, perform the tetrahedralization process, and output the resulting mesh.

Key methods include:

• init: Sets up the triangulation using surface vertices, faces, and associated tags (face tags, edge tags, and connectivity).
• getVoxelPoints: Generates voxel points within a specified bounding box defined by p_min and p_max.
• tetra: Executes the main tetrahedralization logic, producing BSP (Binary Space Partitioning) elements like vertices, edges, faces, and nodes.
• outputTetmesh: Writes the final tetrahedral mesh to a file.

tetwild::DelaunayTetrahedralization engine;

// Initialize with surface data
engine.init(m_vertices, m_faces, m_f_tags, raw_e_tags, raw_conn_e4v);

// Perform tetrahedralization
engine.tetra(m_vertices, geo_surface_mesh, bsp_vertices, bsp_edges, bsp_faces, bsp_nodes, args, state);

// Output the result
engine.outputTetmesh(m_vertices, cells, "output_file.mesh");