{"id":17744080,"url":"https://github.com/fangq/iso2mesh","last_synced_at":"2025-05-16T17:06:40.708Z","repository":{"id":26353720,"uuid":"29802702","full_name":"fangq/iso2mesh","owner":"fangq","description":"Iso2Mesh - a 3D surface and volumetric mesh generator for MATLAB/Octave","archived":false,"fork":false,"pushed_at":"2025-03-31T03:05:10.000Z","size":131545,"stargazers_count":194,"open_issues_count":8,"forks_count":76,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-05-14T07:08:35.196Z","etag":null,"topics":["computer-graphics","image-processing","matlab","medical-image-processing","mesh-generation","modeling-tools","visualization"],"latest_commit_sha":null,"homepage":"http://iso2mesh.sf.net","language":"MATLAB","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fangq.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.txt","contributing":null,"funding":null,"license":"COPYING.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.txt","dei":"deislands2d.m","publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-01-25T04:33:07.000Z","updated_at":"2025-05-01T13:58:02.000Z","dependencies_parsed_at":"2022-07-09T09:46:14.098Z","dependency_job_id":"6266b3cf-365a-42f2-978e-9601751d071f","html_url":"https://github.com/fangq/iso2mesh","commit_stats":{"total_commits":669,"total_committers":12,"mean_commits":55.75,"dds":"0.026905829596412523","last_synced_commit":"7d62780020c34d9fbc7b5d29f296d627a238969d"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fiso2mesh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fiso2mesh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fiso2mesh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fiso2mesh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fangq","download_url":"https://codeload.github.com/fangq/iso2mesh/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254573588,"owners_count":22093731,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computer-graphics","image-processing","matlab","medical-image-processing","mesh-generation","modeling-tools","visualization"],"created_at":"2024-10-26T06:41:54.568Z","updated_at":"2025-05-16T17:06:40.690Z","avatar_url":"https://github.com/fangq.png","language":"MATLAB","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Iso2Mesh: An Image-based 3D Surface and Volumetric Mesh Generator\n\n|                |                          |\n|----------------|------------------------- |\n| **Author**     | Qianqian Fang            |\n| **E-mail**     | \u003cq.fang at neu.edu\u003e      |\n| **Department** | Bioengineering           |\n| **Institute**  | Northeastern University  |\n| **Address**    | 360 Huntington Ave, Boston, MA 02115 |\n| **Version**    | 1.9.8 (Pot Stickers)     |\n| **License**    | GPL v2 or later (see COPYING) (this license does not cover the binaries under the bin/ directory, see Section III for more details) |\n| **URL**        | http://iso2mesh.sf.net   |\n\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Iso2Mesh Suite](#iso2mesh-suite)\n- [Overview of functions](#overview-of-functions)\n- [Compiling Iso2mesh](#compiling-iso2mesh)\n- [Acknowledgement](#acknowledgement)\n\n#### Introduction\n\n\"Iso2Mesh\" is a MATLAB/Octave-based mesh generation toolbox,\ndesigned for easy creation of high quality surface and \ntetrahedral meshes from 3D volumetric images. It contains \nover 200 mesh processing scripts/programs, working \neither independently or interacting with external free \nmeshing utilities. Iso2Mesh toolbox can directly convert\na 3D image stack, including binary, segmented or gray-scale \nimages such as MRI or CT scans, into quality volumetric \nmeshes. This makes it particularly suitable for multi-modality \nmedical imaging data analysis and multi-physics modeling.\nAbove all, iso2mesh is open-source. You can download it for \nfree. You are also allowed to extend the toolbox for your\nown research and share with other users. Iso2Mesh is \ncross-platform and is compatible with both MATLAB and GNU Octave \n(a free MATLAB clone).\n\nThe details of this toolbox can be found in the following\npapers (citing the first paper is highly encouraged):\n\n- Anh Phong Tran, Shijie Yan and Qianqian Fang*, (2020) \"Improving \n model-based fNIRS analysis using mesh-based anatomical and \n light-transport models,\" Neurophotonics, 7(1), 015008\n- Qianqian Fang and David Boas, \"Tetrahedral mesh generation from \n volumetric binary and gray-scale images,\" Proceedings of IEEE \n International Symposium on Biomedical Imaging (ISBI 2009), \n pp. 1142-1145, 2009\n\nThe first paper published recently describes a fully automated high-quality\n[brain mesh generation pipeline](http://mcx.space/brain2mesh) \nbuilt upon Iso2Mesh, providing a showcase for nearly all core\nfunctionalities provided in this toolbox.\n\n#### Iso2Mesh Suite\n\nIn addition to convenient 3D mesh generation functionalities,\nthe development of Iso2Mesh has also resulted in a number of \nsubmodules that have also received wide adoption - some \nare even more popular than Iso2Mesh itself. For example:\n\n- JSONLab (http://openjdata.org/jsonlab): a JSON/UBJSON/MassagePack \n encoder and decoder [(Editor Pick-of-the-week, Popular File 2018)](https://www.mathworks.com/matlabcentral/fileexchange/33381-jsonlab-a-toolbox-to-encode-decode-json-files)\n- Brain2Mesh (http://mcx.space/brain2mesh): a fully automated\n high-quality brain mesh generation toolbox built on Iso2Mesh\n- JNIfTI (http://github.com/NeuroJSON/jnifti): a fast and portable \n NIfTI-1/2 reader/writer and next-gen NIfTI file format\n- Metch (http://iso2mesh.sf.net/metch): a 3D mesh registration toolbox\n- JData specification (http://openjdata.org): a highly portable\n easy-to-use scientific data annotation method and specification\n- ZMat (http://github.com/NeuroJSON/zmat): a data compression library \n and MATLAB/Octave toolbox\n\nCurrently, Iso2Mesh and its submodules are broadly distributed \namong popular open-source MATLAB toolboxes, especially among major \nneuroimaging tools, including\n\n- Fieldtrip (http://www.fieldtriptoolbox.org) [[iso2mesh/jsonlab](https://github.com/fieldtrip/fieldtrip/tree/master/external/iso2mesh)]\n- BrainStorm (https://neuroimage.usc.edu/brainstorm) [[iso2mesh/brain2mesh/easyh5](https://neuroimage.usc.edu/brainstorm/Tutorials/FemMesh#Mesh_tools)]\n- Lead-DBS (http://www.lead-dbs.org) [[iso2mesh](https://github.com/netstim/leaddbs/tree/master/ext_libs/iso2mesh)]\n- ROAST (https://www.parralab.org/roast) [[iso2mesh](https://github.com/andypotatohy/roast/tree/master/lib/iso2mesh)]\n- HOMER2 (https://github.com/BUNPC/AtlasViewer) [[iso2mesh/metch](https://github.com/BUNPC/AtlasViewer/tree/master/iso2mesh)]\n- REST (https://github.com/goodshawn12/REST) [[iso2mesh](https://github.com/goodshawn12/REST/tree/master/dependencies/iso2mesh)]\n\n#### Overview of functions\n\nCreation of high-quality surface and tetrahedral meshes \nfrom volumetric images has been a challenging task. \nThere are very limited software and resources available \nfor this purpose. Commercial tools, such as Mimics \nand Simpleware, are both expensive and limited in flexibility. \nIso2Mesh was developed as a free alternative to these \nexpensive commercial tools and provides researchers a highly\nflexible, modular and streamlined image-based mesh \ngeneration pipeline. Intuitive interfaces and rich\nfunctionalities allow one to enjoy a wide range \nof mesh-based analyses, ranging from 3D volumetric \nimage pre-processing (hole-filling, thinning and \nthickening), surface mesh modeling (extraction, \nremeshing, repairing, and smoothing) to volumetric \nmesh creation.\n\nConverting 3D image stacks into quality surface and\ntetrahedral meshes is one of the core features of iso2mesh.\nWe provide serveral automated functions to perform\nthe image-\u003emesh and mesh-\u003eimage conversion, including\n\n- `vol2mesh` (`v2m`): convert a 3D volumetric image into a tetrahedral mesh\n- `vol2surf` (`v2s`): extract triangular surfaces from a 3D image volume\n- `surf2mesh` (`s2m`): create a tetrahedral mesh from a triangular surface mesh\n- `surf2vol` (`s2v`): rasterize a close-surface to a volumetric image\n- `mesh2vol` (`m2v`): rasterize a tetrahedral mesh to a volumetric image\n\nMost of these function are associated with several meshing\noptions and parameters to give users full control to mesh \ndensity, adaptivity, region labeling and mesh quality.\nThe output data for some of these functions can be used\nas the input for the others, giving endless combinations to\nanalyze your data. In addition to image-based mesh generation,\niso2mesh can also mesh geometry primitives such as spheres,\ncubes and cylinders. This makes iso2mesh a CAD-capable software,\nfully integrated in the MATLAB/Octave environments.\n\nAnother core feature of iso2mesh is surface mesh\nprocessing. A surface mesh is the bridge between a voxelated\nimage and a tetrahedral mesh, and is the foundation for \nsuccessful 3D mesh generation. In iso2mesh, we provide the\nfollowing key functions for surface mesh processing:\n\n- `smoothsurf` (`sms`): smoothing a surface mesh\n- `surfboolean`: boolean operations (join, intersect, diff) of two surfaces\n- `meshresample`: downsample a surface mesh to a coarse surface\n- `meshrefine`: refine a surface mesh\n- `remeshsurf`: remesh a surface mesh, including up-sampling and down-sampling\n- `meshcheckrepair`: test a surface mesh and remove defects and self-intersecting elements\n\nA third area iso2mesh excels is the rich set of mesh analysis \nand inquiry functions. For both surface and tetrahedral meshes, \niso2mesh can report the element volume (or area), mesh quality\nmetrics, node connectivity and neighbors, interior edges and \nboundaries, surface norms, element centroids, etc.\n\nLast, but not the least, iso2mesh can import and export mesh\ndata from/to a dozen of file formats, including those used by the \npopular FEA software like COMSOL and ABAQUS. The STL format can\nexport an iso2mesh-generated mesh for 3D printing.\nUsers can not only export the data to a file, but also make\n3D plots in MATLAB/Octave using the powerful \"plotmesh\" function.\n\nThese examples are only a small fraction in the over 200 optimized \nfunctions provided by iso2mesh. The modular design of iso2mesh \nmakes the code easy to understand and easy to be intergrated in \nyour data analysis workflow. Please check out the full iso2mesh \nfunction list and detailed help information in the following URL:\n\nhttp://iso2mesh.sf.net/cgi-bin/index.cgi?Doc/FunctionList\n\n#### Compiling Iso2Mesh\n\nThe default release of Iso2Mesh packages already contains pre-compiled\nbinaries for a wide range of platforms (32/64bit Windows, 32/64bit Linux\nand Mac with 64bit Intel and 32 bit PowerPC CPUs). So, without needing \nto recompile, Iso2Mesh can be executed out-of-box on MATLAB or GNU Octave.\n\nHowever, in the event that your operating system is not supported, or\ndue to license restrictions, such as creating a release for various\nLinux distributions, you can recreate the mesh utility binaries under\n`iso2mesh/bin` folder using the source codes provided under `iso2mesh/tools`\nby following the below commands:\n\n ```\ngit clone --recurse-submodules https://github.com/fangq/iso2mesh.git\ncd iso2mesh\nrm -rf bin/*.mex* bin/*.exe\ncd tools\nmake clean\nmake\n```\n\nThis will download and recompile the below binaries in the bin folder:\n\n- cgalmesh\n- cgalsurf\n- cgalsimp2\n- jmeshlib\n- meshfix\n- tetgen1.5\n- cork\n\nOnce these binary files are recreated, you can run all the major functionalities\nof Iso2Mesh. The gtrefine utility is depreciated and replaced by \ncork and tetgen.\n\nTo compile the above external tools, the below tools must be pre-installed\n(tested on Ubuntu 14.04 LTS, if you use another Linux distribution, the package\nnames might be different)\n\n- gcc\n- cmake\n- libcgal-dev\n- libsuitesparse-dev\n- zlib1g-dev\n\nyou can install these on Ubuntu by running:\n ```\n sudo apt-get install gcc cmake libcgal-dev libsuitesparse-dev zlib1g-dev\n ```\n on Ubuntu or Debian. If you use Fedora, you need to install the below packages\n```\n sudo dnf install cmake CGAL-devel SuperLU-devel blas-static gcc-c++ zlib-devel octave-devel\n```\n\n#### Acknowledgement\n\nThis toolbox interacts with a number external meshing tools \nto perform the essential functionalities. These tools are listed \nbelow:\n\n\u003e bin/tetgen and bin/tetgen1.5:\n\n- Summary: tetgen is a compact and fast 3D mesh generator\n- License: GNU Affero General Public License version 3\n- URL: http://tetgen.org/\n- Author: Hang Si \u003csi at wias-berlin.de\u003e\n- Research Group: Numerical Mathematics and Scientific Computing\n::Weierstrass Institute for Applied Analysis and Stochastics\n::Mohrenstr. 39, 10117 Berlin, Germany\n\n\u003e bin/cgalsurf:\n\n- Summary: cgalsurf is a utility to extract a surface mesh from a gray-scale or a binary 3D image\n- Source: it is a slightly modified version from Surface_mesher example from CGAL 3.4\n- 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)\n- URL: http://www.cgal.org/Manual/3.3/doc_html/cgal_manual/Surface_mesher/Chapter_main.html\n\n\u003e bin/cgalmesh and bin/cgalpoly:\n\n- Summary: cgalmesh and cgalpoly are utilities to produce surface and volumetric meshes from a multi-valued volumetric image\n- Source: it is a slightly modified version from Mesh_3 example from CGAL 5.3\n- 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)\n- URL: https://doc.cgal.org/latest/Mesh_3/\n\n\u003e bin/cgalsimp2:\n\n- Summary: cgalsimp2 performs surface mesh simplification in iso2mesh.\n- Source: it is adapted from Surface_mesh_simplification example of CGAL library\n- 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)\n- URL: https://doc.cgal.org/latest/Surface_mesh_simplification/index.html\n\n\u003e bin/jmeshlib:\n\n- Summary: meshfix is adapted from the sample code of JMeshLib\n- License: GPL (GNU General Public License) v2 or later\n- URL: http://jmeshlib.sourceforge.net/\n- Author:Marco Attene \u003cattene at ge.imati.cnr.it\u003e\n::Istituto di Matematica Applicata e Tecnologie Informatiche\n::Consiglio Nazionale delle Ricerche\n::Via De Marini, 6 (Torre di Francia)\n::16149 Genoa - ITALY \n\n\u003e bin/meshfix:\n\n- Summary: meshfix is a mesh-repairing utility\n- License: GPL (GNU General Public License) v2 or later\n- URL: http://code.google.com/p/meshfix/\n- Author: Marco Attene, Mirko Windhoff and Axel Thielscher.\n::Istituto di Matematica Applicata e Tecnologie Informatiche\n::Consiglio Nazionale delle Ricerche\n::Via De Marini, 6 (Torre di Francia)\n::16149 Genoa - ITALY \n\n\u003e bin/cork:\n\n- Summary: A robust surface mesh Boolean operation algorithm\n- License: LGPL (GNU Lesser General Public License)\n- URL: https://github.com/gilbo/cork\n- Author: Gilbert Bernstein\n\n\u003e bin/gtsrefine:\n\n- Summary: GTS is the GNU Triangulated Surface Library\n- License: LGPL (GNU Lesser General Public License)\n- URL: http://gts.sourceforge.net/\n- Author: GTS developers\n\n\u003e bin/PoissonRecon:\n\n- Summary: Screened Poisson Surface Reconstruction (Version 8.0)\n- License: MIT\n- URL: http://www.cs.jhu.edu/~misha/Code/PoissonRecon/Version8.0/\n- Author: Michael Kazhdan (http://www.cs.jhu.edu/~misha/)\n\n\n**Note:** Iso2Mesh and the above meshing utilities are considered \nas an \"aggregate\" rather than \"derived work\", based on the \ndefinitions in GPL FAQ (http://www.gnu.org/licenses/gpl-faq.html#MereAggregation)\nTherefore, the license of Iso2Mesh and these utilities are independent.\nThe Iso2Mesh license only applies to the scripts and documentation/data\nin this package and exclude those programs stored in the bin/ directory.\nThe source codes of the modified meshing utilities are available\nseparately at Iso2Mesh's website and retain their upstream licenses.\n\nYour acknowledgement of Iso2Mesh in your publications or \npresentations would be greatly appreciated by the author of \nthis toolbox. The citation information can be found in the\nIntroduction section.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffangq%2Fiso2mesh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffangq%2Fiso2mesh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffangq%2Fiso2mesh/lists"}