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. 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 was able to deal with widely accepted surface mesh formats, such as Wavefront OBJ (which is our preferred format for exporting surfaces from contour segmentations from 3D MR/CT images). The only program being capable to do this was Nvidia's PhysX Viewer (which is meanwhile discontinued). The only required extension was a small program to convert Nvidia's XML-based NXUStream2 format to the GMSH format. Although the PhysX Viewer seemed to work perfectly at first sight, further analysis revealed that high-resolution tetrahedral meshes generated with it were not free of errors and caused major instabilities during deformable simulation due to occasional inverted elements and falsely connected tetrahedra indices (and no, this was not caused by my conversion program....).

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 (2011). Additionally, experiments with the CGAL library showed robust results and finally found its way into the resulting program.

Features

  • Runs on Windows and Linux (tested on Win7 (32/64 bit), WinXP (32 bit) and Ubuntu 12.04/12.10).
  • Integration of QGLViewer for easy mesh preview.
  • Surface mesh import and export for *.obj, *.ply, *.off, *.stl (using trimesh2).
  • 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 could possibly 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.
  • Improve build mechanism. E.g. I would like to have a centralised file to contain the paths to all required 3rd-party libraries or use CMAKE/QMAKE.
  • Add Nvidia's NXUStream2 import.

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. 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 > 10. 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 < 10 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.
  • 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.
  • Exporting surfaces does not add the extension automatically! You have to enter it explicitly (e.g. ".obj", ".off", ".ply" or ".stl")! This will also determine the desired export format.

Download (Source + Binary)

Dependencies / 3rd Party Libraries

This program is using the following 3rd-party libraries: (Name/URL, Version, License)

Build Instructions

Initial advice: Do not think this will be easy! Due to the high number of 3rd-party depenencies, building this program from source will be more complicated than expected... Additionally, I haven't spent too much time thinking about a more comfortable build-system (such as CMAKE/QMAKE).

All components are separate libraries which requires to build the libraries first and then build the acutal GUI using QtCreator. On Windows you will have to build a number of Visual Studio Solutions (2008, SP 1), on Linux you will have to run several Makefiles. I have tried to use relative paths as often as possible, but as you have to build most 3rd-party dependencies from source locally on your machine, chances are high that you have to adjust some dependency paths for a successful build.

Prerequisites

  • Download and install Qt (>= 4.8.x). Don't forget to install the QtCreator. In Ubuntu use the package manager to install the required packages. Update: Since Ubuntu 13.04 you should install the package "qt4-default" to explicitly force invocation of Qt4.
  • Download and build QGLViewer (Windows only). QGLViewer is available in the Ubuntu repositories.
  • Download SOFA (including the required dependency package for your platform) and follow the build/installation instructions. (Good luck!)
  • Download CGAL and follow the installation instructions. CGAL for Windows already comes with GMP and MPFR. But you will have to install Boost. For Windows I recommend using BoostPro. CGAL's instructions are for VS 2010 but work fine for VS 2008 (SP1). On Ubuntu CGAL is available in the package manager. You might have to install GMP and MPFR manually.
  • On Linux install the 'freeglut'-dev package. For Windows a version of GLUT is included in SOFA.

Build Order (ProjectPath, Build-method)

  1. $QTetraMesher/TetraMeshTools/TetraMeshTools.sln or Makefile
  2. $QTetraMesher/SofaTetraStuffing/SofaTetraStuffing.sln or Makefile
  3. $QTetraMesher/CGALTetrahedralize/CGALTetrahedralize.sln or Makefile
  4. Build $QTetraMesher/QTetraMesher.pro using QtCreator

Linux

The Makefiles contain variables for the 3rd-party dependency paths. Adjust those as needed (probably only necessary for SofaTetraStuffing (once in the Makefile, once in QTetraMesher.pro). Then run 'make' in $PWD. Finally open the Qt project "QTetraMesher.pro" in QtCreator. Adjust the SOFA path in .pro file as needed. Currently, execution of the resulting program is only possible from the QtCreator. I will eventually make a run script to append the required $LD_LIBRARY_PATH.
Update: The SVN now has a start script called "qtetramesher.sh" that will set the library path semi-automatically. You probably have to adjust the variable SOFA_LIBS_PATH to point to your SOFA instance.

Windows

Open the Visual Studio solution files in VS 2008 SP1. Adjust the dependency paths (include and libraries) according to where you have installed/built SOFA and CGAL. Build each solution in the order mentioned above. The resulting DLLs will automatically be copied to QTetraMesher's binary/Release dir. If successful, open the QTetraMesher.pro in QtCreator. Update the .pro file to point to your SOFA/CGAL/Boost directories. Then build it. You might want to test the binary release to see which DLLs are required for stand-alone execution outside QtCreator.

Changelog

0.8.1

  • 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

  • Initial version, for basic features see above.

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