Examples ultraMesh2Mesh
In this page, we will present several examples of ultraMesh2Mesh using different input and output arguments.
This is a basic (or minimal) example showing how to create a watertight mesh (in .OBJ format) of a neuron from a non-watertight input mesh. The input mesh was created with NeuroMorphoVis from a neuronal morphology provided by the Blue Brain Project.
ultraMesh2Mesh --mesh ultraMesh2Mesh/input/neuron-1.obj --output-directory ultraMesh2Mesh/example-1 --export-obj-mesh
The input mesh is available in the input directory, examples/ultraMesh2Mesh/input/neuron-1.obj and the output artifacts are generated to examples/ultraMesh2Mesh/example-1.
This command will create three meshes in the examples/ultraMesh2Mesh/example-1/meshes directory.
All the generated meshes are labeled with the same input prefix of the input mesh input-1 with a suffix added to differentiate between them.
The first mesh neuron-1-dmc.obj is created by applying the isosurface reconstruction algorithm dual marching cubes (dmc) on the intermediate volume created from rasterizing the input mesh.
The second mesh neuron-1-laplacian.obj is created by applying the Laplacian filter on the first mesh. By default, a Laplacian kernel is applied with 10 iterations, but users can change the number of iterations from the argument --laplacian-iterations NUMBER.
The third mesh neuron-1-watertight.obj is similar to the Laplacian mesh, but is guaranteed to be watertight after applying the watertight verification checkes on it. Nevertheless, this mesh does not, yet, have neither nice topology nor moderate tessellation becuase we did not use any of the optimization functions to optimize its surface.
- It is quite obvious that the output files of the first and second meshes are not needed (to be written on disk) if the user is only seeking a watertight mesh. These meshes are quite important for the logic of the application for comparative purposes. Nevertheless, the user can avoid writing these meshes from memory to disk using the following command
--ignore-marching-cubes-meshand--ignore-laplacian-mesh. This is also advisable when writing huge meshes with several million triangles. Therefore, we sould recommend the users to use alternatively the following command line
ultraMesh2Mesh --mesh ultraMesh2Mesh/input/neuron-1.obj --output-directory ultraMesh2Mesh/example-1 --export-obj-mesh --ignore-marching-cubes-mesh --ignore-laplacian-mesh
-
This command line must have at least one argument to export the mesh to one of the supported formats. This is why the argument
--export-obj-meshis mandatory.
If--export-obj-meshis not added, the following error message will be shownYou must specify at least one valid mesh format to export:[--export-obj-mesh, --export-ply-mesh, --export-off-mesh, --export-stl-mesh]. For further details, please refer to this page. -
It is possible to export the output mesh(es) in other (or multiple) file formats, for example, if .STL meshes are needed for simulation and .OBJ meshes for visualization, users can add both arguments to the command line as follows
ultraMesh2Mesh --mesh ultraMesh2Mesh/input/neuron-1.obj --output-directory ultraMesh2Mesh/example-1 --export-obj-mesh --export-stl-mesh --ignore-marching-cubes-mesh --ignore-laplacian-mesh
- The resulting mesh has a single partition or island representing a single continuous manifold. Therefore, if the input mesh contains multiple mesh partitions, the largest partition (in terms of number of triangles and surface area) will only be preserved and the others will be ommited. If the user want to keep all the partitions in the mesh, the
--preserve-partitionsflag must be added to the command line.
This example extends the previous one to create projection images of the intermediate volumes created from voxelizing of the input mesh. Further details are available in this page.
ultraMesh2Mesh --mesh ultraMesh2Mesh/input/neuron-1.obj --output-directory ultraMesh2Mesh/example-2 --export-obj-mesh --ignore-marching-cubes-mesh --ignore-laplacian-mesh --project-xy --project-zy --project-xz
In addition to the mesh(es) generated in the meshes subdirectory, the projections required are generated to the projections subdirectory. The resulting projections are gray-scale .PPM images. If the users want to visually inspect the internal structure of the volume using a specific colormap, a series of color-coded projections using a huge set of colormaps can be generated using the following flag --project-color-coded. The naming convention of the resulting files are based on the input mesh prefix, projection plane and the name of the colormap. Further details are available in this page. For example, the following command creates a list of color-coded images for the XZ projection of the intermediate volume
ultraMesh2Mesh --mesh ultraMesh2Mesh/input/neuron-1.obj --output-directory ultraMesh2Mesh/example-2 --export-obj-mesh --ignore-marching-cubes-mesh --ignore-laplacian-mesh --project-xz --project-color-coded
This command will create the following color-coded projection images, in addition to the gray-scale projection that is created by default when the --project-xz flag is added to the command line arguments.
neuron-1-projection-xz-ACCENT.ppm
neuron-1-projection-xz-AFMHOT.ppm
neuron-1-projection-xz-AUTUMN.ppm
neuron-1-projection-xz-BINARY.ppm
neuron-1-projection-xz-BLUES.ppm
neuron-1-projection-xz-BONE.ppm
neuron-1-projection-xz-BRBG.ppm
neuron-1-projection-xz-BRG.ppm
neuron-1-projection-xz-BUGN.ppm
neuron-1-projection-xz-BUPU.ppm
neuron-1-projection-xz-BWR.ppm
neuron-1-projection-xz-CIVIDIS.ppm
neuron-1-projection-xz-CMRMAP.ppm
neuron-1-projection-xz-COOL.ppm
neuron-1-projection-xz-COOLWARM.ppm
neuron-1-projection-xz-COPPER.ppm
neuron-1-projection-xz-CUBEHELIX.ppm
neuron-1-projection-xz-DARK2.ppm
neuron-1-projection-xz-FLAG.ppm
neuron-1-projection-xz-GIST_EARTH.ppm
neuron-1-projection-xz-GIST_GRAY.ppm
neuron-1-projection-xz-GIST_HEAT.ppm
neuron-1-projection-xz-GIST_NCAR.ppm
neuron-1-projection-xz-GIST_RAINBOW.ppm
neuron-1-projection-xz-GIST_STERN.ppm
neuron-1-projection-xz-GIST_YARG.ppm
neuron-1-projection-xz-GNBU.ppm
neuron-1-projection-xz-GNUPLOT2.ppm
neuron-1-projection-xz-GNUPLOT.ppm
neuron-1-projection-xz-GRAY.ppm
neuron-1-projection-xz-GREENS.ppm
neuron-1-projection-xz-GREYS.ppm
neuron-1-projection-xz-HOT.ppm
neuron-1-projection-xz-HSV.ppm
neuron-1-projection-xz-INFERNO.ppm
neuron-1-projection-xz-JET.ppm
neuron-1-projection-xz-MAGMA.ppm
neuron-1-projection-xz-NIPY_SPECTRAL.ppm
neuron-1-projection-xz-OCEAN.ppm
neuron-1-projection-xz-ORANGES.ppm
neuron-1-projection-xz-ORRD.ppm
neuron-1-projection-xz-PAIRED.ppm
neuron-1-projection-xz-PASTEL1.ppm
neuron-1-projection-xz-PASTEL2.ppm
neuron-1-projection-xz-PINK.ppm
neuron-1-projection-xz-PIYG.ppm
neuron-1-projection-xz-PLASMA.ppm
neuron-1-projection-xz-PRGN.ppm
neuron-1-projection-xz-PRISM.ppm
neuron-1-projection-xz-PUBUGN.ppm
neuron-1-projection-xz-PUBU.ppm
neuron-1-projection-xz-PUOR.ppm
neuron-1-projection-xz-PURD.ppm
neuron-1-projection-xz-PURPLES.ppm
neuron-1-projection-xz-RAINBOW.ppm
neuron-1-projection-xz-RDBU.ppm
neuron-1-projection-xz-RDGY.ppm
neuron-1-projection-xz-RDPU.ppm
neuron-1-projection-xz-RDYLBU.ppm
neuron-1-projection-xz-RDYLGN.ppm
neuron-1-projection-xz-REDS.ppm
neuron-1-projection-xz-SEISMIC.ppm
neuron-1-projection-xz-SET1.ppm
neuron-1-projection-xz-SET2.ppm
neuron-1-projection-xz-SET3.ppm
neuron-1-projection-xz-SPECTRAL.ppm
neuron-1-projection-xz-SPRING.ppm
neuron-1-projection-xz-SUMMER.ppm
neuron-1-projection-xz-TAB10.ppm
neuron-1-projection-xz-TAB20B.ppm
neuron-1-projection-xz-TAB20C.ppm
neuron-1-projection-xz-TAB20.ppm
neuron-1-projection-xz-TERRAIN.ppm
neuron-1-projection-xz-TWILIGHT.ppm
neuron-1-projection-xz-TWILIGHT_SHIFTED.ppm
neuron-1-projection-xz-VIRIDIS.ppm
neuron-1-projection-xz-WINTER.ppm
neuron-1-projection-xz-WISTIA.ppm
neuron-1-projection-xz-YLGNBU.ppm
neuron-1-projection-xz-YLGN.ppm
neuron-1-projection-xz-YLORBR.ppm
neuron-1-projection-xz-YLORRD.ppm
-
By default, surface voxelization is used to rasterize the input mesh into a volume grid. This makes the interior of the volume empty and can result in certain cases in some artifacts. Therefore, it is always recommended to use solid voxelization to fill the interior of the volumetric shell shell created from the rasterization step. Solid voxelization is enabled by adding the
--solidflag to the command line. Users can still select the axis used to perform the solid voxelization process. Further details are available in this page. -
The resolution of the resulting projection image depends on the base resolution defined by the user to reconstruct the volume. By default, the resolution is set to 512, but the user can set a different resolution as follows
--resolution NUMBER [for example 1024, 2048 or 5000]. Users can also use scaled resolution that depends on the dimensions of the input mesh. Further details are available in this page.
This example creates an optimized and watertight surface mesh that has clean topology and less tessellation.
ultraMesh2Mesh --mesh ultraMesh2Mesh/input/neuron-2.obj --output-directory ultraMesh2Mesh/example-3 --export-obj-mesh --ignore-marching-cubes-mesh --ignore-laplacian-mesh --optimize-mesh --resolution 1024
By default, the optimizer has 5 optimization iterations. But this value can be set using the --optimization-iterations NUMBER.
The mesh optimization module produces this output to the console showing the number of facets removed in every iteration.
----------------------------------------------------------------------------------
-----------------------------| Mesh Optimization |-----------------------------
----------------------------------------------------------------------------------
Coarsing Mesh [1]
Creating Neighbour List
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
* Time | 1.73473 Seconds
Ordering Vertices
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
* Time | 0.847661 Seconds
Computing Edges
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
* Time | 1.80473 Seconds
Removing Vertices
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
* Time | 3.59241 Seconds
* Removed Vertices: [ 83.2256 k ], Removed Triangles: [ 166.451 k ]
Coarsing Mesh [2]
Computing Edges
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
* Time | 1.47445 Seconds
Removing Vertices
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
* Time | 2.24901 Seconds
* Removed Vertices: [ 41.5742 k ], Removed Triangles: [ 83.1484 k ]
Coarsing Mesh [3]
Computing Edges
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
* Time | 1.09499 Seconds
Removing Vertices
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
* Time | 1.65577 Seconds
* Removed Vertices: [ 30.2656 k ], Removed Triangles: [ 60.5312 k ]
Coarsing Mesh [4]
Computing Edges
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
* Time | 0.977837 Seconds
Removing Vertices
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
* Time | 1.42579 Seconds
* Removed Vertices: [ 24.5176 k ], Removed Triangles: [ 49.0352 k ]
Coarsing Mesh [5]
Computing Edges
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
* Time | 0.871269 Seconds
Removing Vertices
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
* Time | 1.11668 Seconds
* Removed Vertices: [ 18.0791 k ], Removed Triangles: [ 36.1582 k ]
Dense Coarsing (Decimation) Stats.
* Time | 19.0023 Seconds
Smoothing Mesh Normals
Smoothing Normals
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
WARNING: Min. Angle: [1.516590], Max. Angle : [176.191574], Smaller than 15: [1282], Larger than 150: [204]
* Time | 0.768836 Seconds
Smoothing Mesh Surface
Smoothing Faces
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
WARNING: Min. angle: 14.748827, Max. angle: 143.561783, Smaler than 15: 1, Larger than 150: 0
* Time | 6.19258 Seconds
Smoothing Mesh Normals
Smoothing Normals
* Progress │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│ (100.00 %)
WARNING: Min. Angle: [14.810155], Max. Angle : [145.307770], Smaller than 15: [1], Larger than 150: [0]
* Time | 0.786386 Seconds
Total Optimization
* Time | 26.7501 Seconds
The previous command will create two mesh files (since we have disabled writing the dmc and laplacian meshes). The first mesh is neuron-2-optimized.obj which was created from optimizing the topology of the mesh created from the Laplacian operator. This mesh is optimized, and two-manifold, but it might have self-intersecting faces due to the optimization procedure. The second mesh neuron-2-watertight.obj is comparable to the optimized mesh (in terms of structure and size), but it is guaranteed to have no self-intersecting faces. This mesh results from the application of the watertight verification step on the optimized mesh to resolve all the self-intersecting facets.
-
The user can supress writing the optimized mesh
neuron-2-optimized.objto disk by adding the--ignore-optimized-meshflag to the command line arguments. In this case, the watertight meshneuron-2-watertight.objwill be the only mesh that will be saved to disk. -
Depending on the base resolution (set using the
--resolution NUMBERargument) used to voxelize the input (non-watertight) mesh, it is advisable to use appropriate value of the--laplacian-iterationsargument to smooth the surface of the mesh generated from the isosurface reconstruction function without loosing details of fine structures. This could be established based on trial-and-error. A few iterations of the Laplacian kernel (3-7) will not smooth the surface of the mesh sufficiently to have nice appearance (stair-step artifacts). On the other hand, high number of iterations will affect thin and fine structures of the mesh and could potentially cause detaching them from the final mesh after the optimization and watertight verification stages. This can be demonstrated by running the following command onneuron-1.objwith a base resolution of 512 and three different values for the Laplacian iterations 5, 10 and 20. Note that the output meshes are named using the prefixlap_itr_NUMBER. A comparison (meshes are found side-by-side inexample3/comparisons/neuron-1-laplacian-iterations.blend) between the three meshes is demonstrated in the figure below (from left to right: using 5, 10 and 20 Laplacian iterations to smooth the surface of the mesh, and a the meshes are compared in the fileexample3/comparisons/neuron-1-laplacian-iterations_resolution-2000.blend).
ultraMesh2Mesh --mesh ultraMesh2Mesh/input/neuron-1.obj --output-directory ultraMesh2Mesh/example-3 --export-obj-mesh --ignore-marching-cubes-mesh --ignore-laplacian-mesh --ignore-optimized-mesh --solid --optimize-mesh --resolution 512 --laplacian-iterations 5 --prefix lap_itr_5
- To resolve the previous issue, it is advisable to increase the base resolution, for example 2000 or more. This allows to maximize the number of Laplacian iterations without loosing details as demonstrated by the image below. The command line used to create these meshes is as follows (the prefix
lap_itr_NUMBER_2000is used to label the output meshes)
ultraMesh2Mesh --mesh ultraMesh2Mesh/input/neuron-1.obj --output-directory ultraMesh2Mesh/example-3 --export-obj-mesh --ignore-marching-cubes-mesh --ignore-laplacian-mesh --ignore-optimized-mesh --solid --optimize-mesh --resolution 2000 --laplacian-iterations 5 --prefix lap_itr_5_2000
- Increasing the resolution will definitely increase the tessellation of the resulting mesh (number of facets). Nevertheless, users can further reduce its tessellation by increasing the number of optimization iterations
--optimization-iterations NUMBER. Other parameters such as--flat-factorand--dense-factorcan be set, but this requires some further knowledge on how the optimization kernels work and might also require trial-and-error. We used 20 Laplacian iterations and created three meshes with 5, 10 and 20 optimization iterations. The results are compared in the image below. The resulting meshes have the following sizes: 11.3, 7.1 and 3.0 Mbytes respectively. Note that the last mesh has lost some branches. The following command is used to create these meshes (the prefixopt_itr_NUMBERis used to label the different output meshes)
ultraMesh2Mesh --mesh ultraMesh2Mesh/input/neuron-1.obj --output-directory ultraMesh2Mesh/example-3 --export-obj-mesh --ignore-marching-cubes-mesh --ignore-laplacian-mesh --ignore-optimized-mesh --solid --optimize-mesh --resolution 2000 --laplacian-iterations 20 --optimization-iterations 20 --prefix opt_itr_20
- Ultraliser has support to create surface meshes with adaptive optimization. This can be accomplished if the
--optimize-adaptivelyflag is added to the command line arguments. Further details are available in this page.
This example exports an .NRRD volume representing the intermediate grid that was used to voxelize the input mesh.
ultraMesh2Mesh --mesh ultraMesh2Mesh/input/neuron-1.obj --output-directory ultraMesh2Mesh/example-4 --export-obj-mesh --ignore-marching-cubes-mesh --ignore-laplacian-mesh --ignore-optimized-mesh --solid --resolution 512 --export-nrrd-volume
In addition to the resulting .OBJ watertight mesh, the previous command will create an .NRRD volume in the volumes subdirectory. This volume (neuron-1.nrrd) can be loaded in Paraview for visual analytics and multi-modality analysis as shown in the image below. Ultraliser can generate volumes in other file formats including a low memory footprint file where every voxel is stored in a single bit. Further details are avilable in this page.
- The output volume is an 8-bit NRRD file. The voxels of the resulting volumes are either empty (with 0) or filled (with 255).
This example analyses the input mesh and the resulting meshes (and intermediat volume) and writes to disk text files containing the analytics of these models in the distributions and statistics subdirectories. Further details are available in this page.
In addition to the meshes, a list of text files are created containing information about the input and output models in the statistics subdirectory. The distributions subdirectory contains a list of *.dist files where every file is labeled with the name of the distribution it accounts for in addition to a prefix to differentiate between the different models. From these distributions, we can plot the analysis histograms with which we can measure the topological quality of the output meshes and compare them to the input one. This can be demonstrated as shown in the figure below.
Other statistics relevant to the input and output data are also exported as shown below
Mesh Stats. [ input ]
* Bounding Box: | [268.274841, 172.225815, 344.103149]
* pMin: | [-71.882156, -108.753296, -166.683548]
* pMax: | [196.392670, 63.472523, 177.419586]
* Number Vertices | 6.46875 k
* Number Triangles | 11.666 k
* Surface Area | 7077.514160²
* Volume | 2472.325195³
Volume Stats. [ volume ]
* Bounding Box: | [295.102295, 189.448395, 378.513428]
* pMin: | [-85.295898, -117.364586, -183.888702]
* pMax: | [209.806412, 72.083817, 194.624741]
* Resolution | [399] x [256] x [512]
* Number of Voxels | 52297728
* Volume Format | Bit
* Size in Memory | 6.23438 MBytes
* Volume | 7805.014160³
Mesh Stats. [ watertight ]
* Bounding Box: | [268.718987, 172.496445, 344.345993]
* pMin: | [-71.886284, -109.004044, -166.777527]
* pMax: | [196.832703, 63.492401, 177.568466]
* Number Vertices | 39.6035 k
* Number Triangles | 79.2188 k
* Surface Area | 13073.404837²
* Volume | 5338.243339³ ultraMesh2Mesh --mesh ultraMesh2Mesh/input/neuron-1.obj --output-directory ultraMesh2Mesh/example-5 --export-obj-mesh --ignore-marching-cubes-mesh --ignore-laplacian-mesh --solid --stats --dists
- The back-to-back plots and the complete analysis figure shown above is created automatically using the analysis scripts integrated into NeuroMorphoVis.
MICrONS Explorer meshes ...