prepare for iso2mesh 1.9 release - Century Egg

Author: fangq

AUTHORS.txt

@@ -1,4 +1,4 @@
-The author of "Iso2mesh" toolbox is Qianqian Fang. 
+The author of "Iso2Mesh" toolbox is Qianqian Fang. 
 Qianqian is currently an Assistant Professor at the
 Department of Bioengineering of Northeastern University.
 

ChangeLog.txt

@@ -1,10 +1,39 @@
 ============================================================================
 
-     Iso2mesh - a compact, powerful yet simple-to-use 3D mesh generator
+     Iso2Mesh - a compact, powerful yet simple-to-use 3D mesh generator
 
 ----------------------------------------------------------------------------
 
-Iso2mesh ChangeLog (key features marked by *):
+Iso2Mesh ChangeLog (key features marked by *):
+
+2018/07/19  (1.9.0, codename: Century Egg - final)
+
+  2018-07-19*[67ae478] update jsonlab to v1.8
+  2018-07-19 [0af072c] compiling jmeshlib and tetgen1.5 from source
+  2018-07-19 [c75ce08] use meshfix 1.2 from an old copy
+  2018-07-18 [f49286b] use system binaries first, then use locally built suffix-less binaries, then prebuilt ones
+  2018-07-18 [8d015f4] add makefile to compile all external tools and copy exe to bin
+  2018-07-18*[17bf732] add source codes for embedded tool for deployment
+  2018-06-27 [2baaf0d] fix bugs in meshinterp and meshremap when elemid contains nan
+  2018-06-26 [3413cf6] add meshremap and meshinterp to map values between a pair of meshes
+  2018-05-30 [f111940] add examples for readnirfast and savenirfast
+  2018-05-30*[6ec9dbc] support importing and exporting NIRFAST mesh files
+  2018-05-25 [312d1ff] nodevolume can be calculated using elemvolume
+  2018-05-02 [39bc663] fix missing command in the meshconn output
+  2018-04-11 [65a0f2a] Update tetgen1.5 executable for Windows to TetGen v1.5.1-beta1
+  2017-11-08*[98d9fb4] add extrudesurf function to expand an open surface into a solid
+  2017-10-02 [9f5e9f1] support cone trunk in meshacylinder
+  2017-09-13 [914d9e9] Fix bug in surf2mesh
+  2017-08-30*[a6070a9] add top and bottom faces for extrudecurve
+  2017-08-06 [6cd2747] merge phong's surfboolean, make s2m/surf2mesh support tetgen1.5
+  2017-07-19 [f6d8d7f] remove isoloated nodes for cell represented surfaces
+  2017-06-29 [4ff9ed9] support removing duplicated nodes in cell face input
+  2017-06-20 [dab6afe] close open surfaces by the bounding box
+  2017-06-20 [059f98a] support initial angle in orthdisk
+  2017-06-12 [5d22c41] apply a patch from Riccardo to correct surface orientation
+  2017-05-29 [48f30d5] update meshfix binary for windows, add 64bit meshfix from https://github.com/MarcoAttene/MeshFix-V2.1/
+  2017-05-11 [d11dbc4] add new function to create extruded surfaces from orthogonal 2D spline curves
+  2017-03-05 [41da47d] create 10-node tet from 4-node tet
 
 2017/01/16  (1.8.0, codename: Deviled Egg - final)
         1.**robust surface boolean operator based on Cork

Content.txt

@@ -706,6 +706,27 @@
            row represents a triangle denoted by the indices of the 3 nodes
 
 
+==== function [node,face,elem]=meshcylinders(c0, v, len, varargin) ====
+
+ [node,face]=meshcylinders(c0, v, len, r,tsize,maxvol,ndiv)
+    or
+ [node,face,elem]=meshacylinder(c0, v, len, r, tsize,maxvol,ndiv)
+ [nplc,fplc]=meshacylinder(c0, v, len,r,0,0,ndiv);
+
+ create the surface and (optionally) tetrahedral mesh of a 3D cylinder
+
+
+ input: 
+   c0, cylinder list axis's starting point
+   v: directional vector of the cylinder
+   len: a scalar or a vector denoting the length of each 
+        cylinder segment along the direction of v
+   tsize, maxvol, ndiv: please see the help for meshacylinder for details
+
+ output:
+   node, face, elem: please see the help for meshacylinder for details
+
+
 === # Mesh decomposition and query ===
 
 ==== function facecell=finddisconnsurf(f) ====
@@ -1799,6 +1820,21 @@
     newval=meshremap(value_src,id,ww,e2,size(n2,1)); % map to target
 
 
