• Copyright: (C) Qianqian Fang (2024-2025) <q.fang at neu.edu>
• License: GNU Public License V3 or later
• Version: 0.6.5
• URL: https://pypi.org/project/iso2mesh/
• Homepage: https://iso2mesh.sf.net
• Github: https://github.com/NeuroJSON/pyiso2mesh
• Acknowledgement: This project is supported by the US National Institute of Health (NIH) grants U24-NS124027 and R01-CA204443

• Introduction
• How to Install
• Runtime Dependencies
• Build Instructions
  • Build Dependencies
  • Build Steps
  • Run built-in unit-tests
• How to Use
• Plotting backends
• Iso2Mesh function port status
• How to Cite
• Acknowledgement

Iso2Mesh is a versatile 3D mesh generation toolbox, originally developed for MATLAB and GNU Octave in 2007. It is designed for the easy creation of high-quality surface and tetrahedral meshes from 3D volumetric images. It includes over 200 mesh processing scripts and programs, which can operate independently or in conjunction with external open-source meshing tools. The Iso2Mesh toolbox can directly convert 3-D image stacks—including binary, segmented, or grayscale images such as MRI or CT scans—into high-quality volumetric meshes. This makes it especially suitable for multi-modality medical imaging data analysis and multi-physics modeling.

The iso2mesh Python module provides a re-implementation of Iso2Mesh in the native Python language, following algorithms similar to those in the MATLAB/Octave versions of Iso2Mesh.

• PIP: python3 -m pip install iso2mesh
• PIP+Git (latest version): python3 -m pip install git+https://github.com/NeuroJSON/pyiso2mesh.git

MacOS users: you need to run the following commands to install this module

python3 -m venv /tmp/pyiso2mesh-venv
source /tmp/pyiso2mesh-venv/bin/activate
python3 -m pip install iso2mesh

• numpy: pyiso2mesh relies heavily on vectorized NumPy matrix operations, similar to those used in the MATLAB version of Iso2Mesh.
• matplotlib: The default plotting backend, used to render meshes. Install with pip install matplotlib.
• plotly (optional): An alternative, interactive plotting backend suitable for web pages and Jupyter notebooks. Install with pip install plotly. See Plotting backends.
• pyvista (optional): A VTK/GPU-accelerated plotting backend, recommended for large or volumetric meshes thanks to native tetrahedral (unstructured-grid) rendering. Install with pip install pyvista. See Plotting backends.
• jdata (optional): A lightweight module to load JSON-encoded volume/mesh data, including dynamically downloading data from NeuroJSON.io pip install jdata.

Many core meshing functions in pyiso2mesh require the set of mesh processing executables provided in the Iso2Mesh package under the iso2mesh/bin folder. These binaries are not needed at the time when installing pyiso2mesh; when any of them becomes needed during mesh processing, pyiso2mesh dynamically downloads these external tools and store those under the user's home directory ($HOME/iso2mesh-tools) for future use. This download operation only runs once.

• Operating System: The module is written in pure Python and is portable across platforms, including Windows, Linux, and macOS.

1. Install the build module: python3 -m pip install --upgrade build

2. Clone the repository:

git clone --recursive https://github.com/NeuroJSON/pyiso2mesh.git
cd pyiso2mesh

3. Type python3 -m build to build the package

4. A platform-independent noarch module will be built locally. You should see a package named iso2mesh-x.x.x-py2.py3-none-any.whl in the dist/ subfolder.

5. You can install the locally built package using: python3 -m pip install --force-reinstall iso2mesh-*.whl

If you want to modify the source, and verify that it still produces correct results, you can run the built-in unit-test script inside the downloaded git repository by using this command inside the pyiso2mesh root folder

python3 -m unittest test.run_test

pyiso2mesh inherits the "trademark" one-liner mesh generator style from its MATLAB/Octave counterpart and maintains high compatibility with Iso2Mesh in terms of function names, input/output parameters, and node/element ordering and indexing conventions.

All index matrices, such as face or elem, in the generated mesh data are 1-based (i.e., the lowest index is 1, not 0). This design ensures compatibility with the MATLAB/Octave Iso2Mesh outputs.

import iso2mesh as i2m
import numpy as np

# creating basic grid-like meshes
no, el = i2m.meshgrid5([0,1], [0,2], [1,2])
i2m.plotmesh(no, el)

no, el = i2m.meshgrid6([0,1], [0,2], [1,2])
i2m.plotmesh(no, el)

# meshing a box and plotting with selector
no, fc, el = i2m.meshabox([0,0,0], [30, 20, 10], 2)
i2m.plotmesh(no, el, 'z < 5')

# computing various mesh data

fc2 = i2m.volface(el)
ed1 = i2m.surfedge(fc[:-1,:])
fvol = i2m.elemvolume(no, fc)
evol = i2m.elemvolume(no, el)
facenb = i2m.faceneighbors(el)
snorm = i2m.surfacenorm(no, fc)
cv = i2m.meshcentroid(no, el)
cf = i2m.meshcentroid(no, fc)

# plotting nodes with markers
i2m.plotmesh(cf, 'r.')

# cleaning a surface mesh
no1, fc1 = i2m.meshcheckrepair(no, fc)

# smoothing a surface mesh
no2 = i2m.sms(no1, fc1, 20)

i2m.plotmesh(no2, fc1)

# meshing a cylinder
no, fc, el = i2m.meshacylinder([0,0,0], [0, 0, 10], 2, 50)
i2m.plotmesh(no, el, 'x < 0', edgecolor='r')

