App ultraNeuroMorpho2Mesh

About the Application

Objective

ultraNeuroMorpho2Mesh reconstructs high fidelity and geometrically realistic two manifold watertight surface mesh models of neurons from input morphology skeletons that are either stored in .SWC or .H5 file formats. Somata profiles are reconstructed on a physically plausible basis using a finite-element method (FEM) [1]. The resulting mesh can be optimized to produce high quality topology with resonable tessellation as shown in Figure 1.

Figure 1

Creating biologically realistic spiny neuronal surface mesh from its input morphology skeleton. (a) Progressive reconstruction of the soma from an initial icosphere into a 3D plausible profile based on the FEM approach [1]. (b) The morphology is rendered as a set of samples. (c) For each neurite, we reconstruct a list of proxy-geometries linking a set of principal sections from the root node and until the leaf: level 1 is in red, level 2 is in green, and level 3 is in blue. Note that the proxy geometries start from the origin of the soma to avoid any gaps when the soma mesh is added afterwards (d). (e) Spine proxy geometries are added along the surface of the proxy-mesh. All the section geometries, spines and somatic mesh are rasterized to create a continuous and watertight manifold. Renderings of multiple closeups of this mesh are shown in Figure 3. Scale bars, 5 microns (a) and 20 microns (b, c, d, e).

Significance

Reaction diffusion simulations ....

Input

ultraNeuroMorpho2Mesh takes input neuronal morphologies (the morphology structure is shown in the figure below) in the following formats:

• SWC format (open source)
• H5 format (internal)

Figure 2

Digitized morphology skeletons of neurons are represented by acyclic graphs. The root node represents the cell body (or soma) - in yellow - of the neuron. The morphology is traced and digitized into a list of samples (a). Each sample has a unique index, 3D Cartesian coordinate and radius. A pair of connected samples represents a segment (b). A concatenated list of adjacent segments between two branching points represents a section (c). Neurites or arbors are composed of a hierarchical organization of sections. Note that branching samples might have different radii and dendritic spines are not shown in this illustration.

SWC Neuronal Morphologies

SWC morphologies are typically downloaded from NeuroMorpho.Org. The documentation of the SWC specification is available online.

H5 Neuronal Morphologies

H5 neuronal morphologies are created within the scope of the Human Brain Project (HBP). Documentation is currently available from the Blue Brain Project. For further details, please consult the documentation of NeuroM.

Output

ultraNeuroMorpho2Mesh primarily creates a two-manifold watertight mesh model of corresponding input astrocytic skeleton, as shown in Figure 1. Other artefacts including volumes, projections, statistical analysis results of the input morphology and output meshes and volumes. Further details on all the output artefacts are available in this page.

Data Samples

We provide a pair of astrocyte morphologies in the data directory.

Command Line Arguments

Input Arguments

• --morphology   The absolute path of the input morphology. This application accepts only .SWC and .H5 astrocyte morphologies. For Neurolucida-based formats .ASC, please consult MorphIO to convert the .ASC morphologies to either .SWC or .H5 files.

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 file will be considered to label all the output artifacts. For example, if the input morphology name is neuron1.h5, the resulting mesh should be labeled neuron1.obj. If a prefix is given, for example --prefix cortical_neuron, the resulting mesh will be labeled cortical_neuron.obj.

Voxelization-related Arguments

• --resolution   The base resolution of the volume that will be created to voxelize the input neuron morphology. This resolution is set to the larget dimension of the bounding box of the input morphology, 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 morphology) will be computed based on the dimensions of the morphology (in microns) and the --voxels-per-micron scale factor. For example, if the largest dimension of the input morphology 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 morphology. 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 morphology into the created volume grid. For this specific application, this option is advised TO BE ALWAYS SET.

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

• --edge-gap   Some little extra space (in percentage of the total bounding box the input astrocyte) 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.

• --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. For this specific application, this option is advised NOT TO BE SET.

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

• --serial   Execute the pipeline in a single thread validation. This option has no value if OpenMP is not available in your system or if you do not have multi-core workstation.

Branching Order Arguments

• --axon-branch-order The maximum branch order of the axon. All branches with higher branching orders will be omitted and ignored in the reconstructed mesh. The default value is infinity.

• --basal-branch-order The maximum branch order of the basal dendrites. All branches with higher branching orders will be omitted and ignored in the reconstructed mesh. The default value is infinity.

• --apical-branch-order The maximum branch order of the apical dendrites. All branches with higher branching orders will be omitted and ignored in the reconstructed mesh. The default value is infinity.

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

References

[1] Garcia-Cantero, Juan J., Juan P. Brito, Susana Mata, Sofia Bayona, and Luis Pastor. "Neurotessmesh: a tool for the generation and visualization of neuron meshes and adaptive on-the-fly refinement." Frontiers in neuroinformatics 11 (2017): 38.