+==== function [node,face]=extrudesurf(no,fc,vec) ====
+
+ [node,face]=extrudesurf(no,fc,vec)
+ 
+ create a enclosed surface mesh by extruding an open surface
+
+
+ input:
+
+ output:
+      node: 3D node coordinates for the generated surface mesh
+      face: triangular face patches of the generated surface mesh, each
+           row represents a triangle denoted by the indices of the 3 nodes
+
+
 === # File I/O ===
 
 ==== function saveasc(v,f,fname) ====
@@ -1950,6 +1986,21 @@
              (optional)
 
 
+==== function savemsh(node,elem,fname,rname) ====
+
+ savemsh(node,elem,fname,rname)
+
+ save a tetrahedral mesh to GMSH mesh format
+
+ author: Riccardo Scorretti (riccardo.scorretti<at> univ-lyon1.fr)
+
+ input:
+      node: input, node list, dimension (nn,3)
+      elem: input, tetrahedral mesh element list, dimension (ne,4) or (ne,5) for multi-region meshes
+      fname: output file name
+      rname: name of the regions, cell-array of strings (optional)
+
+
 ==== function savevrml(node,face,elem,fname) ====
 
  savevrml(node,face,elem,fname)

README.txt

@@ -1,12 +1,12 @@
 ----------------------------------------------------------------------
-= Iso2mesh: an image-based 3D surface and volumetric mesh generator  =
+= Iso2Mesh: An Image-based 3D Surface and Volumetric Mesh Generator  =
 ----------------------------------------------------------------------
 
 *Author: Qianqian Fang <q.fang at neu.edu>
       Department of Bioengineering
       Northeastern University
       360 Huntington Ave, Boston, MA 02115
-*Version: 1.8.0 (Deviled Egg)
+*Version: 1.9.0 (Century Egg)
 *License: GPL v2 or later (see COPYING) 
       (this license does not cover the binaries under the bin/ 
        directory, see Section III for more details)
@@ -19,25 +19,27 @@
 
 == # Introduction ==
 
-"Iso2mesh" is a MATLAB/Octave-based mesh generation toolbox,
+"Iso2Mesh" is a MATLAB/Octave-based mesh generation toolbox,
 designed for easy creation of high quality surface and 
 tetrahedral meshes from 3D volumetric images. It contains 
 a rich set of mesh processing scripts/programs, working 
 either independently or interacting with external free 
-meshing utilities. Iso2mesh toolbox can directly convert
+meshing utilities. Iso2Mesh toolbox can directly convert
 a 3D image stack, including binary, segmented or gray-scale 
 images such as MRI or CT scans, into quality volumetric 
 meshes. This makes it particularly suitable for multi-modality 
 medical imaging data analysis and multi-physics modeling.
 Above all, iso2mesh is open-source. You can download it for 
 free. You are also allowed to extend the toolbox for your
-own research and share with other users. Iso2mesh is 
+own research and share with other users. Iso2Mesh is 
 cross-platform and is compatible with both MATLAB and GNU Octave 
 (a free MATLAB clone).
 
 The details of this toolbox can be found in the following
-paper:
+papers:
 
+*Anh Phong Tran and Qianqian Fang, "Fast and high-quality tetrahedral \
+ mesh generation from neuroanatomical scans," arXiv preprint arXiv:1708.08954, 2017
 *Qianqian Fang and David Boas, "Tetrahedral mesh generation from volumetric binary and \
  gray-scale images," Proceedings of IEEE International Symposium on Biomedical Imaging \
  (ISBI 2009), pp. 1142-1145, 2009
@@ -49,8 +51,8 @@ Creation of high-quality surface and tetrahedral meshes
 from volumetric images has been a challenging task. 
 There are very limited software and resources available 
 for this purpose. Commercial tools, such as Mimics 
-and Amira, are both expensive and limited in functionalities. 
-Iso2mesh was developed as a free alternative to these 
+and Simpleware, are both expensive and limited in flexibility. 
+Iso2Mesh was developed as a free alternative to these 
 expensive commercial tools and provides researchers a highly
 flexible, modular and streamlined image-based mesh 
 generation pipeline. Intuitive interfaces and rich
@@ -69,7 +71,8 @@ the 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 into a volumetric image
+* 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 meshing
 options and parameters to give users full control to mesh 
