TetGen.jl

TetGen

TetGen

The TetGen.jl package is a Julia wrapper for the C++ project TetGen. This wrapper enables TetGen based tetrahedral meshing, and (constrained) 3D Delaunay and Voronoi tesselation.

If you find TetGen useful, please consider citing Hang Si: "TetGen, a Delaunay-Based Quality Tetrahedral Mesh Generator" ACM Trans. on Mathematical Software. 41 (2), 2015 http://doi.acm.org/10.1145/2629697.

License

When installing TetGen.jl, a compiled library version of the TetGen library will be downloaded from the TetGen_jll.jl repository. This library is bound to the Affero Gnu Public License v3 (AGPL), but the bindings to the library in this package, TetGen.jl, are licensed under MIT. This means that code using the TetGen library via the TetGen.jl bindings is subject to TetGen's licensing terms. If you distribute covered work, i.e. a program that links to and is distributed with the TetGen library, then that distribution falls under the terms of the AGPLv3.

See the TetGen Licensing FAQ for other options.

Example using GeometryBasics datatypes

using TetGen
using GeometryBasics
using GeometryBasics: Mesh, QuadFace

# Construct a cube out of Quads
points = Point{3, Float64}[
    (0.0, 0.0, 0.0), (2.0, 0.0, 0.0),
    (2.0, 2.0, 0.0), (0.0, 2.0, 0.0),
    (0.0, 0.0, 12.0), (2.0, 0.0, 12.0),
    (2.0, 2.0, 12.0), (0.0, 2.0, 12.0)
]

facets = QuadFace{Cint}[
    1:4,
    5:8,
    [1,5,6,2],
    [2,6,7,3],
    [3, 7, 8, 4],
    [4, 8, 5, 1]
]

markers = Cint[-1, -2, 0, 0, 0, 0]
# attach some additional information to our faces!
mesh = Mesh(points, meta(facets, markers=markers))
result = tetrahedralize(mesh, "vpq1.414a0.1")

using GLMakie

GLMakie.mesh(normal_mesh(result), color=(:blue, 0.1), transparency=true)
GLMakie.wireframe!(result)

Plotted with Makie:

Example using plain Julia arrays

