iso2mesh - Fast & Versatile 3D Mesh Generation

iso2mesh

Fast, Versatile & Cross-Platform 3D Mesh Generation Toolbox

An image-based 3D surface and volumetric mesh generator

Version 1.9.8 (Pot Stickers) MATLAB/Octave/Python 200+ Functions GPL v2+ NIH Funded

📋 What is iso2mesh?

Iso2mesh is a MATLAB/Octave/Python-based mesh generation toolbox with 200+ functions for creating high-quality surface and tetrahedral meshes from 3D volumetric images. It converts MRI/CT scans into quality meshes for medical imaging and multi-physics modeling.

🏆 NeuroJSON Project

Part of NeuroJSON (neurojson.org), funded by US NIH grants U24-NS124027 and R01-CA204443.

1000+
Citations
18+
Years Active
200+
Functions
MATLAB/Octave Python Package Documentation

⚡ Core Capabilities

  • Image-to-Mesh Conversion: Direct conversion from 3D volumetric images (MRI, CT) to high-quality tetrahedral meshes
  • Multi-Region Support: Handle complex multi-labeled volumes with tissue-specific mesh density control
  • Surface Extraction: Fast isosurface extraction using CGAL, with mesh simplification and repair
  • Primitive Meshing: Built-in meshers for spheres, boxes, cylinders, ellipsoids, and complex geometries
  • Boolean Operations: Union, intersection, difference operations on surface meshes using Cork library
  • Mesh Processing: Smoothing, refinement, simplification, quality analysis, and repair tools
  • Cross-Platform: Works identically on Windows, Linux, and macOS with MATLAB R2008+ or GNU Octave 3.8+
Detailed Features View Examples

🔧 Core Functions

Volume-to-Mesh

  • v2m - vol2mesh
  • v2s - vol2surf
  • cgalv2m - CGAL 3D mesher
  • binsurface - fast isosurface

Surface-to-Mesh

  • s2m - surf2mesh
  • s2v - surf2vol
  • cgals2m - CGAL surface mesh
  • remeshsurf - remeshing

Primitive Meshers

  • meshabox - box mesh
  • meshasphere - sphere mesh
  • meshacylinder - cylinder mesh
  • meshanellip - ellipsoid mesh

Mesh Processing

  • sms - smoothsurf
  • meshcheckrepair - repair
  • surfboolean - Boolean ops
  • meshrefine - refinement
Quick Examples

🔄 Typical Workflows

1️⃣ Medical Image Processing

Input: MRI/CT scan (NIfTI, DICOM)
Process: Load → Segment → v2s (surface) → sms (smooth) → s2m (tetrahedral)
Output: Multi-tissue tetrahedral mesh for FEM analysis

2️⃣ Geometric Modeling

Input: CAD models, primitive shapes
Process: meshasphere/box/cylinder → surfboolean (combine) → meshrefine
Output: Complex geometries for physics simulation

3️⃣ Brain Mesh Generation

Input: T1/T2 MRI brain scans
Process: brain2mesh (auto-segmentation) → multi-layer mesh
Output: 5-layer brain mesh (scalp, skull, CSF, GM, WM)

4️⃣ Mesh Analysis Pipeline

Input: Existing mesh (STL, OBJ, OFF)
Process: readoff → meshcheckrepair → meshquality → exportFEA
Output: Clean mesh for COMSOL/ABAQUS

🏆 Why Choose iso2mesh?

✅ Free & Open Source

GPL v2+ license with full source code access. No expensive commercial licenses like Mimics ($15K+) or Simpleware ($30K+)

⚡ High Performance

Optimized CGAL and TetGen backends. Process 256³ volumes in seconds. Parallel processing support for large datasets

🔧 Highly Modular

200+ independent functions that can be combined in endless ways. Easy to integrate into existing MATLAB/Octave workflows

🌐 Cross-Platform

Windows, Linux, macOS. MATLAB R2008+ and GNU Octave 3.8+. Now available in Python (pyiso2mesh)

📚 Well-Documented

Comprehensive documentation with 50+ examples. Active community support. Published in IEEE ISBI 2009 with 1000+ citations

🎯 Medical Imaging Focused

Native support for NIfTI, DICOM, multi-region segmentation. Powers brain2mesh for automated brain mesh generation

🛠️ External Tools & Backends

Iso2mesh integrates with powerful open-source meshing libraries:

🔷 TetGen (v1.5)

Fast 3D tetrahedral mesh generator. GPL/AGPL license. Used for surf2mesh operations

⚙️ CGAL (v5.3)

Computational Geometry Algorithms Library. GPL/LGPL. Powers cgalsurf, cgalmesh, cgalsimp2

🔧 Cork

Robust Boolean operations on triangle meshes. LGPL license. Used by surfboolean

🛠️ JMeshLib / MeshFix

Mesh repair utilities. GPL v2. Fixes non-manifold vertices and self-intersections

📐 GTS / PoissonRecon

Additional surface reconstruction tools. LGPL/MIT. Optional backends for specialized tasks

