Introduction

The tetGen process is a simplified wrapper to the TetGen

"TetGen is a program to generate tetrahedral meshes of any 3D polyhedral domains. TetGen generates exact constrained Delaunay tetrahedralizations, boundary conforming Delaunay meshes, and Voronoi partitions." Manual [1] "TetGen 1.6 Manual" - Si, 2020 [PDF]

Currently the process is limited to a few features of the tetGen, yet still a powerfull tool for generating constrained and embedded tetrahedral meshes data. The mesh functionalities are divided in three:

buildTetMesh() Generating tetrahedral meshes from a bounding box and/or surfaces
buildMeshGroups() Segmenting any mesh using a set of surface using a flood-fill approach
refineTetMesh()Refining tetrahedral meshes regions/boundaries and adding points

Generating the mesh data (point coordinates, element indices, boundary triangles/markers)

tetgen.buildTetMesh(points, triangles, bboxMin, bboxMax, maxElementVolume, mesh)
Description:	Given the set of points, triangles, bounding box and element maximum volume, generates the data for a tetrahedral mesh (point coordinates, element indices) respecting its input constraints. Optionally if a empty mesh is given, setup the mesh points and elements.
Parameters:	points	A table of 3D points in the form 'points[i] = {x, y, z}'. Can be 'nil' if both 'bboxMin' and 'bboxMax' are passed.
	triangles	A table of triangles' point indices in the form 'triangles[i] = {i1, i2, i3}', with indices starting from 1 and less or equal to the number of points. Triangles must not have self-intersection or duplicated/overlapping edges. Can be 'nil' if both 'bboxMin' and 'bboxMax' are passed.
	bboxMin	A table in the form {xmin, ymin, zmin} representing the axis aligned bounding box minimum. All points should be strictly inside this box. Can be 'nil' if 'points' and 'triangles' form a closed volume
	bboxMax	A table in the form {xmax, ymax, zmax} representing the axis aligned bounding box maximum. All points should be strictly inside this box. Can be 'nil' if 'points' and 'triangles' form a closed volume
	maxElementVolume	A number strictly greater than zero specifying the maximum element volume. Can be 'nil'.
	mesh	(Optional) A mesh object or string mesh name. When set, the function only returns the number of points and number of elements instead of tables.
Returns:	- table: points (x, y, z) or integer: number of points, - table: element indices (i1, i2, i3, i4) or integer: number of elements, - table: boundary triangles (i1, i2, i3) - internal and bounding box, - table: boundary triangle marker (integer)

IMPORTANT: point and triangle data must not have duplicates, self-intersection or overlapping edges. otherwise the generator will fail.

Sample 1: Generates the mesh data for the unit cube (bounding box) and max element volume 0.1

local points, elements, btri, btrimarker = tetgen.buildTetMesh(nil, nil, {0,0,0}, {1,1,1}, 0.1)

Sample 2: Generates the mesh data for the unit cube with 10 random points as constraint and setup the data to the mesh with id 'mesh'

local points = {}
for i=1, 10 do
  table.insert(points, {math.random(), math.random(), math.random()})
end
 
local npoints, nelements, btri, btrimarker = tetgen.buildTetMesh(points, nil, {0,0,0}, {1,1,1}, nil, 'mesh')

Sample 3: Generates the mesh data for the unit cube with one triangle as constraint and max element volume 0.05

local points = { {0.1, 0.4, 0.8}, {0.5, 0.5, 0.1}, {0.9, 0.5, 0.3}}
local triangles = {{1,2,3}}
 
local points, elements = tetgen.buildTetMesh(points, nil, {0,0,0}, {1,1,1}, 0.05)

Sample 4: Generates the mesh data for a closed volume given by points and triangles data with max element volume 0.02 and setup the data to the mesh m

local points = {...}
local triangles = {...}
 
local m = modelData:mesh('mesh')
 
local npoints, nelements = tetgen.buildTetMesh(points, triangles, nil, nil, 0.02, m)

tetgen.buildMeshGroups(mesh, cellAttribAccessor, surfacesPoints, surfacesTriangles, bboxMin, bboxMax, groupingThreshold, gridSize) tetgen.buildMeshGroups(points, cells, surfacesPoints, surfacesTriangles, bboxMin, bboxMax, groupingThreshold, gridSize)
Description:	Given a mesh (points/cells), a set o surfaces and a bounding box, find the discretized regions and sets each cell attribute according to the region its center lies.
Parameters:	mesh	A mesh object or a string with the mesh id.
	cellAttribAccessor	A cellAttribAccessor where the region marker will be set (scalar value).
	points	A table of 3D points in the form 'points[i] = {x, y, z}'.
	triangles	A table of triangles' point indices in the form 'triangles[i] = {i1, i2, i3}', with indices starting from 1 and less or equal to the number of points.
	surfacesPoints	A table of surfaces points, each entry 'surfacesPoints[i]' is a table of 'surfPoints' where 'surfPoints[j] = {x, y, z}'
	surfacesTriangles	A table of surfaces triangle indices, each entry 'surfacesTriangles[i]' is a table of 'surfTri' where 'surfTri[j] = {i1, i2, i3}'
	bboxMin	A table in the form {xmin, ymin, zmin} representing the axis aligned bounding box minimum.
	bboxMax	A table in the form {xmax, ymax, zmax} representing the axis aligned bounding box maximum.
	groupingThreshold	(Optional) A number in [0, 0.5] used as a percentage threshold for removing outliers (from discretization) when grouping different regions. Default = 0
	gridSize	(Optional) A number 's' or a triplet '{sx, sy, sz}' with each entry in [8, 4096] defining the grid discretization for the flood-fill. Default = 256 Smaller values increase the step effect in the regions detection. Large values increase the memory usage and also require tighter surfaces to avoid joining regions by leaks (non-watertight surfaces).
