The BrainAtlas repository is a package which wraps the BrainGlobe Atlas API into a package for easy use in Unity.
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.
annotation.tiff: annotation IDs
metadata.json: name, citation + link, species, symmetric, resolution, orientation, version, shape, 4x4 transform matrix
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)
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
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.
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
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
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
BrainAtlas.LoadTexture functions to obtain the Texture3D objects for this atlas.
Load a Region
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.
Adding new atlases
The pipeline should run for all existing bg-atlas atlases.
Under-the-hood for Pipelines
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.
Existing projects should then be migrated to target the new storage version, by modifying the field in the