App ultraAstroMorpho2Mesh

About the Application

Objective

ultraAstroMorpho2Mesh reconstructs two-manifold watertight surface mesh models of astroglial cells from input morphology skeletons that are either stored in .SWC or .H5 file formats. The resulting mesh can be optimized to produce high quality topology with resonable tessellation as shown in Figure 1.

Figure 1

Left: Input astroglial morphology skeleton synthesized by Zisis et al. [1]. Right: Optimized, two-manifold and watertight mesh model created with ultraAstroMorpho2Mesh. Endfeet surface patches are not shown in the morphology illustration on the left, however, the endfeet are included in the reconstructed mesh model on the right. Scale bar: 10 microns.

Significance

Compared to neurons, available reconstructions of astroglial cells are sparse. Even complete astrocytic reconstructions (that have endfeet data) are extremely limited. In fact, NeuroMorpho.Org has ~6,000 astrocytes, but none of them contains any endfeet descriptions; only the arborizations of perisynaptic and perivascular processes. These astrocyte morphologies are basically similar to neuron in their structure; they are also stored in the standard .SWC format that describe arborizations and branching data.

Input

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

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

Figure 2

Astrocytic morphologies are similar to the neuronal ones, but additionally, they have multiple endfeet (shown in green). Endfeet are represented by triangular patches (list of connected triangles), where each vertex along the surface has a thickness. Further details on the exact structure of astrocytic morphologies are available in [1, 2]. Note that astrocytic processes have sponge-like spatial structure in contrast to neurons, but they are both represented by acyclic graphs.

SWC Astrocyte Morphologies

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

H5 Astrocyte Morphologies

H5 astrocyte morphologies are created using an integrated script. Documentation is currently available only to Blue Brain Project collaborators. For further details, please contact the corresponding author.

Output

ultraAstroMorpho2Mesh 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. The current version of the application accepts only .SWC and .H5 astrocyte morphologies. If you wish to integrate your specific format, please contact the corresponding author.

Output Arguments

• --output-directory   The absolute path of the parent directory where the results (or artefacts) 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 artefacts. For example, if the input morphology name is astrocyte1.h5, the resulting mesh will be labeled astrocyte1.obj. If a prefix is given, for example --prefix cortical_astrocyte, the resulting mesh will be labeled cortical_astrocyte.obj.

Voxelization-related Arguments

• --resolution   The base resolution of the volume that will be created to voxelize the input astrocyte morphology. This resolution is set to the largest 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 astrocyte 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 NOT TO BE 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

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

References

1. Zisis, Eleftherios, et al. "Digital reconstruction of the neuro-glia-vascular architecture." Cerebral Cortex 31.12 (2021): 5686-5703.

2. Cali, C., K. Kare, M. Agus, H. Lehvaslaiho, D. J. Boges, M. Hadwiger, and P. J. Magistretti. "Structural analysis of 3D cellular models of cortical glia, neurons and vasculature from serial block-face electron microscopy of p14 rat cortex." In GLIA, vol. 67, pp. E373-E374. 111 RIVER ST, HOBOKEN 07030-5774, NJ USA: WILEY, 2019.

3. Abdellah, Marwan, Alessandro Foni, Eleftherios Zisis, Nadir Román Guerrero, Samuel Lapere, Jay S. Coggan, Daniel Keller, Henry Markram, and Felix Schürmann. "Metaball skinning of synthetic astroglial morphologies into realistic mesh models for in silico simulations and visual analytics." Bioinformatics 37, no. Supplement_1 (2021): i426-i433.