# creating and plotting polyhedral solids (PLCs)
mesh = i2m.latticegrid([0,1],[0,1,2], [0,2])
i2m.plotmesh(mesh[0], mesh[1], alpha=0.5, linestyle='--')

# mesh and label PLC based domains using tetgen1.5
mesh2 = i2m.s2m(mesh[0], mesh[1], 1, 0.03, method='tetgen1.5')
i2m.plotmesh(mesh2[0], mesh2[1], alpha=0.5)

pyiso2mesh subdivides all functions into sub-modules (core, geometry, plot, io, trait, modify, utils, register, raster) that can be individually imported. For example, if one wants to create tetrahedral meshes from a 3-D binary array, one can use

from iso2mesh.core import v2m, v2s
from iso2mesh.plot import plotmesh
import numpy as np

img = np.zeros([60,60,60], dtype=np.uint8)
img[20:41, 10:51, 30:] = 1

no, el, fc = v2m(img, [], 3, 100, 'cgalmesh')
plotmesh(no, el)

no, fc, _, _ = v2s(img, 0.5, {'distbound': 0.2})
ax = plotmesh(no, fc, 'y < 30', alpha=0.5,  edgecolor='none')
plotmesh(no, fc, 'y > 30', parent = ax)

The mesh plotting functions (plotmesh, plotsurf, plottetra, plotedges) support three interchangeable rendering backends:

matplotlib is the default and is always available. The plotly and pyvista backends are optional and only need to be installed if you intend to use them; a clear error is raised if you select a backend whose package is missing.

The global default is controlled by the ISO2MESH_PLOT_BACKEND environment variable, following the same convention as other iso2mesh runtime options such as ISO2MESH_TEMP and ISO2MESH_SESSION. The backend can be selected in three ways (in order of precedence: a per-call backend= flag overrides the global ISO2MESH_PLOT_BACKEND setting, which defaults to matplotlib):

import os
import iso2mesh as i2m
import numpy as np

no, fc, el = i2m.meshabox([0,0,0], [30, 20, 10], 2)

# 1) per-call, using the `backend=` keyword (highest priority)
i2m.plotmesh(no, el, 'z < 5', backend='plotly')

# 2) globally, via the ISO2MESH_PLOT_BACKEND environment variable, either from
#    the shell (export ISO2MESH_PLOT_BACKEND=plotly) or from Python:
os.environ['ISO2MESH_PLOT_BACKEND'] = 'plotly'

# 3) globally, using plotbackend() -- a combined getter/setter that validates
#    the name and sets ISO2MESH_PLOT_BACKEND for you:
i2m.plotbackend('pyvista')      # set the backend
i2m.plotmesh(no, el)
print(i2m.plotbackend())        # query the backend -> 'pyvista'
i2m.plotbackend('matplotlib')

All backends accept the same plotmesh inputs (nodes, faces, tetrahedra, selector strings such as 'z < 5', per-node values in a 4th node column, and sub-domain/sub-surface tags) and return a handle dictionary with fig, ax, and obj keys. Common style options are mapped where applicable (e.g. alpha controls opacity, cmap selects the colormap). The plotly and pyvista backends open their own interactive window/figure; pass hold='on' (or show=False) to suppress display, for example when composing multiple plots into the same figure via the parent= keyword.

The progress of converting MATLAB-based Iso2Mesh functions to Python is tracked in #1

Users of the pyiso2mesh toolbox should consider citing the below publications related to iso2mesh.

The original conference paper that described the iso2mesh toolbox workflow was published in 2009:

• Qianqian Fang and David Boas, "Tetrahedral mesh generation from volumetric binary and gray-scale images," Proceedings of IEEE International Symposium on Biomedical Imaging 2009, pp. 1142-1145, 2009

A journal paper, published in 2020 describing the brain2mesh toolbox contains a much more up-to-date description of iso2mesh in the context of complex brain mesh generation

• Anh Phong Tran, Shijie Yan and Qianqian Fang*, (2020) "Improving model-based fNIRS analysis using mesh-based anatomical and light-transport models," Neurophotonics, 7(1), 015008

If one utilized the brain1020 function in your research, you should cite the below paper where the workflow of this function was described

• Ashlyn McCann, Edward Xu, Fan-Yu Yen, Noah Joseph, Qianqian Fang, "Creating anatomically derived, standardized, customizable, and three-dimensional printable head caps for functional neuroimaging," Neurophoton. 12(1) 015016 (18 March 2025) https://doi.org/10.1117/1.NPh.12.1.015016, PMID: 39257741; PMCID: PMC11383710.

The pyiso2mesh module was converted from the MATLAB/Octave version of of Iso2Mesh (https://github.com/fangq/iso2mesh) written by the same author.

We utilized large-language-model (LLM) and AI chatbot in the initial MATLAB-to-Python conversion, with specific instructions to faithfully replicate the algorithms developed in the MATLAB code to avoid introducing external copyrighted materials into this toolbox. With the assumption that the AI chatbot functions primarily as an automated syntax translator without altering the originality of the code, the upstream author of the original MATLAB-based Iso2Mesh retains the full copyright of this derived Python module.

The initial translation was further manually tested, adjusted and restructured to produce matching outputs as the original MATLAB toolbox. Dr. Edward Xu <xu.ed at northeastern.edu> had contributed to the initial conversion and testing of a subset of functions in the geometry.py and trait.py units.

The development of this software is supported by the US National Institute of Health (NIH) under research awards U24-NS124027 and R01-CA204443, with the author, Dr. Qianqian Fang, serving as the principle investigator on both awards.