Note: Pre-compiled binaries for Windows, Linux (32/64-bit), and macOS are included. Source code available for custom compilation.

One-Liner Magic

Generate complex meshes with simple, intuitive commands

MATLAB/Octave

% Volume to mesh
[node,elem,face] = v2m(img, 0.5, 2, 100);

% Create sphere
[node,face,elem] = meshasphere([0,0,0], 5, 0.5, 1);

% Extract surface
[node,face] = v2s(img, 0.5, opt);

% Surface to volume
vol = s2v(node, face, div);

Python

# Import iso2mesh
import iso2mesh as i2m

# Generate mesh from volume
no, el, fc = i2m.v2m(img, [], 3, 100, 'cgalmesh')

# Create and plot cylinder
no, fc, el = i2m.meshacylinder([0,0,0], [0,0,10], 2, 50)
i2m.plotmesh(no, el, 'x < 0')

Core Capabilities

Interactive tutorials with live examples

📦 Volume to Mesh Conversion

% Load a 3D volume (MRI/CT scan)
img = zeros(60,60,60);
img(20:40,20:40,20:40) = 1;

% One-liner: volume to tetrahedral mesh
[node,elem,face] = v2m(img, 0.5, 2, 100);

% Extract surface only
[node,face] = v2s(img, 0.5, opt);

% Using CGAL backend for multi-region
[node,elem,face] = v2m(img,[],2,100,'cgalmesh');

🔧 Surface Processing

% Smooth surface mesh (Laplacian-HC)
newnode = sms(node, face, 10);

% Check and repair mesh
[node,face] = meshcheckrepair(node,face,'deep');

% Resample mesh (simplify to 10%)
[node2,face2] = meshresample(node,face,0.1);

% Remesh surface
[newno,newfc] = remeshsurf(node,face,1);

⬡ Primitive Mesh Generation

% Create sphere mesh
[node,face,elem] = meshasphere([0,0,0],5,0.5,1);

% Create box mesh
[node,face,elem] = meshabox([0,0,0],[10,10,10],1);

% Create cylinder mesh
[node,face,elem] = meshacylinder([0,0,0],[0,0,10],2,50);

% Create ellipsoid
[node,face,elem] = meshanellip([0,0,0],[3,2,1],0.5,1);

📊 Mesh Quality & Analysis

% Compute mesh quality (Joe-Liu metric)
quality = meshquality(node, elem);

% Calculate element volumes
vol = elemvolume(node, elem);

% Get surface normals
snorm = surfacenorm(node, face);

% Find mesh connectivity
conn = meshconn(elem, size(node,1));

% Check if points inside surface
tf = insurface(node, face, points);

💾 File Import/Export

% Save to STL (for 3D printing)
savestl(node,face,'mesh.stl');

% Save to OFF format
saveoff(node,face,'mesh.off');

% Read mesh files
[node,face] = readoff('mesh.off');

% Export to COMSOL/ABAQUS
savemedit(node,face,elem,'mesh.mesh');
saveabaqus(node,face,elem,'mesh.inp');

Advanced Features

Powerful capabilities for complex workflows

🔀 Boolean Operations

% Create two overlapping meshes
[no1,fc1] = meshabox([0,0,0],[10,10,10],1);
[no2,fc2] = meshasphere([5,5,5],4,0.5,1);

% Boolean operations
[no3,fc3] = surfboolean(no1,fc1,'union',no2,fc2);
[no4,fc4] = surfboolean(no1,fc1,'intersect',no2,fc2);
[no5,fc5] = surfboolean(no1,fc1,'diff',no2,fc2);

📊 Mesh Quality

% Compute mesh quality (Joe-Liu metric)
quality = meshquality(node, elem);

% Calculate element volumes
vol = elemvolume(node, elem);

% Get surface normals
snorm = surfacenorm(node, face);

% Find connectivity
conn = meshconn(elem, size(node,1));

🔬 Adaptive Refinement

% Refine by maximum volume
[no1,el1,fc1] = meshrefine(node,elem,maxvol=0.02);

% Refine with size field
sizefield = node(:,1) * 0.3;
[no2,el2,fc2] = meshrefine(node,elem,sizefield);

% Add specific nodes
newpts = [1,1,1; 2,2,2; 3,3,3];
[no3,el3,fc3] = meshrefine(node,elem,newpts);

🧠 Brain Mesh Generation

% Automated brain mesh from MRI (T1/T2)
[node,elem,face] = brain2mesh('brain_t1.nii');

% Generate 10-20 electrode positions
[coords,labels] = brain1020('fsaverage');

% Multi-layer brain mesh (5 tissues)
cfg.method = 'cgalv2m';
cfg.maxnode = 50000;
[node,elem,face] = brain2mesh('brain_t1.nii',cfg);

% elem(:,5) contains tissue labels:
% 1=WM, 2=GM, 3=CSF, 4=Skull, 5=Scalp

Brain2Mesh

Automated brain mesh generation from MRI scans

🧠 Basic Usage

