Meshtool is a comand-line tool written in C++. It is designed to apply various manipulations to volumetric meshes. The mesh manipulations are referred to as "meshtool modes". This are verbs that describe what meshtool is supposed to do with a mesh. The most important modes are:
- extract : Extract submeshes, surfaces or data from a given mesh.
- insert : Insert mesh information or data from a submesh back into the mesh.
- convert : Convert between CARP, VTK, VTU and MMG binary and ascii formats.
- map : Map index sets (e.g. vertex lists, surfaces) between mesh subsets.
- query : Query various mesh informations like bounding-box, tags, resolution or quality.
- smooth : Smooth surfaces between multiple regions, while preserving mesh quality.
- resample : Increase or reduce resolution of meshes, mesh regions and Purkinje systems.
Most modes require the user to specify an object (e.g. what to extract or insert) followed by mandatory and optional mode options.
The currently supported mesh formats are:
- CARPentry: Ascii and binary formats used by the CARPentry cardidac electrophysiology simulator.
- VTK: Ascii and binary legacy formats used by The Visualization Toolkit (VTK).
- VTU: Binary format used by VTK.
- MMG: Ascii format used by MMG3D.
- OBJ: Wavefront ascii format. Used only for surfaces.
No 3rd-party libraries are required. The code is being built and used under many Linux distros, MacOS and Windows 10 (using WSL).
Meshtool is build (in parallel, no -j option required) via the command
make
The compiled binary is then located in
meshtool/meshtool
The build process can be customized in the my_switches.def
file. This file is autogenerated
by the first build run. There, the user can configure some basic
build settings like:
- Compile in debug or in optimized mode.
- Link statically, if static librarie are availiable.
- Use OpenMP.
- Use (
long
,double
) or (int
,float
) for (mt_int
,mt_real
) - choose between intel, gnu, clang compilers
The meshtool help is called with:
meshtool help
This will display some help information and a list with all currently included modes:
clean quality deform mesh elements to reach a certain quality threshold value
clean topology clean the mesh from bad topology definitions.
convert convert between different mesh formats
collect merge a mesh with datasets
extract data data defined on a mesh is extracted for a given submesh
extract gradient compute gradient and gradient magnitude of a scalar function on a mesh
extract mesh a submesh is extracted from a given mesh based on given element tags
extract myocard the myocardium is extracted from a given mesh
extract surface extract a sequence of surfaces defined by set operations on element tags
extract unreachable extract elements that are unreachable through edge-traversal from a given start vertex
extract volume extract elements inside a given box volume
generate fibres generate default fibers for a given mesh file
generate distancefield generate a distancefield between two surfaces
generate mesh generate a tetrahedral mesh from a list of nested triangle surfaces
insert data data defined on a submesh is inserted back into a mesh
insert meshdata the fiber and tag data of a mesh is inserted into another mesh
insert submesh a submesh is inserted back into a mesh and written to an output mesh
interpolate clouddata interpolate data from a pointcloud onto a mesh
interpolate elemdata interpolate element data from one mesh onto another
interpolate elem2node interpolate data from elements onto nodes
interpolate node2elem interpolate data from nodes onto elements
interpolate nodedata interpolate nodal data from one mesh onto another
itk close Apply closing (i.e. dilate-erode) algorithm to itk data
itk crop remove surrounding whitespace
itk dtype convert datatype
itk extract extract slices of an itk image stack
itk flip flip the voxel data along given axes
itk normalize Normalize voxel spacing
itk padding add padding to voxel data
itk refine refine voxel data
itk sample create an itk image stack from sampeling surfaces
itk smooth Smooth the voxel data
map map .vtx, .surf and .neubc files to the indexing of a submesh
merge surface merge the geometry given by a closed surface mesh into a different mesh
merge meshes merge two meshes, unifying co-located vertices
query bbox print the bounding box of a given mesh
query curvature compute the curvature of a surface
query edges print several statistics related to the mesh edges
query graph print the nodal connectivity graph
query idx print indices in a proximity to a given coordinate
query insidepoint get a point inside a given closed surface
query quality print mesh quality statistics
query tags print the tags present in a given mesh
reindex reindex a mesh to improve matrix bandwidth and cache efficiency
resample mesh resample a tetrahedral mesh to fit a given edge size range
resample purkinje resample purkinje cables as close as possible to a segment size
resample surfmesh resample a triangle mesh to fit a given edge size range
restore mapping restore nodal and element mapping for a submesh w.r.t. a reference mesh
smooth data smooth data defined on a mesh
smooth mesh smooth surfaces and volume of a mesh
smooth surface smooth one or multiple surfaces of a mesh
split generate the split list for given split operations
To get further information about one specific mode, the user can call that mode without any options.
For example:
meshtool extract mesh
generates the output
Mesh extract error: Insufficient parameters provided.
extract mesh: a submesh is extracted from a given mesh based on given element tags
parameters:
-msh=<path> ... (input) path to basename of the mesh to extract from
-tags=tag1,tag2 ... (input) ","-seperated list of tags
-ifmt=<format> ... (optional) mesh input format. may be: carp_txt, carp_bin, vtk, vtk_bin, mmg, purk, stellar
-ofmt=<format> ... (optional) mesh output format. may be: carp_txt, carp_bin, vtk, vtk_bin, vtk_polydata, mmg, stellar
-submsh=<path> ... (output) path to basename of the submesh to extract to
Note that "basename" denotes the file path without the file format extension. If input / output formats are not provided, meshtool will default to CARP ascii format for writing and will default to first binary CARP and then ascii CARP (if no binary files are present) for reading. All options that are not marked as optional, are mandatory. Therefore, the extract mesh mode needs to be called as
meshtool extract mesh -msh=MESH -submsh=SUBMESH -tags=TAGS
By convention, elements hold an additional integer value called element tag. You can extract submeshes by specifying a set of tags that should be extracted as a new submesh.
# store tags into variable (optional)
TAGS=125,150,175,225,250,275,325,350,375
# call meshtool
meshtool extract submesh -msh=TBunnyC -submsh=TBunnyC_i -tags=$TAGS
The following image shows the original mesh and the extracted myocardial submesh:
The extraction of complex surfaces can be expressed as set operations on the surfaces of the individual tags. For instance, the epicardial and endocardial surfaces of a heart immersed in a bath / blood pool, can be extracted by intersecting the myocardial surface with respectively the bath or the blood pools.
# store tags into variable (optional)
MYOCARD=125,150,175,225,250,275,325,350,375
BLOODPOOLS=500,600
BATH=400
# call meshtool
meshtool extract surface -msh=TBunnyC -surf=TBunnyC.epi,TBunnyC.endo -op=$MYOCARD:$BATH;$MYOCARD:$BLOODPOOLS
With the -surf
parameter we specify (comma-seperated) the names of the two surfaces we generate. The -op
parameter
defines the set operations: The colon (:) character specifies that we compute the set intersection between the left hand
side and the right hands side tag sets, the semicolon (;) character is the delimiter of the two set operations.
Optionally, the user can also specify the -ofmt
parameter to not only generate a surface
definition file but additionally a full surface mesh (vertices, elements and fibers) in the
specified file format.
A mesh can be smoothed with meshtool in two ways: Either by selecting entire tag regions
with meshtool smooth mesh
, or by specifying surfaces via surface files via meshtool smooth surface
.
In this example we will show how entire tag regions of a mesh are smoothed:
meshtool smooth mesh -msh=LV.vtk -tags=* -thr=0.98 -iter=150 -smth=0.16 -outmsh=LV.smth.vtk
Using *
for the tags, specifies that all tags shall be smoothed, with smooth interfaces
between the individual tag regions (see the help by typing meshtool smooth mesh
for more information).
The quality threshold is set to 0.98, as we want to sacrifice some mesh quality for more
smoothness. The smoothness coefficient of 0.16 is of moderate value, the coefficient should
be between 0.1 and 0.3.
The discretization size of a surface or volumetric mesh can be changed with the resampling mode of meshtool. The user can specify minimum and/or maximum edge lengths.
For volumetric meshes, veshtool will first collapse edges smaller than the minimum edge length and then split edges larger than the maximum edge length.
For surface meshes, meshtool will iteratively collapse and split edges until either no edges can be updated anymore or all edges are inside the specified length interval.
In the following example we have resampled the surface of a mesh with an average edge length of approx. 250 um to approx 700 um and 1300 um. The commands were
meshtool resample surfmesh -msh=TBC.surfmesh -min=500 -outmsh=TBC.surfmesh.crs -surf_corr=0.95
meshtool resample surfmesh -msh=TBC.surfmesh -min=1000 -outmsh=TBC.surfmesh.crsbig -surf_corr=0.95
The -surf_corr
parameter specifies how closely the surface form should be preserved. The
value denotes the threshold correlation value of two surface normal vectors of an edge that can
be collapsed.
Example of more advaced workflows with meshtool can be found here.
In addition to this documentation, there exists a doxygen documentation of most code parts. It can be build with
make doxygen
and is located in the doxydoc
folder.
The code is organized as a set of utility functions and classes located in meshtool/utils
.
This utility building blocks are then used in the meshtool modes, located in meshtool/modes
, to implement
certain mesh manipulations. The utilities are designed in a general way to encourage recombination in
different ways. Some recombinations are located in the standalone tools in meshtool/standalones
.