App ultraMesh2Volume

About the Application

Objective

ultraMesh2Volume creates volumetric models from non-watertight input meshes (see Figure 1). This application is similar to ultraMesh2Mesh - in fact, it is a subset of ultraMesh2Mesh. ultraMesh2Volume does not generate any output meshes from the input one; it is only concerned with generating volumes that can be potentially used for volume visualization and in silico imaging^1-3.

Figure 1 Paraview-based rendering of an 8-bit NRRD volume of a hippocampal neuron (right) from a non-watertight input mesh (left). This volume is reconstructed with 512 base resolution relying on conservative rasterization, and this is why the thin branches of the mesh are thick in the resulting volume.

Principal Input Data

ultraMesh2Volume takes input meshes with the following formats:

• Wavefront object .OBJ
• Polygonal file format .PLY in ASCII encoding only
• Stereolithography file format .STL
• Object file format .OFF

Principal Output Data

ultraMesh2Volume primarily produces volume files with the following formats:

1. Raw volumes stored in 8-, 16-, 32- and 64-bit binary files with .HDR/.IMG formats. The meta-data is stored in the .HDR file while the raw binary data is stored in the .IMG file. Raw volumes can be seamlessly read in Paraview.

2. Ultraliser-based volume files in .UVOL with 1-, 8-, 16-, 32- and 64-bit content. The meta-data and data are all stored in the .UVOL file.

3. NRRD volumes (with compressions). Support to this format depends on the compilation of the NRRD reader with Ultraliser.

Further details on the file formats of the output volumes are discussed in this page.

Command Line Arguments

Input Arguments

• --mesh   The absolute path of the input mesh. Supported mesh formats are: .OBJ, .PLY, .STL, .OFF.

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.

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

References

1. Abdellah, Marwan. In silico brain imaging: physically-plausible methods for visualizing neocortical microcircuitry. No. THESIS. EPFL, 2017.

2. Abdellah, Marwan, Ahmet Bilgili, Stefan Eilemann, Julian Shillcock, Henry Markram, and Felix Schürmann. "Bio-physically plausible visualization of highly scattering fluorescent neocortical models for in silico experimentation." BMC bioinformatics 18, no. 2 (2017): 1-14.

3. Abdellah, Marwan, Ahmet Bilgili, Stefan Eilemann, Henry Markram, and Felix Schürmann. "Physically-based in silico light sheet microscopy for visualizing fluorescent brain models." BMC bioinformatics 16, no. 11 (2015): 1-13.