User documentation

Data import

Data type File format Option in Settings Additional remarks
Volume rendering NIfTI (.nii) file Add Volume To calibrate measurements, place a homonymous file in the same directory as the data file: see FAQ.
Depending on your machine, you may need to uniformly downscale the image stack and upscale the voxel size (see FAQ).
(Isosurface) Mesh Wavefront (.obj) file Add Mesh To calibrate measurements, consider using the BrainacleJ plug-in for ImageJ to create the necessary .mobj file interactively. The two files should also have the same name and be placed in the same directory.
Delineations Native (.json) file Import Delineations The file is created by Brainacle when delineations are exported or saved. The file includes any regions, points, and lines.
Coordinates data CSV (.csv) file Import Coordinates The file is created 1) with Brainacle by exporting delineations to CSV (.csv), or 2) with ImageJ's ROI Manager by saving selections using the Export Coordinates macro.
Image Image (.jpg, .jpeg, .png, .tiff, .tif, .bmp, .gif, .tga) file Add Image Add any reference images to the virtual environment. Images are interactable.

Visualization

Visualization mode Data type Where to find? Additional remarks
Orthoplane visualization Volume rendering Dropdown in volume menu; default option Othrogonal planes (3) with which volumetric data is sliced. The accompanying volume menu has options for more precise control:
  • scale data size from 0.5m to 12m,
  • advance a plane by increments of 5 slices.
A plane can be slided with any of the controllers.
Co-shape visualization Volume rendering Dropdown in volume menu A complement shape (cube) with which volumeric data can be revealed quickly. Movement is unconstrained to an axis as for the orthogonal planes. Interactions include:
  • a grab and move with a controller,
  • two-hand scaling.
Mesh visualization (Isosurface) Mesh Default option The mesh is visualized with a specific shader and made interactable from inside and outside. Interactions include:
  • a grab and move with a controller,
  • two-hand scaling at the boundaries.

Interaction

In the following, button naming references known controllers, such as the various types of SteamVR's controlllers and Quest's Touch controllers. If you use different controllers, interactions should be able to map just as well.

The main controller is colored in black (currently, right hand), the secondary (2nd) controller — in gray.
Interaction Purpose How to use? Additional remarks
Ray-based interaction Place a point;
Select a UI element		 Point the ray and press the trigger, main controller Points can be placed while the cursor is visible on a visualization.
Selectable (2D) UI elements: buttons and sliders in each menu, scrolling, and labels.
Constrained interaction Move an object On or in the object, press and hold the grip button on any of the controllers Depending on the object, common constraints include:
  • gravity constraint (default),
  • movement along a given axis,
  • movement at regular intervals (image slices).
Translation of volume renderings is done through a separate ''handle'', which itself has a (smaller) ''handle''.
Continuous movement Move viewing position in the environment Joystick button Movement in the horizontal plane (XZ): joystick on the main controller.
Movement in the vertical plane and rotation (Y): joystick on the 2nd controller.
Button press Open/close Settings Menu button, main controller The settings menu follows your gaze.
Button press Open/close context menu Menu button, 2nd controller The context menu is itself grabbable.
Button press Pause application System button, main controller Useful to load data without removing the headset. After pausing, in SteamVR, Quest Link, etc. switch to Desktop viewing.
Rotation of voxels Rotate volumetric data By grabbing rotation axes on the ''handle'' Each rotation axis has a different colour.
For repeatability, rotating is constrained to multiples of 5° (see label on the ''handle'').
Selection of user data Select a point While holding the trigger (2nd controller), draw a shape to visually mark objects inside of it. The mechanism is an extension of the well-known window selection to 3D. To clear or change selection, draw again.
Selection via touch Select a region Touch a region's envelope to select it. Region selection is used to confirm on which region the command, previously activated from the context menu, should be run.
Selection of labels Select visualization data Via ray-based interaction with the label (yellow) Label selection is used to confirm for which model (visualization data) should the export/import command be run.
Two-hand scaling Scale an object In an object, press and hold both grip buttons while stretching/squashing. Linear mapping to the distance between the two controllers. Scaling is uniform.
Swipe in the air Undo an operation While holding the grip button (2nd controller), swipe/flick outwards to the left. Suitable for quickly undoing small, recent changes.

