App ultraVolume2Mesh

About the Application

ultraVolume2Mesh reconstructs a two-manifold watertight mesh model from an input volume based on a user-defined iso-value that defines a continuous surface in the given volume (see Figure 1). The core of this application uses any of the iso-surface extraction algorithms that are implemented in Ultraliser: either the marching cubes (MC) or the advanced dual marching cubes (DMC). Further details on the isosurface extraction algorithms are provided in this page.

Figure 1 Reconstruction of an optimized watertight mesh (right in wireframe blue) of a head dataset from its corresponding 8-bit volume. This mesh has been generated after applying Laplacian filteration and mesh optimization to the the mesh in the middle (in orange). Note that the resulting mesh is reconstructed by using an iso-range (50 - 100) to build this surface.

Principal Input Data

ultraVolume2Mesh takes input volumes in several file formats including:

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 supported file formats are provided in this page.

Command Line Arguments

Input Arguments

• --volume   The absolute path to the input volume. Supported file types are .HDR, .NRRD and .UVOL.

• --iso-option   The --iso-option can be one of the following options: [(value), values, min, max, range, nonzero].

  • If --iso-option=value is selected, the value is defined by the option --iso-value=[VALUE].
  • If --iso-option=values is selected, the values are loaded from a given ASCII file as a space-separated list of values. The ASCII file is given using the option --iso-values-file=[ISO_VALUES_FILE]. Note that the values don't have to be a continuous range.
  • If --iso-option=min is selected, all the range above or equal to a given value will be used to segment the volume. The minimum value is defined by the option --min-value=[VALUE].
  • If --iso-option=max is selected, all the range below or equal to a given value will be used to segment the volume. The maximum value is defined by the option --max-value=[VALUE].
  • If the --iso-option=range is selected, then all the values between two values will be used to segment the volume. The minimum and maximum values will be defined by the options --min-value=[VALUE] and --max-value=[VALUE].
  • If the --iso-option=nonzero is selected, then all the non-zero voxels will be used to calculate the iso-volume.

• --iso-value   The iso-value where the volume will get segmented. The default is 1.

• --min-value   The minimum value used to segment the volume. The default is 1.

• --max-value   The maximum value used to segment the volume. The default value is 255.

• --isovalues-file   A file containing a list of values that will be used to define the surface of the volume to be extracted.

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 volume name is neuron.nrrd, the resulting mesh should be labeled neuron-*.obj. If a prefix is given, for example --prefix cortical_neuron, the resulting volume will be labeled cortical_neuron-*.obj.

• --write-histogram   Write the histogram of the volume into a text file.

Volume Filling Arguments

Note that the input data is a volume grid. Nevertheless, we can apply the solid voxelization kernel on this volume in case we need to fill the interior of its structure to reconstruct a better mesh.

• --solid   Use solid voxelization to fill the interior of the input volume grid, if exists.

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