App ultraMask2Mesh

About the Application

Objective

ultraMask2Mesh reconstructs high fidelity, multi-partitioned and two manifold watertight surface mesh models of input masks segmented from microscopy stacks as shown in the figure below.

Input

ultraMask2Mesh takes input masks represented by a stack (or a series of .tiff or .tif files). The naming convention of the files must be ordered.

Unlike ultraVolume2Mesh, ultraMask2Mesh does not depend on an input isovalue to segment the volume. The input stack is always assumed to contain a binary mask that was segmented a priori.

Output

ultraMask2Mesh primarily produces a high-fidelity, optimized, and two-manifold watertight mesh extracted from the input mask.

Command Line Arguments

Input Arguments

• --mask-directory   The absolute path to the directory where the mask stack is located.

• --mask-width   The width of the mask (in pixels).

• --mask-height   The height of the mask (in pixels).

Output Arguments

• --output-directory   The absolute path of the parent directory where the results (or artifacts) will be generated. Resulting meshes will be created by default in the meshes subdirectory. If any of the projection flags are enabled, for example --project-xy, the resulting projection will be generated to the projections directory. Further details on the structure of the output directory are available in this page.

• --prefix   A file prefix that will be used to label the generated files. If this prefix is not given by the user, the base name of the input directory will be considered to label all the output artifacts. For example, if the input directory name is neuron-mask, the resulting mesh should be labeled neuron-mask-*.obj. If a prefix is given, for example --prefix cortical_neuron, the resulting mesh will be labeled cortical_neuron-*.obj.

Volume-related Arguments

• --solid   Use solid voxelization to fill the interior of the volume shell created from the loaded mask in case it is not guaranteed to be filled.

• voxelization-axis   The axis where the solid voxelization operation will be performed. Use one of the following options [x, y, z, or xyz]. If you use x or y or z the voxelization will happen along a single axis, otherwise, using xyz will perform the solid voxelization along the three main axes of the volume to avoid filling any loops in the morphology. By default, the Z-axis solid voxelization is applied ONLY if the --solid flag is set.

Volume Projection Arguments

• --project-xy   Project the volume along the Z-axis and create a gray-scale PPM image.

• --project-xz   Project the volume along the Y-axis and create a gray-scale PPM image.

• --project-zy   Project the volume along the X-axis and create a gray-scale PPM image.

• --project-color-coded   Generate color-coded projections of the volume in different colormaps to help the investigation process. Further details on the colormaps are available in this page.

Volume Slicing Arguments (Stacks)

• --export-stack-xy   Generate an image stack (volume slices) along the Z-axis of the volume.

• --export-stack-xz   Generate an image stack (volume slices) along the Y-axis of the volume.

• --export-stack-zy   Generate an image stack (volume slices) along the X-axis of the volume.

Volume Export Arguments

• --export-bit-volume   Export an Ultraliser-specific bit volume, where each voxel is stored in 1 bit. The header and data are stored in a single file with the extention .UVOL. Further details are available in this page.

• --export-unsigned-volume   Export an Ultraliser-specific unsigned volume, where each voxel is either in 1, 2, 3 or 4 bytes depending on the type of the volume. The header and data are stored in a single file with the extention .UVOL. Further details are available in this page.

• --export-raw-volume   Export a raw volume, where each voxel is stored in 1 byte. The resulting files are: .IMG file (contains data) and .HDR file (meta-data)

• --export-nrrd-volume   Export a .NRRD volume that is compatible with VTK and can be loaded with Paraview for visualization purposes. The resulting output contains the header and data integrated into a single .NRRD file.

Volume-grid Mesh Export Arguments

• --export-volume-mesh   Export a mesh that represents the volume where each voxel will be a cube. The format of the exported mesh(es) is specified by the Mesh Export Arguments

• --export-volume-bounding-box-mesh  
  Export a mesh that represents the bounding box of the volume. This mesh is primarily used for debugging purposes. The format of the exported mesh(es) is specified by the Mesh Export Arguments

• --export-volume-grid-mesh   Export a mesh that represents the volumetric grid used to voxelize the mesh. This mesh is primarily used for debugging purposes. The format of the exported mesh(es) is specified by the Mesh Export Arguments

Surface Mesh Reconstruction Arguments

• --isosurface-technique   Specify a technique to extract the isosurface from the volume. The options are [mc, dmc] for marching cubes and dual marching cubes respectively. The default technique is dmc (Dual Marching Cubes).

• --preserve-partitions   Keeps all the partitions (islands) of the mesh if the resulting mesh contains more than one.

Surface Mesh Optimization Arguments

• --laplacian-iterations   Number of iterations to smooth the reconstructed mesh with Laplacian filter. The default value is 10.

• --optimize-mesh   Optimize the reconstructed mesh using the default optimization strategy.

• --adaptive-optimization   Optimize the reconstructed mesh using the adaptive optimization strategy.

• --optimization-iterations   Number of iterations to optimize the resulting mesh. The default value is 1. NOTE: If this value is set to 0, the optimization process will be ignored even if the --optimize-mesh flag is set.

• --smooth-iterations   Number of iterations to smooth the reconstructed mesh, The default value is 5.

• --flat-factor   A factor that is used for the coarseFlat function. The default value is 0.05.

• --dense-factor   A factor that is used for the coarseDense function. The default value is 5.0.

• --min-dihedral-angle   The required minimum dihedral angle. The default value is 0.1.

Mesh Scaling Arguments

• --x-scale   Scaling factor for the mesh along the X-axis, The default value is 1.0.

• --y-scale   Scaling factor for the mesh along the Y-axis. The default value is 1.0.

• --z-scale   Scaling factor for the mesh along the Z-axis. The default value is 1.0.

Mesh Export Arguments

• --export-obj-mesh   Export the resulting mesh(es) to Wavefront object format (.OBJ).

• --export-ply-mesh   Export the resulting mesh(es) to the Stanford triangle format (.PLY).

• --export-off-mesh   Export the resulting mesh(es) to the object file format (.OFF).

• --export-stl-mesh   Export the resulting mesh(es) to the stereolithography CAD format (.STL).

• --ignore-marching-cubes-mesh   If this flag is set, the mesh reconstructed with the marching cubes algorithm will be ignored and will NOT be written to disk. Setting this flag speeds up the process to create the final watertight mesh. Further details are available at this page.

• --ignore-laplacian-mesh   If this flag is set, the mesh resulting from the application of the Laplacian operator will be ignored and will NOT be written to disk. Setting this flag speeds up the process to create the final watertight mesh. Further details are available at this page.

• --ignore-optimized-mesh   If this flag is set, the optimized mesh will NOT be written to disk. Setting this flag speeds up the process to create the final watertight mesh. Further details are available at this page.

• --export-at-origin   Export the astrocyte mesh at the origin, where the center of the bounding box will be located at the origin O(0, 0, 0).

Statistical Analysis Arguments

• --stats   Write the statistics of the input and resulting meshes/volumes/morphologies. Further details are available in this page.

• --dists   Write the statistical distributions of the input and resulting meshes/volumes/morphologies. Further details are available in this page.

Execution Arguments

• --threads   Number of threads used to process the parallel chunks in the code. If this value is set to 0, all the cores available in the system will be used. The default value is 0.

Examples

In this page, we provide a list of examples to demonstrate how to use ultraMask2Mesh.