Delineation

To change delineation tool, use the context menu where you can find the Delineaton tool option.
The delineation editor also includes the possibility to:
  1. Create a new active region.
  2. Select a region to change as the current active region.
  3. Delete selected points and lines.
  4. Show/Hide a region.
  5. Delete a region.
  6. Assign selected points to an existing or a new region.
  7. Show/Hide region's envelope continuously during delineation.
Delineation tool Modes Additional remarks
Point tool Additional modes include:
  • Show/Hide segments,
  • Use gaze direction.
 Place points in rapid succession. The placement of Points per frame can be configured in the Settings menu.
Line tool Additional modes include:
  • Use gaze direction.
 Draw more precise contours, where natural cubic interpolation is applied to line segments.
The color of the virtual environment (default black) can be changed with the Change Background option in Settings. The following operations cannot be undone: delete a region and show/hide region's envelope continuously.

Measurements

Measurements require calibration beforehand (otherwise measurements are performed in px, pixels). Measurements are performed in or on a region (the current active region) by executing one of the respective commands from below.
Measurement type Measurement method Additional remarks
Count Number of points

To count a number of landmarks:

  1. Set Points per frame in the Settings menu to 0
  2. Set the current tool to the point tool in the Context menu
  3. Create a new region*
  4. Place points to indicate landmarks of interest
*The first region is always created for the user. If there is no prior user data, this region will be empty.
Distance Straight-line distance

To measure the straight-line distance between two points:

  1. Set the current tool to the line tool in the Context menu
  2. Create a new region*
  3. Place points A and B to measure the distance AB
  4. Repeat 2. - 3. for any other distances
Distance Contour distance

After calibration, the line tool displays a label with the length of each added segment. If uncalibrated, the length is given in pixels.

The sum of all segments results in the perimeter of the delineated region at the intersection with the respective slice.
Distance Major axis
Intermediate axis
Minor axis

This is the length of each axis of the bounding ellipsoid for the region (see below). Obtained with Compute Measures from the Context menu.
Volume Volume of the region's envelope

The envelope is guaranteed to be always convex (with no dents). The envelope is also known as the convex hull. The volume of the envelope is computed based on its surfaces. Obtained with one of two options in the Context menu.
Volume Volume of the region's bounding ellipsoid

This is the minimum-volume ellipsoid that includes all points placed during delineation of the region. The orientation of the bounding ellipsoid is therefore determined by the principal axis of the spatial distribution of those points.

Obtained with Compute Measures from the Context menu.
Volume Slice-by-slice volume

To measure the volume of a delineated region, a correct order of the points during delineation is important. This involves:

  • placing points subsequently,
  • using the point tool only for simple structures, i.e. no nested structures,
  • using the line tool for more complex structures, such that all connections are visible,
  • using both tools or specifically closing segments to indicate the start and end of a substructure, and
  • generally, assigning any substructure a separate region (see show/hide region).

If correct, the volume of any nested stuctures is subtracted from the volume of larger structures.

Computation can be adjusted to trade off precision for performance in the Context menu. A value of 0 disables computation as part of Compute Measures.

Data export and saving

Data type File format Option in Settings Additional remarks
Delineations Native (.json) file;
Coordinates file: .csv, .xyz, .obj.		 Export Delineations Depending on the file ending, the type of export is also different.

A native (.json) file contains a full written reference to any delineations that can be shared with other Brainacle users, or imported again.

A (.csv, .xyz, .obj) file contains coordinates in image space. The CSV file can be imported in other software, e.g., ImageJ, Fiji (How to set up supporting ImageJ macros?), stripped of any regions and measurements. The export can be set to include all coordinates, i.e., the coordinates of points and lines, via the Export Coordinates setting.
(Isosurface) Mesh Wavefront (.obj) file Export Mesh Export previously imported (isosurface) mesh data. Export size can be reduced — by setting Complete Mesh Exports in Settings to no (default) — to trim normals and texture UVs. Normals and texture UVs are not required for the default mesh shader in Brainacle.
Delineations with any measurements Native (.json) file Save and Delete Saved data includes any user created and added data. The data will be automatically loaded anytime Brainacle starts until deletion. Deletion also removes any saved data for the selected data.