QTetraMesher

Screenshot with CGAL options Screenshot with TetraStuffing options

Contents

Project Description

This is an open-source Qt-based program for Windows and Linux to generate tetrahedral meshes for finite element simulation from various surface mesh formats. It also offers a fast and easy-to-use mesh viewer based on QGLViewer and allows basic mesh manipulations (currently only scaling is possible). Two different methods for tetrahedralization are possible: Delaunay Triangulation and Johnathan Shewchuk's Isosurface Stuffing algorithm.

As I am using lots of 3rd-party open-source C/C++ libraries, this work is released as GPL software. This includes all self-written code. 3rd-party code remains under its own license.

Motivation

When I initially started working with deformable simulation on tetrahedral meshes in 2010, I soon met the point when I had to generate my own tetrahedral meshes from already existing surface meshes (segmentations from MRI/CT images). It became obvious that there are indeed lots of papers suggesting methods for doing this, including some more or less specialized implementations (GMSH, Tetgen), while none of those programs were able to deal with widely accepted surface mesh formats, such as OBJ or STL. What I really wanted was a standalone software in which I could load a surface mesh for which I could generate a tetrahedral mesh with a button-click.

Soon after I had found Johnathan Shewchuk's Isosurface Stuffing: Fast Tetrahedral Meshes with Good Dihedral Angles method, with no freely available reference implementation, though. Instead, I could find a C++ implementation of this method in the SOFA Framework. Instead of abusing SOFA's scene files to exploit this implementation, I decided to write an integrated viewer and conversion tool that would integrate the SOFA libraries. Additionally, experiments with the CGAL library showed robust results and finally found its way into the resulting program.

Features

  • Build and run tested successfully on Windows and Linux (Win10 (64 bit), Manjaro >= 21.04 Ubuntu 22.04, Fedora 38).
  • Integration of QGLViewer for easy mesh preview.
  • Surface mesh import and export for *.obj, *.stl, *.ply, *.3DS, Collada
    (using the Assimp library since Septober 2023).
  • Import and export of tetrahedral meshes in (a simplified subset of the) GMSH format *.msh (compatible with the SOFA Framework).
  • Two different methods for tetrahedralization: Delaunay Triangulation (CGAL implementation) and Johnathan Shewchuk's Isosurface Stuffing: Fast Tetrahedral Meshes with Good Dihedral Angles (implementation taken from the SOFA Framework, non-graded variant only).
  • Wireframe and solid/shaded drawing.
  • Cutplane view for tetrahedral meshes.
  • Export the surface of a tetrahedral mesh.
  • Automatic initial parameter guessing for tetrahedralization.
  • Reversible scale mechanism for CGAL performance optimization.
  • (since 0.8.1) Load supported mesh files via drag & drop on the main window.

Limitations

  • Certain surface meshes cause problems with one or the other tetrahedralization method, e.g. corrupt meshes(SOFA TetraStuffing) or violated CGAL preconditions. This might happen due to corrupt surface meshes and can (often) be fixed by resampling the surface mesh in a 3D modeller such as Blender.
  • Currently only scaling by a factor of 10 or 0.1 is possible to guarantee reversibility of the operation.
  • My UI design skills are close to non-existent. That's why the tetrahedralization methods show up in separate windows instead of being nicely squeezed into the main window.

TODO

  • Add Tetgen support.
  • Stand-alone Isosurface Stuffing implementation to reduce "dependency weight"...
  • Add graded variant for Isosurface Stuffing.

Usage

Generating tetrahedral meshes can't get any easier than this:

  • After starting the program you should see a 3D-spiral as a tribute to QGLViewer.
  • Load a supported surface mesh from the File-menu. You can filter by file-type. It should appear in the viewer.
  • When the mesh is loaded, select the Mesh-entry in the upper menu. Click either CGAL or SofaTetraStuffing to open a window containing some parameters and a button labeled Generate Tetrahedra.
  • Leave the parameters unchanged and click the Generate Tetrahedra-button. This might take while with CGAL (especially for large meshes (where large is meant as longest-bounding-box-axis), see below).
  • If successful, chances are high that you now don't see a tetrahedral mesh because it is covered by the previously loaded surface mesh.
  • At the right-hand side switch the surface mesh visualization to Wireframe or Hidden. This should reveal the tetrahedral mesh. Additionally, you can use the Cut Plane slider to inspect the inner volume.
