Stmes 8000 h is a library implementing the paper "4D Space-Time Delaunay Meshing for Medical Images" by Panagiotis Foteinos and Nikos Chrisochoides. It was devised as part of my Bachelor's Thesis at the RWTH Aachen University.
Through the use of CGAL's efficient implementation of Delaunay triangulations, stmesh is able to run significantly faster than the original implementation. The library is written in C++ and offers the stmesher command line tool to mesh 4D geometries.
In addition to meshing functionality, generic pre- and postprocessing tools for 4D meshes are provided, that can be used independently of the mesher employed. This includes a Python module to evaluate continuous simplex space-time simulation results at arbitrary space-time points within the domain.
This project is designed to be used with devcontainers and in particular works best in VSCode.
To build the project, firstly install the devcontainer extension and open the project in VSCode. You should then be prompted to open the project in a devcontainer.
Once the devcontainer is running, you can build the project by first configuring the project with CMake:
cmake --preset unixlike-clang-debugThen build the project with:
cmake --build --preset unixlike-clang-debug --parallelThe stmesher binary will be located in the out/build/unixlike-clang-debug/src/stmesher directory.
In order to run stmesher on HPC systems, which may sometimes be necessary due to its memory requirement, it is advised to use apptainer for containerization. As only a Dockerfile is supplied for use with the devcontainer, the docker container must first be built and then converted to a SIF file:
docker build -t stmesh:ubuntu --build-arg CORES=8 --build-arg VARIANT=noble --build-arg GCC_VER=14 --build-arg LLVM_VER=18 . --target release
apptainer build stmesh.sif docker-daemon://stmesh:latestThis file can then be uploaded to the cluster and used by executing it. This also works in batch files, for more information see the documentation of your cluster. Note that building directly on a cluster is typically not possible, as docker is not available there.
Alternatively, an Alpine based version may be built, which, unlike the Ubuntu-base, includes the py4dproject Python module:
docker build -t stmesh:alpine -t stmesh:latest --build-arg CORES=8 . -f Dockerfile.alpineFor those with access to the CATS GitLab, pre-built images are provided that may be used to directly create SIF files:
apptainer build stmesh.sif docker://registry.git.rwth-aachen.de/cats/stmesh:alpineMeshing, including the generation of slices and output to other formats, is performed using the stmesher command line tool.
After the simulation has been completed on the mesh, its results may be added directly to the VTK files that were generated by slicing the 4D geometry at time-intervals by stmesher. To this end, the data_visualizer tool is provided.
If a different tool was used for meshing or slices were not generated during meshing, the mesh_analyzer tool can be used to generate the slices from the mesh and directly add simulation results to them. This tool is additionally also capable of generating a mesh quality analysis.
As the stmesher tool is capable of both producing a VTK output and a MIXD output, it is possible to simply add the output of an XNS simulation to the VTU slices.
For this, firstly the output data must be mapped to the coordinates of the VTU slice vertices. If --vtk-out-coord-format was used, the MeshProjector tool can be used on it in order to obtain the projected data. For example
./mesh_projector 4 [stmesh_mxyz_file] [stmesh_mien_file] [cns_output] [stmesh_vtk_out_coord_file] [projected_cns_output] -swap_endianness -fortran_indexing -verboseAfter this, the data can be added using a simply python script. For instance for an INS simulation:
import meshio
import numpy as np
from sys import argv
# Usage: python3 add_cns.py <projected_cns_output> <stmesher_vtu> <output_vtu>
dat = np.fromfile(argv[1], dtype='>d').reshape(-1,4)
v = dat[:,:3]
p = dat[:,3]
m = meshio.read(argv[2])
m.point_data["p"] = p
m.point_data["v"] = v
meshio.write(argv[3], m)NOTE: Currently there is a bug in meshio cocerning its use with VTU files containing different sized polyhedra. The fix from this PR currently needs to be applied manually.
While working with 3D FEM simulation results is fairly well supported by many tools, evaluating 4D meshes is not generally possible. To resolve this, the py4dproject Python module is provided, which allows for the evaluation of simulation results at space-time points in a performant manner.
With the project open in a devcontainer, you can start developing. In order to get the best experience with VSCode, it is recommended to configure clangd by specifying in .vscode/settings.json:
{
"clangd.arguments": [
"--compile-commands-dir=out/build/unixlike-clang-debug"
]
}Owing to the relatively poor performance in debug mode and potentially rare errors that arise during debugging of the stmesh library, it is recommended to set up rr for reverse debugging support. This can be done by installing rr in the devcontainer and then configuring the debugger in .vscode/launch.json(example for debugging the tests):
{
"version": "0.2.0",
"configurations": [
{
"name": "tests (rr/gdb)",
"type": "cppdbg",
"request": "launch",
"program": "${workspaceRoot}/out/build/unixlike-clang-debug/test/tests",
"args": [],
"miDebuggerServerAddress": "localhost:50505",
"stopAtEntry": false,
"cwd": "${workspaceRoot}/out/build/unixlike-clang-debug/test",
"environment": [],
"externalConsole": true,
"linux": {
"MIMode": "gdb",
"setupCommands": [
{
"description": "Setup to resolve symbols",
"text": "set sysroot /",
"ignoreFailures": false
}
]
}
}
]
}In order to use this, firstly record the execution of the tests with
rr record out/build/unixlike-clang-debug/test/testsThen start the rr server by running the rr replay -s 50505 command in the terminal. The VSCode debugger can then be started and will connect to the rr server. To execute in reverse simply use the debug console and run
set exec-direction reverse