# pyiso2mesh - One-liner 3D Surface and Tetrahedral Mesh Generation Toolbox
* **Copyright**: (C) Qianqian Fang (2024-2025) <q.fang at neu.edu>
* **License**: GNU Public License V3 or later
* **Version**: 0.3.8
* **URL**: [https://pypi.org/project/iso2mesh/](https://pypi.org/project/iso2mesh/)
* **Homepage**: [https://iso2mesh.sf.net](https://iso2mesh.sf.net)
* **Github**: [https://github.com/NeuroJSON/pyiso2mesh](https://github.com/NeuroJSON/pyiso2mesh)
* **Acknowledgement**: This project is supported by the US National Institute of Health (NIH)
grants [U24-NS124027](https://reporter.nih.gov/project-details/10308329) and
[R01-CA204443](https://reporter.nih.gov/project-details/10982160)
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.
## How to Install
* 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
```
## Runtime Dependencies
* **numpy**: `pyiso2mesh` relies heavily on vectorized NumPy
matrix operations, similar to those used in the MATLAB version of Iso2Mesh.
* **matplotlib**: Used for plotting results. Install with `pip install matplotlib`.
* **jdata** (optional): A lightweight module to load JSON-encoded volume/mesh data,
including dynamically downloading data from [NeuroJSON.io](https://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.
## Build Instructions
### Build Dependencies
* **Operating System**: The module is written in pure Python and is portable across platforms,
including Windows, Linux, and macOS.
### Build Steps
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`
### Run built-in unit-tests
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
```
## How to Use
`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.
```python3
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
```python3
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)
```
## Iso2Mesh function port status
The progress of converting MATLAB-based Iso2Mesh functions to Python is
tracked in https://github.com/NeuroJSON/pyiso2mesh/issues/1
| Ported | Unit-tested | | Ported | Unit-tested |
| ------ | ------ | --- | ------ | ------ |
| > All-in-one pipeline shortcuts | | | > File I/O | |
| ✅ `v2m.m` | ✅ tested | | ✅ `saveasc.m` | ⭕️ tested |
| ✅ `v2s.m` | ✅ tested | | ✅ `savedxf.m` | ⭕️ tested |
| ✅ `s2m.m` | ✅ tested | | ✅ `savestl.m` | ⭕️ tested |
| ✅ `s2v.m` | ✅ tested | | ✅ `savebinstl.m` | ⭕️ tested |
| ✅ `m2v.m` | ⭕️ tested | | ✅ `saveinr.m` | ⭕️ tested |
| ✅ `sms.m` | ✅ tested | | ✅ `saveoff.m` | ✅ tested |
| > Streamlined mesh generation| | | ⭕️ `savesmf.m` | ⭕️ tested |
| ✅ `vol2mesh.m` | ✅ tested | | ✅ `savesurfpoly.m` | ✅ tested |
| ✅ `vol2surf.m` | ✅ tested | | ⭕️ `savegts.m` | ⭕️ tested |
| ✅ `surf2mesh.m` | ✅ tested | | ⭕️ `readgts.m` | ⭕️ tested |
| ✅ `surf2vol.m` | ✅ tested | | ⭕️ `savemsh.m` | ⭕️ tested |
| ✅ `mesh2vol.m` | ⭕️ tested | | ⭕️ `savevrml.m` | ⭕️ tested |
| > Iso2mesh main function backend| | | ✅ `readasc.m` | ⭕️ tested |
| ✅ `binsurface.m` | ✅ tested | | ⭕️ `readinr.m` | ⭕️ tested |
| ✅ `cgalv2m.m` | ✅ tested | | ✅ `readmedit.m` | ⭕️ tested |
| ✅ `cgals2m.m` | ✅ tested | | ✅ `readoff.m` | ✅ tested |
| ✅ `vol2restrictedtri.m` | ✅ tested | | ⭕️ `readsmf.m` | ⭕️ tested |
| ✅ `surf2volz.m` | ✅ tested | | ✅ `readtetgen.m` | ✅ tested |
| ✅ `mesh2mask.m` | ⭕️ tested | | ✅ `deletemeshfile.m` | ✅ tested |
| > Iso2mesh primitive meshing| | | ✅ `mcpath.m` | ✅ tested |
| ✅ `meshabox.m` | ✅ tested | | ✅ `mwpath.m` | ✅ tested |
| ✅ `meshasphere.m` | ✅ tested | | ✅ `savemedit.m` | ✅ tested |
| ✅ `meshanellip.m` | ✅ tested | | ⭕️ `savejson.m` | ⭕️ tested |
| ✅ `meshunitsphere.m` | ✅ tested | | ⭕️ `loadjson.m` | ⭕️ tested |
| ✅ `meshacylinder.m` | ✅ tested | | ⭕️ `saveubjson.m` | ⭕️ tested |
| ✅ `meshgrid5.m` | ✅ tested | | ⭕️ `loadubjson.m` | ⭕️ tested |
| ✅ `meshgrid6.m` | ✅ tested | | ⭕️ `loadmsgpack.m` | ⭕️ tested |
| ✅ `latticegrid.m` | ✅ tested | | ⭕️ `savemsgpack.m` | ⭕️ tested |
| ✅ `extrudecurve.m` | ⭕️ tested | | ⭕️ `savebj.m` | ⭕️ tested |
| ✅ `meshcylinders.m` | ✅ tested | | ⭕️ `loadbj.m` | ⭕️ tested |
| > Mesh decomposition and query| | | ⭕️ `savemphtxt.m` | ⭕️ tested |
| ✅ `finddisconnsurf.m` | ✅ tested | | ⭕️ `savetetgenele.m` | ⭕️ tested |
| ✅ `surfedge.m` | ✅ tested | | ⭕️ `savetetgennode.m` | ⭕️ tested |
| ✅ `volface.m` | ✅ tested | | ⭕️ `saveabaqus.m` | ⭕️ tested |
| ✅ `extractloops.m` | ✅ tested | | ⭕️ `savenirfast.m` | ⭕️ tested |
| ✅ `meshconn.m` | ✅ tested | | ⭕️ `readnirfast.m` | ⭕️ tested |
| ✅ `meshcentroid.m` | ✅ tested | | ⭕️ `readnifti.m` | ⭕️ tested |
| ✅ `nodevolume.m` | ✅ tested | | ⭕️ `readmptiff.m` | ⭕️ tested |
| ✅ `elemvolume.m` | ✅ tested | | ⭕️ `loadjsnirf.m` | ⭕️ tested |
| ✅ `neighborelem.m` | ✅ tested | | ⭕️ `savejsnirf.m` | ⭕️ tested |
| ✅ `layersurf.m` | ⭕️ tested | | ⭕️ `loadsnirf.m` | ⭕️ tested |
| ✅ `faceneighbors.m` | ✅ tested | | ⭕️ `savesnirf.m` | ⭕️ tested |
| ✅ `edgeneighbors.m` | ✅ tested | | ⭕️ `readobjmesh.m` | ⭕️ tested |
| ✅ `maxsurf.m` | ⭕️ tested | | ⭕️ `loadjmesh.m` | ⭕️ tested |
| ✅ `flatsegment.m` | ⭕️ tested | | ⭕️ `readobjmesh.m` | ⭕️ tested |
| ✅ `orderloopedge.m` | ⭕️ tested | | > Volumetric image pre-processing| |
| ✅ `mesheuler.m` | ✅ tested | | ⭕️ `bwislands.m` | ⭕️ tested |
| ✅ `bbxflatsegment.m` | ⭕️ tested | | ⭕️ `fillholes3d.m` | ⭕️ tested |
| ✅ `surfplane.m` | ⭕️ tested | | ⭕️ `deislands2d.m` | ⭕️ tested |
| ✅ `surfinterior.m` | ⭕️ tested | | ⭕️ `deislands3d.m` | ⭕️ tested |
| ✅ `surfpart.m` | ⭕️ tested | | ⭕️ `ndgaussian.m` | ⭕️ tested |
| ✅ `surfseeds.m` | ⭕️ tested | | ⭕️ `ndimfilter.m` | ⭕️ tested |
| ✅ `meshquality.m` | ✅ tested | | ⭕️ `imedge3d.m` | ⭕️ tested |
| ✅ `meshedge.m` | ✅ tested | | ⭕️ `internalpoint.m` | ⭕️ tested |
| ✅ `meshface.m` | ✅ tested | | ⭕️ `smoothbinvol.m` | ⭕️ tested |
| ✅ `surfacenorm.m` | ✅ tested | | ⭕️ `thickenbinvol.m` | ⭕️ tested |
| ✅ `nodesurfnorm.m` | ✅ tested | | ⭕️ `thinbinvol.m` | ⭕️ tested |
| ✅ `uniqedges.m` | ✅ tested | | ⭕️ `maskdist.m` | ⭕️ tested |
| ✅ `uniqfaces.m` | ✅ tested | | > Mesh plotting| |
| ✅ `advancefront.m` | ⭕️ tested | | ✅ `plotmesh.m` | ✅ tested |
| ✅ `innersurf.m` | ⭕️ tested | | ✅ `plotsurf.m` | ✅ tested |
| ✅ `outersurf.m` | ⭕️ tested | | ✅ `plottetra.m` | ✅ tested |
| ✅ `surfvolume.m` | ✅ tested | | ✅ `plotedges.m` | ✅ tested |
| ✅ `insurface.m` | ✅ tested | | ✅ `qmeshcut.m` | ✅ tested |
| > Mesh processing and reparing| | | > Miscellaneous functions| |
| ✅ `meshcheckrepair.m` | ✅ tested | | ⭕️ `surfdiffuse.m` | ⭕️ tested |
| ✅ `meshreorient.m` | ✅ tested | | ⭕️ `volmap2mesh.m` | ⭕️ tested |
| ✅ `removedupelem.m` | ✅ tested | | ⭕️ `isoctavemesh.m` | ⭕️ tested |
| ✅ `removedupnodes.m` | ✅ tested | | ⭕️ `getvarfrom.m` | ⭕️ tested |
| ✅ `removeisolatednode.m` | ✅ tested | | ✅ `raytrace.m` | ✅ tested |
| ✅ `removeisolatedsurf.m` | ⭕️ tested | | ⭕️ `linextriangle.m` | ⭕️ tested |
| ✅ `surfaceclean.m` | ⭕️ tested | | ⭕️ `getplanefrom3pt.m` | ⭕️ tested |
| ✅ `getintersecttri.m` | ⭕️ tested | | ✅ `getexeext.m` | ✅ tested |
| ✅ `delendelem.m` | ⭕️ tested | | ✅ `fallbackexeext.m` | ✅ tested |
| ✅ `surfreorient.m` | ✅ tested | | ⭕️ `iso2meshver.m` | ⭕️ tested |
| > Mesh registration | | | ⭕️ `raysurf.m` | ⭕️ tested |
| ✅ `proj2mesh.m` | ⭕️ tested | | ⭕️ `getoptkey.m` | ⭕️ tested |
| ✅ `dist2surf.m` | ⭕️ tested | | ✅ `rotatevec3d.m` | ⭕️ tested |
| ✅ `regpt2surf.m` | ⭕️ tested | | ✅ `rotmat2vec.m` | ⭕️ tested |
| ✅ `affinemap.m` | ⭕️ tested | | ✅ `varargin2struct.m` | ⭕️ tested |
| > Polyline handling| | | ✅ `jsonopt.m` | ⭕️ tested |
| ⭕️ `slicesurf.m` | ⭕️ tested | | ⭕️ `mergestruct.m` | ⭕️ tested |
| ⭕️ `slicesurf3.m` | ⭕️ tested | | ⭕️ `orthdisk.m` | ⭕️ tested |
| ⭕️ `polylinelen.m` | ⭕️ tested | | ⭕️ `nestbracket2dim.m` | ⭕️ tested |
| ⭕️ `polylinesimplify.m` | ⭕️ tested | | ⭕️ `memmapstream.m` | ⭕️ tested |
| ⭕️ `polylineinterp.m` | ⭕️ tested | | ⭕️ `aos2soa.m` | ⭕️ tested |
| ⭕️ `closestnode.m` | ⭕️ tested | | ⭕️ `soa2aos.m` | ⭕️ tested |
| > Mesh resampling and optimization| |
| ✅ `meshresample.m` | ✅ tested |
| ✅ `remeshsurf.m` | ✅ tested |
| ✅ `smoothsurf.m` | ✅ tested |
| ✅ `sortmesh.m` | ⭕️ tested |
| ✅ `mergemesh.m` | ✅ tested |
| ✅ `meshrefine.m` | ✅ tested |
| ✅ `mergesurf.m` | ⭕️ tested |
| ✅ `surfboolean.m` | ✅ tested |
| ✅ `fillsurf.m` | ⭕️ tested |
| ✅ `highordertet.m` | ✅ tested |
| ✅ `elemfacecenter.m` | ✅ tested |
| ✅ `barydualmesh.m` | ✅ tested |
| ✅ `meshinterp.m` | ⭕️ tested |
| ✅ `meshremap.m` | ⭕️ tested |
| ✅ `extrudesurf.m` | ⭕️ tested |
## Acknowledgement
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](https://reporter.nih.gov/project-details/10308329) and
[R01-CA204443](https://reporter.nih.gov/project-details/10982160), with the author,
Dr. Qianqian Fang, serving as the principle investigator on both awards.
Raw data
{
"_id": null,
"home_page": "https://github.com/NeuroJSON/pyiso2mesh",
"name": "iso2mesh",
"maintainer": "Qianqian Fang",
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Iso2Mesh, Mesh generation, Finite element method, FEM, FEA, MATLAB, Mesh-based Monte Carlo, CGAL, Tetgen, CSG, Boolean, Surface mesh, Tetrahedral mesh, Modeling, Multiphysics, Image processing",
"author": "Qianqian Fang",
"author_email": "fangqq@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2c/75/d74dbc104e0dbae234e8dcf6e7b3ffd4584d836e7bb42b91ea7c6226b0ec/iso2mesh-0.3.8.tar.gz",
"platform": "any",
"description": "\n\n# pyiso2mesh - One-liner 3D Surface and Tetrahedral Mesh Generation Toolbox\n\n* **Copyright**: (C) Qianqian Fang (2024-2025) <q.fang at neu.edu>\n* **License**: GNU Public License V3 or later\n* **Version**: 0.3.8\n* **URL**: [https://pypi.org/project/iso2mesh/](https://pypi.org/project/iso2mesh/)\n* **Homepage**: [https://iso2mesh.sf.net](https://iso2mesh.sf.net)\n* **Github**: [https://github.com/NeuroJSON/pyiso2mesh](https://github.com/NeuroJSON/pyiso2mesh)\n* **Acknowledgement**: This project is supported by the US National Institute of Health (NIH)\n grants [U24-NS124027](https://reporter.nih.gov/project-details/10308329) and \n [R01-CA204443](https://reporter.nih.gov/project-details/10982160)\n\n\n\n\nIso2Mesh is a versatile 3D mesh generation toolbox,\noriginally developed for MATLAB and GNU Octave in 2007.\nIt is designed for the easy creation of high-quality surface and\ntetrahedral meshes from 3D volumetric images. It includes\nover 200 mesh processing scripts and programs, which can operate\nindependently or in conjunction with external open-source\nmeshing tools. The Iso2Mesh toolbox can directly convert\n3-D image stacks\u2014including binary, segmented, or grayscale\nimages such as MRI or CT scans\u2014into high-quality volumetric\nmeshes. This makes it especially suitable for multi-modality\nmedical imaging data analysis and multi-physics modeling.\n\nThe `iso2mesh` Python module provides a re-implementation of Iso2Mesh\nin the native Python language, following algorithms\nsimilar to those in the MATLAB/Octave versions of Iso2Mesh.\n\n## How to Install\n\n* PIP: `python3 -m pip install iso2mesh`\n* PIP+Git (latest version): `python3 -m pip install git+https://github.com/NeuroJSON/pyiso2mesh.git`\n\nMacOS users: you need to run the following commands to install this module\n\n```\npython3 -m venv /tmp/pyiso2mesh-venv\nsource /tmp/pyiso2mesh-venv/bin/activate\npython3 -m pip install iso2mesh\n```\n\n## Runtime Dependencies\n\n* **numpy**: `pyiso2mesh` relies heavily on vectorized NumPy\n matrix operations, similar to those used in the MATLAB version of Iso2Mesh.\n* **matplotlib**: Used for plotting results. Install with `pip install matplotlib`.\n* **jdata** (optional): A lightweight module to load JSON-encoded volume/mesh data,\n including dynamically downloading data from [NeuroJSON.io](https://neurojson.io) `pip install jdata`.\n\nMany core meshing functions in `pyiso2mesh` require the set of mesh processing\nexecutables provided in the Iso2Mesh package under the `iso2mesh/bin` folder.\nThese binaries are not needed at the time when installing `pyiso2mesh`; when\nany of them becomes needed during mesh processing, `pyiso2mesh` dynamically\ndownloads these external tools and store those under the user's home directory\n(`$HOME/iso2mesh-tools`) for future use. This download operation only runs once.\n\n## Build Instructions\n\n### Build Dependencies\n\n* **Operating System**: The module is written in pure Python and is portable across platforms, \nincluding Windows, Linux, and macOS.\n\n### Build Steps\n\n1. Install the `build` module: `python3 -m pip install --upgrade build`\n\n2. Clone the repository:\n\n```\ngit clone --recursive https://github.com/NeuroJSON/pyiso2mesh.git\ncd pyiso2mesh\n```\n\n3. Type `python3 -m build` to build the package\n\n4. A platform-independent `noarch` module will be built locally. You should see a package\n named `iso2mesh-x.x.x-py2.py3-none-any.whl` in the `dist/` subfolder.\n\n5. You can install the locally built package using:\n `python3 -m pip install --force-reinstall iso2mesh-*.whl`\n\n### Run built-in unit-tests\n\nIf you want to modify the source, and verify that it still produces correct results, you can run\nthe built-in unit-test script inside the downloaded git repository by using this command\ninside the `pyiso2mesh` root folder\n\n```\npython3 -m unittest test.run_test\n```\n\n\n## How to Use\n\n`pyiso2mesh` inherits the \"trademark\" **one-liner mesh generator** style from its MATLAB/Octave counterpart\nand maintains high compatibility with Iso2Mesh in terms of function names, input/output parameters,\nand node/element ordering and indexing conventions.\n\nAll index matrices, such as `face` or `elem`, in the generated mesh data are 1-based (i.e.,\nthe lowest index is 1, not 0). This design ensures compatibility with the MATLAB/Octave Iso2Mesh outputs.\n\n```python3\nimport iso2mesh as i2m\nimport numpy as np\n\n# creating basic grid-like meshes\nno, el = i2m.meshgrid5([0,1], [0,2], [1,2])\ni2m.plotmesh(no, el)\n\nno, el = i2m.meshgrid6([0,1], [0,2], [1,2])\ni2m.plotmesh(no, el)\n\n# meshing a box and plotting with selector\nno, fc, el = i2m.meshabox([0,0,0], [30, 20, 10], 2)\ni2m.plotmesh(no, el, 'z < 5')\n\n# computing various mesh data\n\nfc2 = i2m.volface(el)\ned1 = i2m.surfedge(fc[:-1,:])\nfvol = i2m.elemvolume(no, fc)\nevol = i2m.elemvolume(no, el)\nfacenb = i2m.faceneighbors(el)\nsnorm = i2m.surfacenorm(no, fc)\ncv = i2m.meshcentroid(no, el)\ncf = i2m.meshcentroid(no, fc)\n\n# plotting nodes with markers\ni2m.plotmesh(cf, 'r.')\n\n# cleaning a surface mesh\nno1, fc1 = i2m.meshcheckrepair(no, fc)\n\n# smoothing a surface mesh\nno2 = i2m.sms(no1, fc1, 20)\n\ni2m.plotmesh(no2, fc1)\n\n# meshing a cylinder\nno, fc, el = i2m.meshacylinder([0,0,0], [0, 0, 10], 2, 50)\ni2m.plotmesh(no, el, 'x < 0', edgecolor='r')\n\n# creating and plotting polyhedral solids (PLCs)\nmesh = i2m.latticegrid([0,1],[0,1,2], [0,2])\ni2m.plotmesh(mesh[0], mesh[1], alpha=0.5, linestyle='--')\n\n# mesh and label PLC based domains using tetgen1.5\nmesh2 = i2m.s2m(mesh[0], mesh[1], 1, 0.03, method='tetgen1.5')\ni2m.plotmesh(mesh2[0], mesh2[1], alpha=0.5)\n```\n\n`pyiso2mesh` subdivides all functions into sub-modules (**core, geometry, plot,\nio, trait, modify, utils, register, raster**) that can be individually\nimported. For example, if one wants to create tetrahedral meshes from a 3-D binary\narray, one can use\n\n```python3\nfrom iso2mesh.core import v2m, v2s\nfrom iso2mesh.plot import plotmesh\nimport numpy as np\n\nimg = np.zeros([60,60,60], dtype=np.uint8)\nimg[20:41, 10:51, 30:] = 1\n\nno, el, fc = v2m(img, [], 3, 100, 'cgalmesh')\nplotmesh(no, el)\n\nno, fc, _, _ = v2s(img, 0.5, {'distbound': 0.2})\nax = plotmesh(no, fc, 'y < 30', alpha=0.5, edgecolor='none')\nplotmesh(no, fc, 'y > 30', parent = ax)\n```\n\n## Iso2Mesh function port status\n\nThe progress of converting MATLAB-based Iso2Mesh functions to Python is\ntracked in https://github.com/NeuroJSON/pyiso2mesh/issues/1\n\n| Ported | Unit-tested | | Ported | Unit-tested |\n| ------ | ------ | --- | ------ | ------ |\n| > All-in-one pipeline shortcuts | | | > File I/O | |\n| \u2705 `v2m.m` | \u2705 tested | | \u2705 `saveasc.m` | \u2b55\ufe0f tested |\n| \u2705 `v2s.m` | \u2705 tested | | \u2705 `savedxf.m` | \u2b55\ufe0f tested |\n| \u2705 `s2m.m` | \u2705 tested | | \u2705 `savestl.m` | \u2b55\ufe0f tested |\n| \u2705 `s2v.m` | \u2705 tested | | \u2705 `savebinstl.m` | \u2b55\ufe0f tested |\n| \u2705 `m2v.m` | \u2b55\ufe0f tested | | \u2705 `saveinr.m` | \u2b55\ufe0f tested |\n| \u2705 `sms.m` | \u2705 tested | | \u2705 `saveoff.m` | \u2705 tested |\n| > Streamlined mesh generation| | | \u2b55\ufe0f `savesmf.m` | \u2b55\ufe0f tested |\n| \u2705 `vol2mesh.m` | \u2705 tested | | \u2705 `savesurfpoly.m` | \u2705 tested |\n| \u2705 `vol2surf.m` | \u2705 tested | | \u2b55\ufe0f `savegts.m` | \u2b55\ufe0f tested |\n| \u2705 `surf2mesh.m` | \u2705 tested | | \u2b55\ufe0f `readgts.m` | \u2b55\ufe0f tested |\n| \u2705 `surf2vol.m` | \u2705 tested | | \u2b55\ufe0f `savemsh.m` | \u2b55\ufe0f tested |\n| \u2705 `mesh2vol.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `savevrml.m` | \u2b55\ufe0f tested |\n| > Iso2mesh main function backend| | | \u2705 `readasc.m` | \u2b55\ufe0f tested |\n| \u2705 `binsurface.m` | \u2705 tested | | \u2b55\ufe0f `readinr.m` | \u2b55\ufe0f tested |\n| \u2705 `cgalv2m.m` | \u2705 tested | | \u2705 `readmedit.m` | \u2b55\ufe0f tested |\n| \u2705 `cgals2m.m` | \u2705 tested | | \u2705 `readoff.m` | \u2705 tested |\n| \u2705 `vol2restrictedtri.m` | \u2705 tested | | \u2b55\ufe0f `readsmf.m` | \u2b55\ufe0f tested |\n| \u2705 `surf2volz.m` | \u2705 tested | | \u2705 `readtetgen.m` | \u2705 tested |\n| \u2705 `mesh2mask.m` | \u2b55\ufe0f tested | | \u2705 `deletemeshfile.m` | \u2705 tested |\n| > Iso2mesh primitive meshing| | | \u2705 `mcpath.m` | \u2705 tested |\n| \u2705 `meshabox.m` | \u2705 tested | | \u2705 `mwpath.m` | \u2705 tested |\n| \u2705 `meshasphere.m` | \u2705 tested | | \u2705 `savemedit.m` | \u2705 tested |\n| \u2705 `meshanellip.m` | \u2705 tested | | \u2b55\ufe0f `savejson.m` | \u2b55\ufe0f tested |\n| \u2705 `meshunitsphere.m` | \u2705 tested | | \u2b55\ufe0f `loadjson.m` | \u2b55\ufe0f tested |\n| \u2705 `meshacylinder.m` | \u2705 tested | | \u2b55\ufe0f `saveubjson.m` | \u2b55\ufe0f tested |\n| \u2705 `meshgrid5.m` | \u2705 tested | | \u2b55\ufe0f `loadubjson.m` | \u2b55\ufe0f tested |\n| \u2705 `meshgrid6.m` | \u2705 tested | | \u2b55\ufe0f `loadmsgpack.m` | \u2b55\ufe0f tested |\n| \u2705 `latticegrid.m` | \u2705 tested | | \u2b55\ufe0f `savemsgpack.m` | \u2b55\ufe0f tested |\n| \u2705 `extrudecurve.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `savebj.m` | \u2b55\ufe0f tested |\n| \u2705 `meshcylinders.m` | \u2705 tested | | \u2b55\ufe0f `loadbj.m` | \u2b55\ufe0f tested |\n| > Mesh decomposition and query| | | \u2b55\ufe0f `savemphtxt.m` | \u2b55\ufe0f tested |\n| \u2705 `finddisconnsurf.m` | \u2705 tested | | \u2b55\ufe0f `savetetgenele.m` | \u2b55\ufe0f tested |\n| \u2705 `surfedge.m` | \u2705 tested | | \u2b55\ufe0f `savetetgennode.m` | \u2b55\ufe0f tested |\n| \u2705 `volface.m` | \u2705 tested | | \u2b55\ufe0f `saveabaqus.m` | \u2b55\ufe0f tested |\n| \u2705 `extractloops.m` | \u2705 tested | | \u2b55\ufe0f `savenirfast.m` | \u2b55\ufe0f tested |\n| \u2705 `meshconn.m` | \u2705 tested | | \u2b55\ufe0f `readnirfast.m` | \u2b55\ufe0f tested |\n| \u2705 `meshcentroid.m` | \u2705 tested | | \u2b55\ufe0f `readnifti.m` | \u2b55\ufe0f tested |\n| \u2705 `nodevolume.m` | \u2705 tested | | \u2b55\ufe0f `readmptiff.m` | \u2b55\ufe0f tested |\n| \u2705 `elemvolume.m` | \u2705 tested | | \u2b55\ufe0f `loadjsnirf.m` | \u2b55\ufe0f tested |\n| \u2705 `neighborelem.m` | \u2705 tested | | \u2b55\ufe0f `savejsnirf.m` | \u2b55\ufe0f tested |\n| \u2705 `layersurf.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `loadsnirf.m` | \u2b55\ufe0f tested |\n| \u2705 `faceneighbors.m` | \u2705 tested | | \u2b55\ufe0f `savesnirf.m` | \u2b55\ufe0f tested |\n| \u2705 `edgeneighbors.m` | \u2705 tested | | \u2b55\ufe0f `readobjmesh.m` | \u2b55\ufe0f tested |\n| \u2705 `maxsurf.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `loadjmesh.m` | \u2b55\ufe0f tested |\n| \u2705 `flatsegment.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `readobjmesh.m` | \u2b55\ufe0f tested |\n| \u2705 `orderloopedge.m` | \u2b55\ufe0f tested | | > Volumetric image pre-processing| |\n| \u2705 `mesheuler.m` | \u2705 tested | | \u2b55\ufe0f `bwislands.m` | \u2b55\ufe0f tested |\n| \u2705 `bbxflatsegment.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `fillholes3d.m` | \u2b55\ufe0f tested |\n| \u2705 `surfplane.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `deislands2d.m` | \u2b55\ufe0f tested |\n| \u2705 `surfinterior.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `deislands3d.m` | \u2b55\ufe0f tested |\n| \u2705 `surfpart.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `ndgaussian.m` | \u2b55\ufe0f tested |\n| \u2705 `surfseeds.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `ndimfilter.m` | \u2b55\ufe0f tested |\n| \u2705 `meshquality.m` | \u2705 tested | | \u2b55\ufe0f `imedge3d.m` | \u2b55\ufe0f tested |\n| \u2705 `meshedge.m` | \u2705 tested | | \u2b55\ufe0f `internalpoint.m` | \u2b55\ufe0f tested |\n| \u2705 `meshface.m` | \u2705 tested | | \u2b55\ufe0f `smoothbinvol.m` | \u2b55\ufe0f tested |\n| \u2705 `surfacenorm.m` | \u2705 tested | | \u2b55\ufe0f `thickenbinvol.m` | \u2b55\ufe0f tested |\n| \u2705 `nodesurfnorm.m` | \u2705 tested | | \u2b55\ufe0f `thinbinvol.m` | \u2b55\ufe0f tested |\n| \u2705 `uniqedges.m` | \u2705 tested | | \u2b55\ufe0f `maskdist.m` | \u2b55\ufe0f tested |\n| \u2705 `uniqfaces.m` | \u2705 tested | | > Mesh plotting| |\n| \u2705 `advancefront.m` | \u2b55\ufe0f tested | | \u2705 `plotmesh.m` | \u2705 tested |\n| \u2705 `innersurf.m` | \u2b55\ufe0f tested | | \u2705 `plotsurf.m` | \u2705 tested |\n| \u2705 `outersurf.m` | \u2b55\ufe0f tested | | \u2705 `plottetra.m` | \u2705 tested |\n| \u2705 `surfvolume.m` | \u2705 tested | | \u2705 `plotedges.m` | \u2705 tested |\n| \u2705 `insurface.m` | \u2705 tested | | \u2705 `qmeshcut.m` | \u2705 tested |\n| > Mesh processing and reparing| | | > Miscellaneous functions| |\n| \u2705 `meshcheckrepair.m` | \u2705 tested | | \u2b55\ufe0f `surfdiffuse.m` | \u2b55\ufe0f tested |\n| \u2705 `meshreorient.m` | \u2705 tested | | \u2b55\ufe0f `volmap2mesh.m` | \u2b55\ufe0f tested |\n| \u2705 `removedupelem.m` | \u2705 tested | | \u2b55\ufe0f `isoctavemesh.m` | \u2b55\ufe0f tested |\n| \u2705 `removedupnodes.m` | \u2705 tested | | \u2b55\ufe0f `getvarfrom.m` | \u2b55\ufe0f tested |\n| \u2705 `removeisolatednode.m` | \u2705 tested | | \u2705 `raytrace.m` | \u2705 tested |\n| \u2705 `removeisolatedsurf.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `linextriangle.m` | \u2b55\ufe0f tested |\n| \u2705 `surfaceclean.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `getplanefrom3pt.m` | \u2b55\ufe0f tested |\n| \u2705 `getintersecttri.m` | \u2b55\ufe0f tested | | \u2705 `getexeext.m` | \u2705 tested |\n| \u2705 `delendelem.m` | \u2b55\ufe0f tested | | \u2705 `fallbackexeext.m` | \u2705 tested |\n| \u2705 `surfreorient.m` | \u2705 tested | | \u2b55\ufe0f `iso2meshver.m` | \u2b55\ufe0f tested |\n| > Mesh registration | | | \u2b55\ufe0f `raysurf.m` | \u2b55\ufe0f tested |\n| \u2705 `proj2mesh.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `getoptkey.m` | \u2b55\ufe0f tested |\n| \u2705 `dist2surf.m` | \u2b55\ufe0f tested | | \u2705 `rotatevec3d.m` | \u2b55\ufe0f tested |\n| \u2705 `regpt2surf.m` | \u2b55\ufe0f tested | | \u2705 `rotmat2vec.m` | \u2b55\ufe0f tested |\n| \u2705 `affinemap.m` | \u2b55\ufe0f tested | | \u2705 `varargin2struct.m` | \u2b55\ufe0f tested |\n| > Polyline handling| | | \u2705 `jsonopt.m` | \u2b55\ufe0f tested |\n| \u2b55\ufe0f `slicesurf.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `mergestruct.m` | \u2b55\ufe0f tested |\n| \u2b55\ufe0f `slicesurf3.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `orthdisk.m` | \u2b55\ufe0f tested |\n| \u2b55\ufe0f `polylinelen.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `nestbracket2dim.m` | \u2b55\ufe0f tested |\n| \u2b55\ufe0f `polylinesimplify.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `memmapstream.m` | \u2b55\ufe0f tested |\n| \u2b55\ufe0f `polylineinterp.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `aos2soa.m` | \u2b55\ufe0f tested |\n| \u2b55\ufe0f `closestnode.m` | \u2b55\ufe0f tested | | \u2b55\ufe0f `soa2aos.m` | \u2b55\ufe0f tested |\n| > Mesh resampling and optimization| |\n| \u2705 `meshresample.m` | \u2705 tested |\n| \u2705 `remeshsurf.m` | \u2705 tested |\n| \u2705 `smoothsurf.m` | \u2705 tested |\n| \u2705 `sortmesh.m` | \u2b55\ufe0f tested |\n| \u2705 `mergemesh.m` | \u2705 tested |\n| \u2705 `meshrefine.m` | \u2705 tested |\n| \u2705 `mergesurf.m` | \u2b55\ufe0f tested |\n| \u2705 `surfboolean.m` | \u2705 tested |\n| \u2705 `fillsurf.m` | \u2b55\ufe0f tested |\n| \u2705 `highordertet.m` | \u2705 tested |\n| \u2705 `elemfacecenter.m` | \u2705 tested |\n| \u2705 `barydualmesh.m` | \u2705 tested |\n| \u2705 `meshinterp.m` | \u2b55\ufe0f tested |\n| \u2705 `meshremap.m` | \u2b55\ufe0f tested |\n| \u2705 `extrudesurf.m` | \u2b55\ufe0f tested |\n\n\n\n## Acknowledgement\n\nThe `pyiso2mesh` module was converted from the MATLAB/Octave version of\nof Iso2Mesh (https://github.com/fangq/iso2mesh) written by the same author.\n\nWe utilized large-language-model (LLM) and AI chatbot in the initial MATLAB-to-Python\nconversion, with specific instructions to **faithfully replicate** the algorithms\ndeveloped in the MATLAB code to avoid introducing external copyrighted materials\ninto this toolbox. With the assumption that the AI chatbot functions primarily\nas an automated syntax translator without altering the originality of the code,\nthe upstream author of the original MATLAB-based Iso2Mesh retains the full copyright\nof this derived Python module.\n\nThe initial translation was further manually tested, adjusted and restructured\nto produce matching outputs as the original MATLAB toolbox. Dr. Edward Xu\n<xu.ed at northeastern.edu> had contributed to the initial conversion and\ntesting of a subset of functions in the `geometry.py` and `trait.py` units.\n\nThe development of this software is supported by the US National Institute of Health (NIH)\nunder research awards [U24-NS124027](https://reporter.nih.gov/project-details/10308329) and \n[R01-CA204443](https://reporter.nih.gov/project-details/10982160), with the author,\nDr. Qianqian Fang, serving as the principle investigator on both awards.\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "One-liner 3D Surface and Tetrahedral Mesh Generation Toolbox",
"version": "0.3.8",
"project_urls": {
"Homepage": "https://github.com/NeuroJSON/pyiso2mesh"
},
"split_keywords": [
"iso2mesh",
" mesh generation",
" finite element method",
" fem",
" fea",
" matlab",
" mesh-based monte carlo",
" cgal",
" tetgen",
" csg",
" boolean",
" surface mesh",
" tetrahedral mesh",
" modeling",
" multiphysics",
" image processing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eaa2e31d14cf811c36382dbb732a04642c70229d88c5993657dfc6d3437be0e9",
"md5": "6da6e1b3a136f56d395ca250b3616da7",
"sha256": "8857adf0477500569bd34a760117c2129bca063389e2798a55e36300f2f5913f"
},
"downloads": -1,
"filename": "iso2mesh-0.3.8-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "6da6e1b3a136f56d395ca250b3616da7",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 90175,
"upload_time": "2025-07-10T06:00:40",
"upload_time_iso_8601": "2025-07-10T06:00:40.684865Z",
"url": "https://files.pythonhosted.org/packages/ea/a2/e31d14cf811c36382dbb732a04642c70229d88c5993657dfc6d3437be0e9/iso2mesh-0.3.8-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2c75d74dbc104e0dbae234e8dcf6e7b3ffd4584d836e7bb42b91ea7c6226b0ec",
"md5": "38bae2e9a458b5b37c8b9d0b585e1ff8",
"sha256": "671d0e6f8984419d3173b3de02766c2506987a44c9bd96f740c26fa8780bd219"
},
"downloads": -1,
"filename": "iso2mesh-0.3.8.tar.gz",
"has_sig": false,
"md5_digest": "38bae2e9a458b5b37c8b9d0b585e1ff8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 89233,
"upload_time": "2025-07-10T06:00:42",
"upload_time_iso_8601": "2025-07-10T06:00:42.985535Z",
"url": "https://files.pythonhosted.org/packages/2c/75/d74dbc104e0dbae234e8dcf6e7b3ffd4584d836e7bb42b91ea7c6226b0ec/iso2mesh-0.3.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 06:00:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NeuroJSON",
"github_project": "pyiso2mesh",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "iso2mesh"
}
JSON