Maximum Bounding Box Length

Useful Hints

  • Upon loading a new surface mesh, the program will make a more or less "educated" guess to set a reasonable cell-size value and other parameters. I recommend to try the suggested values first.
  • CGAL's Delaunay triangulation is becoming slow when the surface mesh bounding-box size is > 100. Use the built-in scaling function (by using the Scalex01 or Scalex10 entries from the Mesh-menu) to scale the surface mesh down to a value <100 to decrease processing time. After generating the tetrahedral mesh you can undo the scaling by using the opposite scale factor. This will neither affect the tetrahedral mesh indices nor the surface structure.
  • SofaTetraStuffing tends to fail at small structures. To achieve better results, try to scale the surface by 10 and then reduce the proposed cell-size in the appropriate dialog. Depending on the overall volume of your surface this could produce more tetrahedra than expected.
  • With the built-in parameter guess, SofaTetraStuffing doesn't require initial scaling at high volumes for runtime-optimization. The guessed parameters will result in approximate constant runtimes and number of tetrahedra.
  • Unfortunately QuartetTetraStuffing is quite unstable and has a high chance to crash the program. I will leave it enabled for now for testing purposes. I recommend to use Sofa or CGAL tetrahedralization.
  • There exists now a Tetgen implementation which I could not get to work properly on Linux with meshes more complex than a simple cube. It can successfully tetrahedralize a sphere, torus and cylinder on Windows, but fails miserably on Linux. For this reason Tetgen tetrahedralization is disabled for now... Sorry.
  • If you cannot see any mesh after loading/generating one, check if the visualization (on the right-hand side) is not set to "Hidden"! (I had this a few times...)
  • Exporting a tetrahedral mesh as *.msh will automatically add the required .msh extension if absent.

Download (Source + Binary)

Dependencies / 3rd Party Libraries

As of Septober 2023 the following 3rd party libraries are required:
(Name/URL, Version, License, optional note)

libQGLViewer (2.9.1) is now included in the repository with a working CMake build configuration for both Windows and Linux to ensure a smooth platform independent build. I had submitted a pull request which is now superseded by this one: Pull request waiting for approval...

  • Qt (>= 5.15.x), LGPL
  • Boost (>= 1.80.x), Boost Software License, required for Sofa and CGAL
  • SOFA Framework (Github), GPL/LGPL
    • Eigen (>= 3.4.0), MPL2, required for building Sofa Framework
  • CGAL (>= 5.6), GPL/LGPL
    • GMP (>= 5.1.1), LGPL, required for CGAL
    • MPFR (>= 3.1.1), LGPL, required for CGAL
  • Assimp (>= 5.2.x), 3-clause BSD License

Build Instructions

This is not so hard on Linux but really painful on Windows...

Building from source

Building from source mostly requires to install and/or build 3rd-party libraries from source and running a few CMake commands or building Visual Studio solutions (VS 2019, msvc-142).

Linux

The Linux build instructions now have a dedicated page: Linux Build Instructions

Windows

TODO: write Windows build instructions... ... Ok.... I won't write down the build instructions for Windows... The CMake GUI configuration loop is just so tedious that this is not worth to write down. Instead there is a new 0.8.3 Windows release available.

Changelog

0.8.3 (2023-12-16)

0.8.2 (2018-05-23)

  • Updated Windows build (Win64 only!)
    • Built with VS 2015 (Community Edition)
    • Qt 5.10.1
    • Boost 1.64
    • CGAL 4.12 (built with Eigen3)
    • SOFA 17.12
  • Fixed redraw issue for some UI buttons due to changes in QGLViewer

0.8.1 (2015-12-06 : migration to Github)

  • Drag & Drop supported mesh files on the main window to open files.
  • Octree generation and visualization as a preparation for own Isosurface Stuffing implementation.

0.8 (2013-03-03 : Intital commit on GoogleCode)

  • Initial version

License

This program is free software: you can redistribute it and/or modify it 
under the terms of the GNU General Public License as published by the Free 
Software Foundation, either version 3 of the License, or (at your option) any 
later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see here.

Private Work Disclaimer

I hereby confirm that this program has been developed solely during my free time and is in no way related to my regular paid work.


Valid XHTML 1.0 Strict