App ultraMeshes2Mesh

About the Application

ultraMeshes2Mesh reconstructs a single, continuous and watertight surface mesh from a group of non-watertight input meshes, as shown in Figure 1. The resulting mesh can be optimized to produce high quality topology with resonable tessellation.

Figure 1 Reconstruction of a continuous manifold (right in blue) of a spiny neuronal mesh from a list of input meshes representing the different components of the neuron (left: the dendrite is in red and the dendritic spines are in green on the left). The closeup focuses on a small branch of a spiny pyramidal neuron. The image in the middle is a transparency-rendering of the left image revealing how the individual spine meshes are intersecting with the mesh of the dendritic branch.

Workflow

ultraMeshes2Mesh uses a similar workflow like ultraMesh2Mesh, but rather than rasterizing a single input mesh into a volume grid, it rasterizes a group of input meshes into a volume grid with a bounding box calculated from the aggregate bounding boxes of all the input meshes.

Command Line Arguments

ultraMeshes2Mesh has similar command line arguments to the ultraMesh2Mesh application. The only difference is the input arguments, where ultraMesh2Mesh takes a single input mesh, while ultraMeshes2Mesh takes a list of meshes grouped in a single directory.

Input Arguments

• --input-directory   The absolute path to the directory where a group of input meshes are located to be loaded in Ultraliser to create an alternative output watertight mesh. Supported mesh formats are: .OBJ, .PLY, .STL, .OFF and .H5. The format of the H5 files is specified by the MICrONS Explorer (microns-explorer.org). If you wish to integrate your specific format, please contact the corresponding authors.

Output Arguments

• --output-directory   The absolute path of the parent directory where the results (or artifacts) will be generated. Resulting volumes will be created by default in the volumes 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 file will be considered to label all the output artifacts. For example, if the input mesh name is neuron.obj, the resulting volume should be labeled neuron.nrrd. If a prefix is given, for example --prefix cortical_neuron, the resulting volume will be labeled cortical_neuron.nrrd.

Voxelization-related Arguments

• --resolution   The base resolution of the volume created to voxelize the input mesh. This resolution is set to the larget dimension of the bounding box of the input mesh, while the resolutions of the other dimensions are computed accordingly. The default value is 512.

• --scaled-resolution   If this flag is set, the resolution of the volume (that will be created to voxelize the input mesh) will be computed based on the dimensions of the input mesh and the --voxels-per-micron scale factor. For example, if the largest dimension of the input mesh is 100 microns, and the --voxels--per-microns value is 5, the resolution of the volume will be 500. The value of the --resolution argument is ignored if this flag is set.

• --voxels-per-micron   Number of voxels per micron needed to construct the volume grid that will be used to voxelize the input mesh. Note that it is assumed that the dimensions of the input mesh are in microns. If this is not the case, the user must pre-scale the input mesh model. The value of this parameter is only considered if the --scaled--resolution flag is set, otherwise the value defined by the --resolution argument is used. The default value is 3.

• --solid   Use solid voxelization to fill the interior of the volume shell created from the rasterization (or surface voxelization) of the input mesh. For this specific application, this option is advised TO BE ALWAYS SET. If the input mesh contains loops, it is advised to use xyzsolid voxelization. Refer to the voxelization-axis option.

• 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.

• --bounds-file   A file that defines the bounding box or region of interest (ROI) that will be voxelized. This option is used to select a specifc ROI from the space to voxelize. This is a single-line ASCII file that contains pMin and pMax of the ROI in the following format X_MIN Y_MIN Z_MIN X_MAX Y_MAX Z_MAX. If the defined ROI does not have any triangles, there will be no output volumes created.

• --edge-gap   Some little extra space (in percentage of the total bounding box the input mesh) to avoid edges intersection. The default value is 0.05.

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. The resulting stack will be in .TIFF format.

• --export-stack-xz   Generate an image stack (volume slices) along the Y-axis of the volume. The resulting stack will be in .TIFF format.

• --export-stack-zy   Generate an image stack (volume slices) along the X-axis of the volume. The resulting stack will be in .TIFF format.

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

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.

Mesh Fusion Arguments

• --use-simple-mesh-join   If this flag is set, the resulting mesh will constructed from a mesh joint operation that simply merges all the given meshes into a single mesh object with multiple partition. Note that is this flag is set, all the remeshing reconstruction parameters are ignored and the resulting mesh is not guaranteed to be watertight.

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 ultraMeshes2Mesh.