% Load SPM segmentation (c1-c5 files)
for i = 1:5
    A = loadjnifti(sprintf('c%i_seg.jnii', i));
    seg.(names{i}) = A.NIFTIData;
end

% Generate multi-layer brain mesh
[node, elem, face] = brain2mesh(seg);

% With configuration options
cfg.dotruncate = 1;  % cut below brain
cfg.smooth = 10;     % smooth surfaces
[node, elem, face] = brain2mesh(seg, cfg);

📍 10-5 Electrode System

% Generate 10-5 landmarks on scalp
headsurf = volface(elem(:,1:4));
[landmarks, curves] = brain1020(node, headsurf, ...
    initpoints, 10, 5);

% Interactive landmark selection (no initpoints)
[landmarks, curves] = brain1020(node, face);

⚙️ Configuration Options

  • cfg.radbound - Surface sampling density (1.7-3)
  • cfg.maxnode - Max surface nodes [100000]
  • cfg.maxvol - Max element volume [100]
  • cfg.smooth - Smoothing iterations [0]
  • cfg.ratio - Radius-edge ratio [1.414]
  • cfg.dotruncate - Cut neck region [1]
  • cfg.dorelabel - Remove layer gaps [0]

🏷️ Tissue Labels

elem(:,5) contains tissue IDs:
0=Air, 1=Scalp, 2=Skull, 3=CSF, 4=GM, 5=WM, 6=Air pockets

📄 Reference

Tran, Yan & Fang (2020)
"Improving model-based fNIRS analysis..."
Neurophotonics, 7(1), 015008

The iso2mesh Ecosystem

Powerful tools and integrations

🛠️ Core Ecosystem Tools

JSONLab

JSON/Binary JSON encoder/decoder

⭐ Popular File

Brain2Mesh

Automated brain mesh generation

ZMat

Data compression library

JNIfTI

NIfTI-1/2 reader/writer

JData

Scientific data specification

Metch

3D mesh registration toolbox

neuroj.m

NeuroJSON.io data access API

🌐 REST API

Part of the NeuroJSON ecosystem

neurojson.io →

📦 Software Embedding iso2mesh

Major neuroimaging and biomedical toolboxes that include iso2mesh:

FieldTrip

MEG/EEG analysis toolbox • fieldtriptoolbox.org

Brainstorm

MEG/EEG/fNIRS analysis • brainstorm

Lead-DBS

Deep brain stimulation imaging • lead-dbs.org

ROAST

Realistic tDCS modeling • parralab.org/roast

HOMER2

fNIRS data analysis • BUNPC/AtlasViewer

REST

Resting-state fMRI toolkit • goodshawn12/REST

Supported File Formats

Comprehensive I/O support across all major formats

Category File Extension Read Function Write Function Description
📐 Mesh .off readoff saveoff Geomview Object Format
.stl — savestl, savebinstl STL (3D Printing)
.asc readasc saveasc FreeSurfer ASCII
.smf readsmf savesmf Simple Model Format
.gts readgts savegts GNU Triangulated Surface
.mesh readmedit savemedit Medit Mesh Format
.dxf — savedxf AutoCAD DXF
.wrl — savevrml VRML 1.0
🧬 Medical .nii, .nii.gz loadnifti savenifti NIfTI-1/2 neuroimaging
.hdr/.img loadnifti — Analyze 7.5 format
.jnii loadjnifti savejnifti JSON NIfTI
.bnii loadjnifti savebnii Binary JSON NIfTI
.inr readinr saveinr INR volume format
.tif, .tiff readmptiff — Multi-page TIFF
⚙️ FEA .node/.ele/.poly readtetgen savetetgennode, savetetgenele, savesurfpoly TetGen files
.msh — savemsh GMSH mesh format
.inp — saveabaqus ABAQUS input
.mphtxt — savemphtxt COMSOL mesh
.node/.elem/.param readnirfast savenirfast NIRFAST optical FEM
💾 Data .json, .jdt loadjson savejson JSON text format
.jd, .bjd loadbj, jload savebj, jsave Binary JData
.ubj loadubjson saveubjson Universal Binary JSON
.msgpk loadmsgpack savemsgpack MessagePack binary
.jmsh, .bmsh loadjmesh savejmesh JMesh format
📐 Mesh Formats
🧬 Medical Imaging
⚙️ FEA Software
💾 Data Exchange

Installation

Get started in minutes

📦 MATLAB/Octave

Download and add to path:

addpath('/path/to/iso2mesh');
rehash;

🐍 Python

Install via pip:

pip install iso2mesh

🐧 Debian/Ubuntu

Install via apt:

sudo apt-get install octave-iso2mesh

🎩 Fedora

Install via dnf:

sudo dnf install octave-iso2mesh

🔧 From Source

Clone from GitHub:

git clone https://github.com/fangq/iso2mesh.git

📥 Releases

Download stable release:

Download v1.9.8
1000+
Citations
200+
Functions
18+
Years Active
View on GitHub Documentation

Supported by NIH Grants U24-NS124027 & R01-CA204443

GPL v2 or later License

Powered by Habitat