@@ -115,14 +118,60 @@ function 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-compiled
+binaries for a wide range of platforms (32/64bit Windows, 32/64bit Linux
+and Mac with 64bit Intel and 32 bit PowerPC CPUs). So, without needing 
+to recompile, Iso2Mesh can be executed out-of-box on MATLAB or GNU Octave.
+
+However, in the event that your operating system is not supported, or
+due to license restrictions, such as creating a release for various
+Linux distributions, you can recreate the mesh utility binaries under
+iso2mesh/bin folder by 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 functionalities
+of Iso2Mesh. The gtsset and gtrefine tools are depreciated and replaced by 
+cork 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 package
+names might be different)
+
+ libcgal-dev
+ clang
+ cmake
+
+you can install these by
+
+ sudo apt-get install libcgal-dev clang cmake
+ 
+on Ubuntu.
 
 == # Acknowledgement ==
 
 This toolbox interacts with a number external meshing tools 
 to perform the essential functionalities. These tools are listed 
 below:
 
-=== bin/tetgen ===
+=== bin/tetgen and bin/tetgen1.5 ===
 
 *Summary:tetgen is a compact and fast 3D mesh generator
 *License: GNU Affero General Public License version 3
@@ -182,31 +231,31 @@ other modules are under the Lesser General Public License (LGPL)
 ::Via De Marini, 6 (Torre di Francia)
 ::16149 Genoa - ITALY 
 
-=== bin/gtsset and 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/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/gtsset and 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
+
 
-Note: iso2mesh and the above meshing utilities are considered 
+Note: Iso2Mesh and the above meshing utilities are considered 
 as an "aggregate" rather than "derived work", based on the 
 definitions 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/data
+Therefore, the license of Iso2Mesh and these utilities are independent.
+The Iso2Mesh license only applies to the scripts and documentation/data
 in this package and exclude those programs stored in the bin/ directory.
 The source codes of the modified meshing utilities are available
-separately at iso2mesh's website and retain their upstream licenses.
+separately at Iso2Mesh's website and retain their upstream licenses.
 
-Your acknowledgement of iso2mesh in your publications or 
+Your acknowledgement of Iso2Mesh in your publications or 
 presentations would be greatly appreciated by the author of 
 this toolbox. The citation information can be found in the
 Introduction section.

bin/README.txt

@@ -1,4 +1,4 @@
-= External Utilities Used by Iso2mesh Toolbox =
+= External Utilities Used by Iso2Mesh Toolbox =
 
 In this directory, you can find the precompiled binaries
 that are used by iso2mesh (http://iso2mesh.sf.net). The 
@@ -11,7 +11,8 @@ names and origins of these tools are explained below:
 # cgalsimp2.* - Surface Mesh Simplification Utility (built on CGAL)
 # tetgen.*    - A Quality Tetrahedral Mesh Generator and 3D Delaunay Triangulator by Hang Si
 # tetview.*   - A Mesh Graphing Utility by Hang Si
-# meshfix.*   - Mesh Validation and Repairing Utility (build on JMeshLib) by Marco Attene
+# jmeshlib.*  - Mesh Validation and Repairing Utility (build on JMeshLib) by Marco Attene
+# meshfix.*   - Mesh Validation and Repairing Utility (build on Meshfix) by Marco Attene
 # cork.*      - A robust surface mesh Boolean operation algorithm by Gilbert Bernstein (https://github.com/gilbo/cork)
 
 

doc/iso2mesh_workflow.jpg

@@ -27,7 +27,7 @@ func_shortcut="v2m v2s s2m s2v m2v sms"
 func_mainfun="vol2mesh vol2surf surf2mesh surf2vol mesh2vol"
 func_backend="binsurface cgalv2m cgals2m vol2restrictedtri surf2volz mesh2mask"
 func_primitive="meshabox meshasphere meshanellip meshunitsphere meshacylinder 
-                meshgrid5 meshgrid6 latticegrid extrudecurve"
+                meshgrid5 meshgrid6 latticegrid extrudecurve meshcylinders"
 func_inquery="finddisconnsurf surfedge volface extractloops meshconn  
                 meshcentroid nodevolume elemvolume neighborelem 
 		faceneighbors edgeneighbors maxsurf flatsegment orderloopedge  
@@ -39,9 +39,9 @@ func_meshfix="meshcheckrepair meshreorient removedupelem
                 surfaceclean getintersecttri delendelem surfreorient"
 func_remesh="meshresample remeshsurf smoothsurf sortmesh mergemesh 
                 meshrefine mergesurf surfboolean fillsurf highordertet
-		meshinterp meshremap"
+		meshinterp meshremap extrudesurf"
 func_fileio="saveasc savedxf savestl savebinstl saveinr saveoff 
-                savesmf savesurfpoly savegts readgts
+                savesmf savesurfpoly savegts readgts savemsh
                 savevrml readasc readinr readmedit readoff readsmf
 	        readtetgen deletemeshfile mcpath mwpath savemedit
 		savejson loadjson saveubjson loadubjson savejmesh