Iso2Mesh: An Image-based 3D Surface and Volumetric Mesh Generator

Table of Contents

• Introduction
• Iso2Mesh Suite
• Overview of functions
• Compiling Iso2mesh
• Acknowledgement

Introduction

"Iso2Mesh" is a MATLAB/Octave-based mesh generation toolbox,designed for easy creation of high quality surface andtetrahedral meshes from 3D volumetric images. It containsover 200 mesh processing scripts/programs, workingeither independently or interacting with external freemeshing utilities. Iso2Mesh toolbox can directly converta 3D image stack, including binary, segmented or gray-scaleimages such as MRI or CT scans, into quality volumetricmeshes. This makes it particularly suitable for multi-modalitymedical imaging data analysis and multi-physics modeling.Above all, iso2mesh is open-source. You can download it forfree. You are also allowed to extend the toolbox for yourown research and share with other users. Iso2Mesh iscross-platform and is compatible with both MATLAB and GNU Octave(a free MATLAB clone).

The details of this toolbox can be found in the followingpapers (citing the first paper is highly encouraged):

• Anh Phong Tran, Shijie Yan and Qianqian Fang*, (2020) "Improvingmodel-based fNIRS analysis using mesh-based anatomical andlight-transport models," Neurophotonics, 7(1), 015008
• Qianqian Fang and David Boas, "Tetrahedral mesh generation fromvolumetric binary and gray-scale images," Proceedings of IEEEInternational Symposium on Biomedical Imaging (ISBI 2009),pp. 1142-1145, 2009

The first paper published recently describes a fully automated high-qualitybrain mesh generation pipelinebuilt upon Iso2Mesh, providing a showcase for nearly all corefunctionalities provided in this toolbox.

Iso2Mesh Suite

In addition to convenient 3D mesh generation functionalities,the development of Iso2Mesh has also resulted in a number ofsubmodules that have also received wide adoption - someare even more popular than Iso2Mesh itself. For example:

• JSONLab (http://openjdata.org/jsonlab): a JSON/UBJSON/MassagePackencoder and decoder (Editor Pick-of-the-week, Popular File 2018)
• Brain2Mesh (http://mcx.space/brain2mesh): a fully automatedhigh-quality brain mesh generation toolbox built on Iso2Mesh
• JNIfTI (http://github.com/fangq/jnifti): a fast and portableNIfTI-1/2 reader/writer and next-gen NIfTI file format
• Metch (http://iso2mesh.sf.net/metch): a 3D mesh registration toolbox
• JData specification (http://openjdata.org): a highly portableeasy-to-use scientific data annotation method and specification
• ZMat (http://github.com/fangq/zmat): a data compression libraryand MATLAB/Octave toolbox

Currently, Iso2Mesh and its submodules are broadly distributedamong popular open-source MATLAB toolboxes, especially among majorneuroimaging tools, including

• Fieldtrip (http://www.fieldtriptoolbox.org) [iso2mesh/jsonlab]
• BrainStorm (https://neuroimage.usc.edu/brainstorm) [iso2mesh/brain2mesh/easyh5]
• Lead-DBS (http://www.lead-dbs.org) [iso2mesh]
• ROAST (https://www.parralab.org/roast) [iso2mesh]
• HOMER2 (https://github.com/BUNPC/AtlasViewer) [iso2mesh/metch]
• REST (https://github.com/goodshawn12/REST) [iso2mesh]

Overview of functions

Creation of high-quality surface and tetrahedral meshesfrom volumetric images has been a challenging task.There are very limited software and resources availablefor this purpose. Commercial tools, such as Mimicsand Simpleware, are both expensive and limited in flexibility.Iso2Mesh was developed as a free alternative to theseexpensive commercial tools and provides researchers a highlyflexible, modular and streamlined image-based meshgeneration pipeline. Intuitive interfaces and richfunctionalities allow one to enjoy a wide rangeof mesh-based analyses, ranging from 3D volumetricimage pre-processing (hole-filling, thinning andthickening), surface mesh modeling (extraction,remeshing, repairing, and smoothing) to volumetricmesh creation.

Converting 3D image stacks into quality surface andtetrahedral meshes is one of the core features of iso2mesh.We provide serveral automated functions to performthe image->mesh and mesh->image conversion, including

• vol2mesh (v2m): convert a 3D volumetric image into a tetrahedral mesh
• vol2surf (v2s): extract triangular surfaces from a 3D image volume
• surf2mesh (s2m): create a tetrahedral mesh from a triangular surface mesh
• surf2vol (s2v): rasterize a close-surface to a volumetric image
• mesh2vol (m2v): rasterize a tetrahedral mesh to a volumetric image

Most of these function are associated with several meshingoptions and parameters to give users full control to meshdensity, adaptivity, region labeling and mesh quality.The output data for some of these functions can be usedas the input for the others, giving endless combinations toanalyze your data. In addition to image-based mesh generation,iso2mesh can also mesh geometry primitives such as spheres,cubes and cylinders. This makes iso2mesh a CAD-capable software,fully integrated in the MATLAB/Octave environments.

Another core feature of iso2mesh is surface meshprocessing. A surface mesh is the bridge between a voxelatedimage and a tetrahedral mesh, and is the foundation forsuccessful 3D mesh generation. In iso2mesh, we provide thefollowing key functions for surface mesh processing:

• smoothsurf (sms): smoothing a surface mesh
• surfboolean: boolean operations (join, intersect, diff) of two surfaces
• meshresample: downsample a surface mesh to a coarse surface
• meshrefine: refine a surface mesh
• remeshsurf: remesh a surface mesh, including up-sampling and down-sampling
• meshcheckrepair: test a surface mesh and remove defects and self-intersecting elements

A third area iso2mesh excels is the rich set of mesh analysisand inquiry functions. For both surface and tetrahedral meshes,iso2mesh can report the element volume (or area), mesh qualitymetrics, node connectivity and neighbors, interior edges andboundaries, surface norms, element centroids, etc.

Last, but not the least, iso2mesh can import and export meshdata from/to a dozen of file formats, including those used by thepopular FEA software like COMSOL and ABAQUS. The STL format canexport an iso2mesh-generated mesh for 3D printing.Users can not only export the data to a file, but also make3D plots in MATLAB/Octave using the powerful "plotmesh" function.

These examples are only a small fraction in the over 200 optimizedfunctions provided by iso2mesh. The modular design of iso2meshmakes the code easy to understand and easy to be intergrated inyour data analysis workflow. Please check out the full iso2meshfunction list and detailed help information in the following URL:

http://iso2mesh.sf.net/cgi-bin/index.cgi?Doc/FunctionList

Compiling Iso2Mesh

The default release of Iso2Mesh packages already contains pre-compiledbinaries for a wide range of platforms (32/64bit Windows, 32/64bit Linuxand Mac with 64bit Intel and 32 bit PowerPC CPUs). So, without needingto recompile, Iso2Mesh can be executed out-of-box on MATLAB or GNU Octave.

However, in the event that your operating system is not supported, ordue to license restrictions, such as creating a release for variousLinux distributions, you can recreate the mesh utility binaries underiso2mesh/bin folder using the source codes provided under iso2mesh/toolsby following the below commands:

git clone --recurse-submodules https://github.com/fangq/iso2mesh.git
cd iso2mesh
rm -rf bin/*.mex* bin/*.exe
cd tools
make clean
make

This will download and recompile the below binaries in the bin folder:

• cgalmesh
• cgalsurf
• cgalsimp2
• jmeshlib
• meshfix
• tetgen1.5
• cork

Once these binary files are recreated, you can run all the major functionalitiesof Iso2Mesh. The gtrefine utility is depreciated and replaced bycork and tetgen.

To compile the above external tools, the below tools must be pre-installed(tested on Ubuntu 14.04 LTS, if you use another Linux distribution, the packagenames might be different)

• gcc
• cmake
• libcgal-dev
• libsuitesparse-dev
• zlib1g-dev

you can install these on Ubuntu by running:

sudo apt-get install gcc cmake libcgal-dev libsuitesparse-dev zlib1g-dev

on Ubuntu or Debian. If you use Fedora, you need to install the below packages

 sudo dnf install cmake CGAL-devel SuperLU-devel blas-static gcc-c++ zlib-devel octave-devel

Acknowledgement

This toolbox interacts with a number external meshing toolsto perform the essential functionalities. These tools are listedbelow:

bin/tetgen and bin/tetgen1.5:

• Summary: tetgen is a compact and fast 3D mesh generator
• License: GNU Affero General Public License version 3
• URL: http://tetgen.org/
• Author: Hang Si
• Research Group: Numerical Mathematics and Scientific Computing::Weierstrass Institute for Applied Analysis and Stochastics::Mohrenstr. 39, 10117 Berlin, Germany

bin/cgalsurf:

• Summary: cgalsurf is a utility to extract a surface mesh from a gray-scale or a binary 3D image
• Source: it is a slightly modified version from Surface_mesher example from CGAL 3.4
• License: CGAL is licensed under General Public License (GPL) version 3 or later; many of its core modules are under the Lesser General Public License (LGPL)
• URL: http://www.cgal.org/Manual/3.3/doc_html/cgal_manual/Surface_mesher/Chapter_main.html

bin/cgalmesh and bin/cgalpoly:

• Summary: cgalmesh and cgalpoly are utilities to produce surface and volumetric meshes from a multi-valued volumetric image
• Source: it is a slightly modified version from Mesh_3 example from CGAL 5.3
• License: CGAL is licensed under General Public License (GPL) version 3 or later; many of its core modules are under the Lesser General Public License (LGPL)
• URL: https://doc.cgal.org/latest/Mesh_3/

bin/cgalsimp2:

• Summary: cgalsimp2 performs surface mesh simplification in iso2mesh.
• Source: it is adapted from Surface_mesh_simplification example of CGAL library
• License: CGAL is licensed under General Public License (GPL) version 3 or later; many of its core modules are under the Lesser General Public License (LGPL)
• URL: https://doc.cgal.org/latest/Surface_mesh_simplification/index.html

bin/jmeshlib:

• Summary: meshfix is adapted from the sample code of JMeshLib
• License: GPL (GNU General Public License) v2 or later
• URL: http://jmeshlib.sourceforge.net/
• Author:Marco Attene ::Istituto di Matematica Applicata e Tecnologie Informatiche::Consiglio Nazionale delle Ricerche::Via De Marini, 6 (Torre di Francia)::16149 Genoa - ITALY

bin/meshfix:

• Summary: meshfix is a mesh-repairing utility
• License: GPL (GNU General Public License) v2 or later
• URL: http://code.google.com/p/meshfix/
• Author: Marco Attene, Mirko Windhoff and Axel Thielscher.::Istituto di Matematica Applicata e Tecnologie Informatiche::Consiglio Nazionale delle Ricerche::Via De Marini, 6 (Torre di Francia)::16149 Genoa - ITALY

bin/cork:

• Summary: A robust surface mesh Boolean operation algorithm
• License: LGPL (GNU Lesser General Public License)
• URL: https://github.com/gilbo/cork
• Author: Gilbert Bernstein

bin/gtsrefine:

• Summary: GTS is the GNU Triangulated Surface Library
• License: LGPL (GNU Lesser General Public License)
• URL: http://gts.sourceforge.net/
• Author: GTS developers

bin/PoissonRecon:

• Summary: Screened Poisson Surface Reconstruction (Version 8.0)
• License: MIT
• URL: http://www.cs.jhu.edu/~misha/Code/PoissonRecon/Version8.0/
• Author: Michael Kazhdan (http://www.cs.jhu.edu/~misha/)

Note: Iso2Mesh and the above meshing utilities are consideredas an "aggregate" rather than "derived work", based on thedefinitions in GPL FAQ (http://www.gnu.org/licenses/gpl-faq.html#MereAggregation)Therefore, the license of Iso2Mesh and these utilities are independent.The Iso2Mesh license only applies to the scripts and documentation/datain this package and exclude those programs stored in the bin/ directory.The source codes of the modified meshing utilities are availableseparately at Iso2Mesh's website and retain their upstream licenses.

Your acknowledgement of Iso2Mesh in your publications orpresentations would be greatly appreciated by the author ofthis toolbox. The citation information can be found in theIntroduction section.