BrainAtlas

The BrainAtlas repository is a package which wraps the BrainGlobe Atlas API into a package for easy use in Unity.

Data pipeline

BrainAtlas implements a Python pipeline which converts the bg-atlas API files into a convenient format for ingesting into Unity. The pipeline downloads and organizes the raw data into the /Pipelines/data/ folder for each available atlas.

Note that the data pipeline can take a long time to run, as it downloads each atlas locally.

bg-atlas files

annotation.tiff: annotation IDs
metadata.json: name, citation + link, species, symmetric, resolution, orientation, version, shape, 4x4 transform matrix
README.txt:
reference.tiff: reference image RGB
structures.json: acronym, id, full name, hierarchy path, rgb color

Intermediate data files

Reference image: .bytes file with the flattened data from the reference image, in uint16 format (2 bytes per voxel)
Annotation image: .bytes file with the flattened data from the annotation image, in uint32 format (4 bytes per voxel)
structures.json
Mesh files: .obj file for each region
One-sided mesh files: .obj file for each region
Region centers: .csv file with the ap/ml/dv coordinate for the center of each area

Unity files

Pipeline steps

Mesh splitting

A Blender script convert_to_one_sided.blend exists to load each individual mesh file and split it in half to expose just the left hemisphere.

Processed files

In the Unity project, an editor script Convert2Unity implements a conversion pipeline to import the raw data into Unity and convert them to prefabs. There are two separate pipelines that get run, first converting the reference and annotation images and then converting the brain region metadata and mesh files.

The final output of this process are the prefab files that can be loaded via the BrainAtlasRemoteLoader component.

Reference image: Texture3D RGB24
Annotation image: Texture3D R16?, note that R=0 is reserved for regions with no annotation
BrainAtlas prefab: Prefab that represents the CoordinateSpace and Transform

BrainAtlasRemoteLoader

After installing the Unity package into a new project, you’ll need to import the BrainAtlas prefab to be able to use the available features. Note that all of the loading functions are asynchronous

Load an Atlas

Call the BrainAtlas.LoadAtlas function to load a single atlas. This loads the prefab for the atlas Space and any available Transforms into the scene and loads the ontology.

Load an Annotation or Reference texture

Call the BrainAtlas.LoadTexture functions to obtain the Texture3D objects for this atlas.

Load a Region

Call the BrainAtlas.LoadRegion to bring a single region into the scene. Note that there are three copies of every region, Full (both hemispheres), Left, and Right.

Development

Adding new atlases

The pipeline should run for all existing bg-atlas atlases.

Under-the-hood for Pipelines

Pipeline steps:

?
?

Building new bundles

The remote loader uses a simple versioning setup by tagging each build with a tag (e.g. v0.1.1). Increment the patch number if you are modifying an existing file. Increment the minor number if you are adding new files that don’t modify existing functionality. Increment the major number if you are making a backward-incompatible change to the codebase.

To ensure backward-compatibility you should modify the remote URL to include the build target version as a suffix on the url. This avoids accidentally over-writing files and causing hash code mis-matches.

Pushing to the server

Build the addressable assets and copy the entire new ServerData/ folder to the ServerData/X.Y.Z/ folder on the local server. Make sure to build for Windows standalone, WebGL, MacOS, and Linux.

Update projects

Existing projects should then be migrated to target the new storage version, by modifying the field in the AddressablesRemoteLoader component.