Description of GUI of the 3D model building tool

To facilitate reconstruction process a simple graphical user interface was prepared. Below, the 3dBAR reconstruction GUI with an exemplary CAF dataset loaded (Johnson et. al., 2010) is presented.

Figure 1: The structure selection tab. The Striatum selected for reconstruction (gray highlight); Amygdala and Hippocampus loaded as context models (red font). The reconstruction of Hypothalamus is cached and available for loading (bold font).

Selecting structures

The left panel contains ontology tree loaded from CAF index file. One can browse through structures, select them for reconstruction or load already reconstructed, cached models. The right panel contains two tabs. Structure selection tab displays detailed information about the currently selected structure for reconstruction. This includes abbreviated and full name of the structure, span of slides on which it is defined as well as color assigned to this structure. Here one can also set the resolution, the depth of decomposition of the structure into substructures according to ontology tree, and mirroring of brain hemisphere may be enabled if needed.

Figure 2: The model customization tab. Reconstructions of Striatum, Amygdala and Hippocampus are presented.

Viewing and customizing the reconstructions

Reconstructed models can be viewed in the Model customization tab (Fig. 2) which also provides access to parameters of VTK pipeline. The preview is displayed in the form of triangular mesh although the actual model is still stored in volumetric form. The model can be rotated by pressing and holding left mouse button, zoomed in or out by pressing and holding the right button. Pressing the middle button allows one to pan the model over the scene. One can switch between wireframe and surface representations of the model by pressing w or s keys.

After changing VTK pipeline parameters, mesh may be recalculated by pressing Refresh button and cached by pressing Save model. Models are cached in form of polygonal meshes (vtkPolyData). Clear scene button removes all models from preview window. When a model is cached, the corresponding element of the ontology tree is displayed with bold font. Cached models can be loaded in the preview window as context models alongside the model being presently reconstructed, however they cannot be modified. When a cached model is loaded into context, the corresponding element in ontology tree is displayed in red.

Generating multiple reconstructions

Multiple reconstructions can be performed one by one as described above. However, this is convenient only when few models are required. To reconstruct multiple structures one can choose a parent structure containing desired substructures and reconstruct them down to a desired level of detail. All substructures are generated using the same set of reconstruction parameters provided in Structure selection tab and the same VTK pipeline. Models are generated one by one and automatically cached. When all the substructures are reconstructed they are loaded into preview window as context models.

Exporting the models

By default models are cached in the directory where CAF dataset is located. One may choose another export directory by selecting Set cache directory from Edit menu. When cache directory is changed, all currently loaded structures are removed from preview and ontology tree updates information about availability of cached models from the new directory.

3d Brain Atlas Reconstructor GUI offers three ways of exporting three dimensional models. Single reconstructions may be cached as polygonal data (vtkPolyData) or exported as volumetric datasets in the native VTK vtkImageData or NIfTI (Neuroimaging Informatics Technology Initiative) formats. Complex scenes containing numerous context models may be exported into VRML (Virtual Reality Modelling Language) or X3D format.

3D Brain Atlas Reconstructor CLI reconstruction tool

Apart from GUI, 3D Brain Atlas Reconstructor comes with command line interface (or shorter: CLI) allowing the user to perform batch reconstructions without configured graphics environment. After invoking the batch interface, following information will appear:

$./batchinterface.sh

Usage: ./batchinterface.sh [options] <CAF index> [<structure 1> [<structure 2> ...]]
3d Brain Atlas Reconstructor ver.0.1 Batch reconstruction interface

Options:
-h, --help            show this help message and exit
-g GENERATESUBSTRUCTURES, --generateSubstructures=GENERATESUBSTRUCTURES
                      maximum level of substructures (in the structure tree)
                      to be generated; default: 0
-d VOXELDIMENSIONS, --voxelDimensions=VOXELDIMENSIONS
                      voxel size (in units defined in given dataset) in slide plane
                      and in plane perpendicular to the slides, consecutively.
-e EXPORTDIR, --exportDir=EXPORTDIR
                      the path to a directory for reconstructions
-p PIPELINE, --usePipeline=PIPELINE
                      the path to a custom pipeline definition
-v CAMERA, --useViewport=CAMERA
                      the direction vector from the center of the scene to
                      the camera position
--exportToWindow, --show
                      the reconstruction is displayed to the user
--composite           perform a reconstruction of the structure as a scene
                      composed of the reconstructions of the basic
                      substructures in the hierarchy tree (up to the maximum
                      given level)
--includeBrainOutline
                      Includes additional translucent brain outline to the
                      reconstructions. Applies only when exporting to VRML,
                      X3D, screenshot or thumbnail.

Output Format Options:
  --exportToX3d       exports as X3D scene
  --exportToVRML      exports as VRML scene
  --exportToPOVRay    exports to POV-Ray
  --exportToVTKPolydata
                      exports as VTKpolyMesh
  --exportToVolume    exports as VTKstructGrid
  --exportToNiftii    exports as Niftii file
  --exportToNumpy     exports as Numpy array
  --exportScreenshot  saves screenshot as an PNG image
  --exportThumbnail   saves scaled screenshot as an PNG image

The <CAF index> is a location of the index file of the given CAF dataset while the [<structure 1> [<structure 2> ...]] is space-separated list of all structures to reconstruction contained in the CAF dataset.

The simplest usage of the CLI is to generate reconstruction of a single structure from provided CAF dataset using default settings. Assume that our CAF dataset is located in the ~/atlases/mouse/caf/ directory and we would like to reconstruct the Thalamus as save a nifti volume with the reconstruction:

$./batchinterface.sh ~/atlases/mouse/caf/index.xml Thalamus --exportToNiftii

By default, the reconstructions generated using a predefined pipeline and stored in directory parallel to the CAF dataset directory (in this example it would be ~/atlases/mouse/reconstructions/). However, this behavior can be customized using various switches.