Returns:	- table: classes (one entry per cell) or integer: number of cells set with cellAttribAccessor, - table: group mapping (with size equal to the number of regions). Entries with the same value can be considered the same group according to the groupingThreshold.

When the version of the function receiving a mesh/cellAttribAccessor is used, it return the number of classes instead of a table of classes

Sample 1: build mesh groups from a bounding box and surfaces directly setting the regions with an accessor

-- get mesh object
local m = modelData:mesh('mesh')
 
-- Create a new cell attribute to hold the region mark
local newInfo = ValueInfo('cell attribute', {id = 'CellGroup'})
assert(m:addCellAttributeSet(newInfo) == true)
local cgacc = m:cellAttributeAccessor('CellGroup')
 
-- Surfaces splitting the bounding box in regions
local surfPoints1 = {...}
local surfTri1 = {...}
 
local surfPoints2 = {...}
local surfTri2 = {...}
 
local bboxMin = {0,0,0}
local bboxMax = {1,1,1}
 
-- Setup regions (flood-fill approach)
local cclass, cgroup = tetgen.buildMeshGroups(m, cgacc, {surfPoints1, surfPoints2}, {surfTri1, surfTri2}, bboxMin, bboxMax, 0.05, 8)

tetgen.refineTetMesh(mesh, cellAttribAccessor, pointsAdd, regionVol, boundaryTriangles, boundaryMarkers, boundaryMaxEdgeSize) tetgen.refineTetMesh(points, cells, cellAttribute, pointsAdd, regionVol, boundaryTriangles, boundaryMarkers, boundaryMaxEdgeSize)
Description:	Given the set of points, triangles, bounding box and element maximum volume, generates the data for a tetrahedral mesh (point coordinates, element indices) respecting its input constraints. Optionally if a empty mesh is given, setup the mesh points and elements.
Parameters:	mesh	A mesh object or a string with the mesh id. Should be a tetrahedral only mesh.
	cellAttribAccessor	A cellAttribAccessor where the region marker is set (scalar value). In case no region is set, it can be 'nil'.
	points	A table of 3D points in the form 'points[i] = {x, y, z}'.
	cells	A table of tetrahedrons in the form 'cells[i] = {i1, i2, i3, i4}'.
	cellAttribute	A table of integers - region attribute per cell. Can be 'nil'. region should be a integer greater or equal to 0'.
	pointsAdd	A table of 3D points to be added to the mesh in the form 'pointsAdd[i] = {x, y, z}'. Can be 'nil'
	regionVol	A table with maximum volume per region marker. It should be the size of 'maximumMarkerValue + 1', can be 'nil'. Zero volume entry is ignored.
	boundaryTriangles	A table with boundary triangle points indices, with 'boundaryTriangles[i] = { i1, i2, i3}'. Can be 'nil'
	boundaryMarkers	A table with size equal to 'boundaryTriangles' size, where each entry 'boundaryMarkers[j]' is a integer greater or equal to 0.
	boundaryMaxEdgeSize	A table with size equal to 'maximumBoundaryMarker + 1' defining the maximum edge size for each boundary marker. Can be 'nil'. Zero edge size entry is ignored.
Returns:	- table: points (x, y, z) or integer: number of points, - table: element indices (i1, i2, i3, i4) or integer: number of elements, - table: cellAttribute or integer: number of regions table: boundaryTriangles table: boundarymarkers

When the version of the function receiving a mesh/cellAttribAccessor is used, it return the number of points, cells and regions instead of tables.

Sample 1: Refine mesh with new points, maximum volume set per region and maximum edge size set per boundary

-- get mesh object
local m = modelData:mesh('mesh')
 
--get the cell accessor object
local cgacc = m:cellAttributeAccessor('CellGroup')
 
-- create additional points to be inserted in the mesh
local pointsAdd = {}
  for i=1, 4 do
        table.insert(pointsAdd, {math.random(), math.random(), math.random()})
  end
 
-- assuming the mesh has two regions markers '0', '1'
local regionVol = {0, 0.0005}
-- assume the mesh has seven boundaries (6 from bounding box, 1 from internal)
local bEdgeSize = {0, 0, 0, 0.04, 0, 0, 0}
-- 'btri' and 'bmtri' are the boundary triangles and markers manually set or from original mesh generation
local nd, cd, nr, btri, bmtri = tetgen.refineTetMesh(m, cgacc, pointsAdd, regionVol, btri, bmtri, bEdgeSize)

GeMA project main page