using TetGen
let
    tetunsuitable!() do pa,pb,pc,pd
        vol=det(hcat(pb-pa,pc-pa,pd-pa))/6
        center=0.25*(pa+pb+pc+pd)-[0.5,0.5,0.5]
        vol> 0.05*norm(center)^2.5
    end

    input=TetGen.RawTetGenIO{Cdouble}()
    input.pointlist=[0 0 0;  
                     1 0 0;
                     1 1 0;
                     0 1 0;
                     0 0 1;  
                     1 0 1;
                     1 1 1;
                     0 1 1]'

    TetGen.facetlist!(input,[1 2 3 4;
                             5 6 7 8;
                             1 2 6 5;
                             2 3 7 6;
                             3 4 8 7;
                             4 1 5 8]')
    tetrahedralize(input, "pQa")
end

Output:

RawTetGenIO(
numberofpoints=169,
numberofedges=27,
numberoftrifaces=112,
numberoftetrahedra=809,
pointlist'=[0.0 1.0 … 0.500059730245037 0.4996534431688176; 0.0 0.0 … 0.5074057466787957 0.49707528530503103; 0.0 0.0 … 0.5033015055704277 0.4953177845338027],
tetrahedronlist'=Int32[34 47 … 15 143; 6 24 … 143 15; 58 52 … 154 150; 70 73 … 168 168],
trifacelist'=Int32[3 58 … 99 22; 19 6 … 22 8; 78 70 … 158 158],
trifacemarkerlist'=Int32[-1, -1, -1, -1, -1, -1, -1, -1, -1, -1  …  -1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
edgelist'=Int32[3 5 … 70 157; 18 24 … 6 32],
edgemarkerlist'=Int32[-1, -1, -1, -1, -1, -1, -1, -1, -1, -1  …  -1, -1, -1, -1, -1, -1, -1, -1, -1, -1],
)

Contributing

Code of conduct

tetrahedralize(mesh; ...)
tetrahedralize(mesh, command; marker, holes)

Tetrahedralize a mesh of polygons with optional facet markers. Returns a mesh of tetrahdra.

With GeometryBasics version 0.4, the input mesh has to be a GeometryBasics.Mesh with possible metadata. With GeometryBasics version 0.5, the input mesh has to be a GeometryBasics.MetaMesh.

Default command is "Qp", creating the Delaunay triangulation of the point set. See the list of possible flags in the documentation of tetrahedralize(::RawTetGenIO, flags).

voronoi(points::Vector{Point{3, T}})  where {T <: AbstractFloat}

Create voronoi diagram of point set.

Returns a mesh of triangles.

struct RawFacet{T}

A complex facet as part to the input to TetGen.

• polygonlist::Vector{Vector{Int32}}: Polygons given as arrays of indices which point into the pointlist array describing the input points.

• holelist::Matrix: Array of points given by their coordinates marking polygons describing holes in the facet.

mutable struct RawTetGenIO{T}

A structure for transferring data into and out of TetGen's internal representation.

The input of TetGen is either a 3D point set, or a 3D piecewise linear complex (PLC), or a tetrahedral mesh. Depending on the input object and the specified options, the output of TetGen is either a Delaunay (or weighted Delaunay) tetrahedralization, or a constrained (Delaunay) tetrahedralization, or a quality tetrahedral mesh.

A piecewise linear complex (PLC) represents a 3D polyhedral domain with possibly internal boundaries(subdomains). It is introduced in [Miller et al, 1996]. Basically it is a set of "cells", i.e., vertices, edges, polygons, and polyhedra, and the intersection of any two of its cells is the union of other cells of it.

The 'RawTetGenIO' structure is a collection of arrays of data, i.e., points, facets, tetrahedra, and so forth. All data are compatible to the representation in C++ and can be used without copying.

• pointlist::Matrix: 'pointlist': Array of point coordinates with size(pointlist,1)==3.

• pointattributelist::Matrix: 'pointattributelist': Array of point attributes. The number of attributes per point is determined by size(pointattributelist,1)

• pointmtrlist::Matrix: 'pointmtrlist': An array of metric tensors at points.

• pointmarkerlist::Vector{Int32}: 'pointmarkerlist': An array of point markers; one integer per point.

• tetrahedronlist::Matrix{Int32}: 'tetrahedronlist': An array of tetrahedron corners represented by indices of points in pointlist. Unless option -o2 is given, one has size(tetrahedronlist,1)==4, i.e. each column describes the four corners of a tetrahedron. Otherwise, size(tetrahedronlist,1)==10 and the 4 corners are followed by 6 edge midpoints.

• tetrahedronattributelist::Matrix: 'tetrahedronattributelist': An array of tetrahedron attributes.

• tetrahedronvolumelist::Vector: 'tetrahedronvolumelist': An array of constraints, i.e. tetrahedron's volume; Input only. This can be used for triggering local refinement.

• neighborlist::Matrix{Int32}: 'neighborlist': An array of tetrahedron neighbors; 4 ints per element. Output only.

• facetlist::Array{RawFacet{T}, 1} where T: 'facetlist': An array of facets. Each entry is a structure of facet.

• facetmarkerlist::Vector{Int32}: 'facetmarkerlist': An array of facet markers; one int per facet.

• holelist::Matrix: 'holelist': An array of holes (in volume). Each hole is given by a point which lies strictly inside it.

• regionlist::Matrix: 'regionlist': An array of regions (subdomains). Each region is given by a seed (point) which lies strictly inside it. For each column, the point coordinates are at indices [1], [2] and [3], followed by the regional attribute at index [4], followed by the maximum volume at index [5].

  ote that each regional attribute is used only if you select the 'A' switch, and each volume constraint is used only if you select the 'a' switch (with no number following).

• facetconstraintlist::Matrix: 'facetconstraintlist': An array of facet constraints. Each constraint specifies a maximum area bound on the subfaces of that facet. Each column contains a facet marker at index [1] and its maximum area bound at index [2]. Note: the facet marker is actually an integer.

• segmentconstraintlist::Matrix: 'segmentconstraintlist': An array of segment constraints. Each constraint specifies a maximum length bound on the subsegments of that segment. Each columb consists of the two endpoints of the segment at index [1] and [2], and the maximum length bound at index [3]. Note the segment endpoints are actually integers.

• trifacelist::Matrix{Int32}: 'trifacelist': An array of face (triangle) corners.

• trifacemarkerlist::Vector{Int32}: 'trifacemarkerlist': An array of face markers; one int per face.

• edgelist::Matrix{Int32}: 'edgelist': An array of edge endpoints.

• edgemarkerlist::Array{Int32}: 'edgemarkerlist': An array of edge markers.

Create RawTetGenIO structure with empty data.

facetlist!(
    tio::RawTetGenIO{T},
    facets::AbstractMatrix
) -> RawTetGenIO

Set list of input facets from AbstractMatrix desribing polygons of the same
size (e.g. triangles)

facetlist!(
    tio::RawTetGenIO{T},
    facets::Vector
) -> RawTetGenIO

Set list of input facets from a vector of polygons of different size

numberofedges(tio::RawTetGenIO{T}) -> Int64

Number of edges in tetrahedralization

numberofpoints(tio::RawTetGenIO{T}) -> Int64

Number of points in tetrahedralization

numberoftetrahedra(tio::RawTetGenIO{T}) -> Int64

Number of tetrahedra in tetrahedralization

numberoftrifaces(tio::RawTetGenIO{T}) -> Int64

Number of triangle faces in tetrahedralization

surfacemesh(tgio::RawTetGenIO) -> GeometryBasics.Mesh

Create GeometryBasics.Mesh from the triface list (for quick visualization purposes using Makie's wireframe).

tetrahedralize(
    input::RawTetGenIO{Float64},
    flags::String
) -> RawTetGenIO{Float64}

Tetrahedralize input.

  flags: -pYrq_Aa_miO_S_T_XMwcdzfenvgkJBNEFICQVh 
    -p  Tetrahedralizes a piecewise linear complex (PLC).
    -Y  Preserves the input surface mesh (does not modify it).
    -r  Reconstructs a previously generated mesh.
    -q  Refines mesh (to improve mesh quality).
    -R  Mesh coarsening (to reduce the mesh elements).
    -A  Assigns attributes to tetrahedra in different regions.
    -a  Applies a maximum tetrahedron volume constraint.
    -m  Applies a mesh sizing function.
    -i  Inserts a list of additional points.
    -O  Specifies the level of mesh optimization.
    -S  Specifies maximum number of added points.
    -T  Sets a tolerance for coplanar test (default 1e-8).
    -X  Suppresses use of exact arithmetic.
    -M  No merge of coplanar facets or very close vertices.
    -w  Generates weighted Delaunay (regular) triangulation.
    -c  Retains the convex hull of the PLC.
    -d  Detects self-intersections of facets of the PLC.
    -z  Numbers all output items starting from zero.
    -f  Outputs all faces to .face file.
    -e  Outputs all edges to .edge file.
    -n  Outputs tetrahedra neighbors to .neigh file.
    -v  Outputs Voronoi diagram to files.
    -g  Outputs mesh to .mesh file for viewing by Medit.
    -k  Outputs mesh to .vtk file for viewing by Paraview.
    -J  No jettison of unused vertices from output .node file.
    -B  Suppresses output of boundary information.
    -N  Suppresses output of .node file.
    -E  Suppresses output of .ele file.
    -F  Suppresses output of .face and .edge file.
    -I  Suppresses mesh iteration numbers.
    -C  Checks the consistency of the final mesh.
    -Q  Quiet:  No terminal output except errors.
    -V  Verbose:  Detailed information, more terminal output.
    -h  Help:  A brief instruction for using TetGen.

tetrahedralize(stlfile, flags)

Tetrahedralize stl file.

volumemesh(
    tgio::RawTetGenIO
) -> GeometryBasics.Mesh{_A, _B, GeometryBasics.TriangleFace{Int32}, _C, _D, Vector{GeometryBasics.TriangleFace{Int32}}} where {_A, _B<:Real, _C, _D<:(Tuple{var"#s11", Vararg{Union{AbstractVector{T}, GeometryBasics.FaceView{T, AVT} where AVT<:AbstractVector{T}} where T}} where var"#s11"<:AbstractArray{GeometryBasics.Point{_A, _B}, 1})}

Create GeometryBasics.Mesh of all tetrahedron faces (for quick visualization purposes using Makie's wireframe).

tetunsuitable!(unsuitable; check_signature)

Set tetunsuitable function called from C wrapper. Setting this function is valid only for one subsequent call to tetrahedralize. The function to be passed has the signature

unsuitable(p1::Vector{Float64},p2::Vector{Float64},p3::Vector{Float64},p4::Vector{Float64})::Bool

where p1...p4 are 3-Vectors describing the corners of a tetrahedron, and the return value is true if its volume is seen as too large.

Mesh{Tetrahedron}(result::JLTetGenIO)

Extracts the tetrahedral mesh from tetgenio. Can also be called with extra information, e.g.:

    Mesh{Tetrahedron{Float32}}(tetio)
    NDim = 3; T = Float64; PointType = MyPoint{3, Float64}; Edges = 4
    Mesh{Simplex{NDim, T, Edges, PointType}}(tetio)

Mesh{Triangle}(result::JLTetGenIO)

Extracts the triangular surface mesh from tetgenio. Can also be called with extra information, e.g.:

    Mesh{Triangle3d{Float32}}(tetio)
    NDim = 3; T = Float64; PointType = MyPoint{3, Float64}; Edges = 3
    Mesh{Ngon{NDim, T, 3, PointType}}(tetio)

Error struct for TetGen

Show TetGen error, messages have been lifted from TetGen

Tetunsuitable function called from C wrapper

Trivial Julia tetunsuitable function

tetrahedralize(input, command)

Tetrahedralization with error handling

tetunsuitable!(unsuitable; check_signature)

Set tetunsuitable function called from C wrapper. Setting this function is valid only for one subsequent call to tetrahedralize. The function to be passed has the signature

unsuitable(p1::Vector{Float64},p2::Vector{Float64},p3::Vector{Float64},p4::Vector{Float64})::Bool

where p1...p4 are 3-Vectors describing the corners of a tetrahedron, and the return value is true if its volume is seen as too large.