TetGen is distributed in its source code (written in C++). The latest version of TetGen is available at http://www.tetgen.org.
Section 3.1 briefly explains how to compile TetGen into an executable program or a library.
Once TetGen is compiled, and assume you have the executable file, tetgen (or tetgen.exe in Windows), you can start testing TetGen with the included example file by following the tutorial in Section 3.2.
TetGen does not have a graphic user interface (GUI). The TetView program can be used to visualize the input and output of TetGen. Alternatively, other popular mesh viewers are supported, see Section 3.3.
The downloaded archive should include the following files:
| README | General information. |
| LICENSE | Copyright notices. |
| tetgen.h | C++ header file of TetGen. |
| tetgen.cxx | C++ source file of TetGen. |
| predicates.cxx | C++ source of Shewchuk’s predicates. |
| makefile | make file for compiling TetGen. |
| CMakeLists.txt | cmake file for compiling TetGen. |
| example.poly | An example input file. |
The file predicates.cxx is a modified C++ version of Shewchuk’s robust geometric predicates http://www.cs.cmu.edu/~quake/robust.html.
To compile TetGen, use a C++ compiler for the system on which TetGen will be used, such as GNU’s g++, or Microsoft C++ on MS Windows systems. TetGen may be compiled into an executable program or a library, which can be embedded into another program.
The easiest way to compile TetGen is to edit and use the included makefile. Before compiling, put all source files, tetgen.h, tetgen.cxx, and predicates.cxx and the makefile into one directory (usually they are), read the makefile, which describes your options, and edit it accordingly.
You should at least specify the C++ compiler and the level of optimization. By default, the GNU C++ compiler (g++) is used, and there is no optimization is used.
Once you have done this, type make to compile TetGen into an executable program or type make tetlib to compile TetGen into a library. The executable file tetgen or the library libtet.a appears in the same directory as the makefile.
Alternatively, the files are usually easy to compile directly on the command line. Assume you’re using g++, first compile the file predicates.cxx to get an object file:
g++ -c predicates.cxx
To compile TetGen into an executable file, use the following command:
g++ -o tetgen tetgen.cxx predicates.o -lm
To compile TetGen into a library, the symbol TETLIBRARY is needed:
g++ -DTETLIBRARY -c tetgen.cxx ar r libtet.a tetgen.o predicates.o
Some additional remarks to get an efficient executable version of TetGen.
Here is an example to get an optimized version of TetGen using GNU’s C++ compiler:
g++ -O3 -DNDEBUG -c predicates.cxx g++ -O3 -DNDEBUG -o tetgen tetgen.cxx predicates.o -lm
As an alternative, one can compile TetGen using cmake (www.cmake.org). It simplifies the compilation of TetGen with different compilers and architectures (Linux, MacOSX, and MS Windows) at the same time.
Using the provided file CMakeLists.txt, the simplest sequence of commands is:
cd <tetgen-directory> mkdir build cd build cmake .. make
When the compilation is finished, you should get both of the executable file tetgen and the library libtet.a under the directory build.
To get a debug version of TetGen, use the following commands
cd <tetgen-directory> mkdir build cd build cmake -DCMAKE_BUILD_TYPE=Debug .. make
The default is cmake -DCMAKE_BUILD_TYPE=Release ...
To specify a compiler, do
CXX=icpc cmake -DCMAKE_BUILD_TYPE=Debug ..
TetGen default uses Shewchuk’s robust geometric predicates which perform exact floating-point arithmetic (predicates.cxx). The arithmetic are based on the IEEE 754 floating-point standard. However, some processors may not default use this standard for floating-point representations and arithmetic. If so, a configuration is needed to correctly execute the predicates. It is described on its website http://www.cs.cmu.edu/~quake/robust.pc.html for details.
Below are my own experience in using Shewchuk’s predicates.
Alternatively, TetGen can use other robust predicates developed in computational geometry, such as the filtered robust predicates in CGAL (http://www.cgal.org). TetGen includes the interface to the CGAL’s predicates in the file predicates.cxx. It uses the following kernel,
#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
In this section, we show how to use CGAL’s predicates in TetGen. The following steps are needed.
cd CGAL-x.y # go to CGAL directory cmake . # configure CGAL make # build the CGAL libraries
If you have any problems in compiling CGAL, please see CGAL’s manual about installation. Once CGAL is compiled, make sure that you get the new file compiler_config.h inside the directory CGAL-x.y/include/CGAL.
BOOST=/opt/local/include GMP_LIB=/opt/local/lib CGAL_INC=$(HOME)/Programs/CGAL/CGAL-4.1/include
BOOST should point to the directory containing the boost library. Version 1.35 or later is required. GMP_LIB should point to the directory containing the library GMP, - the GNU Multiple Precision Arithmetic Library. And CGAL_INC should point to the C++ headers of CGAL’s library.
g++ -I$(BOOST) -I$(CGAL_INC) -DUSE_CGAL_PREDICATES \ -O3 -c predicates.cxx
g++ -O3 -o tetgen tetgen.cxx predicates.o -L$(GMP_LIB) -lgmp
TetGen gives a short list of command line options if it is invoked without arguments (that is, just type tetgen). A brief description of the usage is printed by invoking TetGen with the -h switch:
tetgen -h
The enclosed example file, example.poly, is a simple 3d mesh domain (a PLC), see Figure 24. Try out TetGen using:
tetgen -p example.poly
With the -p switch, TetGen will read the file, i.e., example.poly, and generate its constrained Delaunay tetrahedralization. The resulting mesh is saved in four files: example.1.node, example.1.ele, example.1.face, and example.1.edge, which are a list of mesh nodes, tetrahedra, boundary faces, and boundary edges, respectively. The file formats of TetGen are described in Section 5. The screen output of the above command looks like this:
Opening example.poly.
Delaunizing vertices...
Delaunay seconds: 0.000864
Creating surface mesh ...
Surface mesh seconds: 0.000307
Constrained Delaunay...
Constrained Delaunay seconds: 0.000325
Removing exterior tetrahedra ...
Exterior tets removal seconds: 8.6e-05
Optimizing mesh...
Optimization seconds: 6.4e-05
Writing example.1.node.
Writing example.1.ele.
Writing example.1.face.
Writing example.1.edge.
Output seconds: 0.000663
Total running seconds: 0.002451
Statistics:
Input points: 28
Input facets: 23
Input segments: 44
Input holes: 2
Input regions: 2
Mesh points: 28
Mesh tetrahedra: 68
Mesh faces: 160
Mesh faces on facets: 50
Mesh edges on segments: 44
The above mesh is pretty coarse, and contains many badly-shaped (e.g., long and skinny) tetrahedra. Now try:
tetgen -pq example.poly
The -q switch triggers the mesh refinement such that Steiner points are added to remove badly-shaped tetrahedra. The resulting mesh is contained in the same four files as before. However, now it is a quality tetrahedral mesh whose tetrahedra have no small face angle less than about 14o (the default quality value). The screen output of the above command looks like this:
Opening example.poly.
Delaunizing vertices...
Delaunay seconds: 0.000384
Creating surface mesh ...
Surface mesh seconds: 0.000181
Constrained Delaunay...
Constrained Delaunay seconds: 0.000163
Removing exterior tetrahedra ...
Exterior tets removal seconds: 0.000368
Refining mesh...
Refinement seconds: 0.009291
Optimizing mesh...
Optimization seconds: 0.000517
Writing example.1.node.
Writing example.1.ele.
Writing example.1.face.
Writing example.1.edge.
Output seconds: 0.004716
Total running seconds: 0.015802
Statistics:
Input points: 28
Input facets: 23
Input segments: 44
Input holes: 2
Input regions: 2
Mesh points: 216
Mesh tetrahedra: 689
Mesh faces: 1587
Mesh faces on facets: 430
Mesh edges on segments: 126
Steiner points inside domain: 1
Steiner points on facets: 105
Steiner points on segments: 82
Now try to run:
tetgen -pq1.2V example.poly
TetGen will again generate a quality mesh, which contains more points than the previous one, and all tetrahedra have radius-edge ratio bounded by 1.2, i.e., the element shapes are better than those in the previous mesh. In addition, TetGen prints a mesh quality report (due to the -V switch) which looks as below:
Mesh quality statistics:
Smallest volume: 0.00059866 | Largest volume: 0.09363
Shortest edge: 0.25 | Longest edge: 1.4142
Smallest asp.ratio: 1.3255 | Largest asp.ratio: 10.169
Smallest facangle: 24.898 | Largest facangle: 126.8698
Smallest dihedral: 8.6045 | Largest dihedral: 163.4980
Aspect ratio histogram:
< 1.5 : 23 | 6 - 10 : 26
1.5 - 2 : 364 | 10 - 15 : 1
2 - 2.5 : 480 | 15 - 25 : 0
2.5 - 3 : 248 | 25 - 50 : 0
3 - 4 : 125 | 50 - 100 : 0
4 - 6 : 56 | 100 - : 0
(A tetrahedron's aspect ratio is its longest edge length divided by its
smallest side height)
Face angle histogram:
0 - 10 degrees: 0 | 90 - 100 degrees: 465
10 - 20 degrees: 0 | 100 - 110 degrees: 132
20 - 30 degrees: 188 | 110 - 120 degrees: 54
30 - 40 degrees: 1059 | 120 - 130 degrees: 5
40 - 50 degrees: 1704 | 130 - 140 degrees: 0
50 - 60 degrees: 1865 | 140 - 150 degrees: 0
60 - 70 degrees: 1609 | 150 - 160 degrees: 0
70 - 80 degrees: 1105 | 160 - 170 degrees: 0
80 - 90 degrees: 736 | 170 - 180 degrees: 0
Dihedral angle histogram:
0 - 5 degrees: 0 | 80 - 110 degrees: 1831
5 - 10 degrees: 2 | 110 - 120 degrees: 274
10 - 20 degrees: 150 | 120 - 130 degrees: 193
20 - 30 degrees: 266 | 130 - 140 degrees: 105
30 - 40 degrees: 643 | 140 - 150 degrees: 62
40 - 50 degrees: 1056 | 150 - 160 degrees: 52
50 - 60 degrees: 1213 | 160 - 170 degrees: 24
60 - 70 degrees: 1121 | 170 - 175 degrees: 0
70 - 80 degrees: 946 | 175 - 180 degrees: 0
Instead of using the -q switch to get a finer mesh, one can use the -a switch to impose a maximum volume constraint on the resulting tetrahedra. By doing so, no tetrahedron in the resulting mesh has volume bigger than the specified value after -a. Try to run the following command.
tetgen -pq1.2Va1 example.poly
Now the resulting mesh should contain much more vertices than the previous one. Besides of -q and -a switches, TetGen provides more switches to control the mesh element size and shape. They are described in Section 4.
To compute the Delaunay tetrahedralization and convex hull of the point set of this PLC, try this:
cp example.poly example.node tetgen example.node
The Delaunay tetrahedralization is saved in example.1.node and example.1.ele. The convex hull is represented by a list of triangles in file example.1.face.
All these meshes and Delaunay tetrahedralizations can be visualized by the programs introduced in the next section.
Detailed descriptions of the command line switches and file formats are found in Section 4 and 5.
TetView is a graphic interface for viewing piecewise linear complexes and simplicial meshes. It can read the input and output files of TetGen and display the objects. It also shows other information as well, such as boundary types and materials. The interactive GUI allows the user to manipulate (i.e., rotate, translate, zoom in/out, cut, shrink, etc.) the viewing objects easily through either mouse or keyboard. TetView can save the current window contents into high quality encapsulated postscript files. Most of the figures of this document were produced by TetView.
TetView is freely available from http://www.tetgen.org/tetview.html. You will find a list of precompiled executable versions on different platforms. Download the one corresponding to your system.
To show the PLC in example.poly, first copy the executable file (tetview) to the directory where you have this file. It is loaded by running:
tetview example.poly
And the following command will display the mesh (in files example.1.node, example.1.ele, and example.1.face):
tetview example.1.ele
The instruction for using TetView can be found on the above website.
TetGen can export its tetrahedral mesh into the .mesh format. It can be then visualized by the software Medit, which is freely available from http://www.ann.jussieu.fr/~frey/logiciels.
For viewing mesh under Medit, add a -g switch in the command line. TetGen will additionally output a file named example.1.mesh, which can be read and rendered directly by TetGen. Try running:
tetgen -pg example.poly medit example.1
Alternatively, TetGen can also output its tetrahedral mesh into the .vtk format by adding the switch -k, i.e.,
tetgen -pk example.poly
It will output a file named example.1.vtk. It can then be visualized by the software Paraview: http://www.paraview.org.