🧠 Neurovolume is a VDB-based fMRI visualization and analysis pipeline. This project is currently a work in progress.

Installation and Usage

💾 Software Requirements

• Neurovolume is primarily written in Go, visit go.dev to download and install Go.
• Currently, the only front end is a Blender Plugin. For development we used Version 4.3.2 (4.3.2 2024-12-17), which you can download here. It should work on most other versions as well.

🛠️ Compiling Go Code

• After cloning the github repo, navigate to cmd folder with cd neurovolume/cmd/neurovolume
• You can compile the code to an executable here with go build main.go

🌩️ Creating a VDB from a NIfTI file

• This executable can now be run from the command line with: ./main /path/to/nifti/file.nii /path/to/output/folder
  • (read on to see how you can run it through a Blender plugin)
• ⚠️ Warning: This project has only been tested for NIfTI-1 files. NIfTI-2 files are not yet supported.
• ⚠️ Warning: GZ unzipping is currently untested. Please unzip all .nii.gz files to .nii before opening them with Neurovolume. You can do so by double clicking on the file (at least in macOS).

🔌 Setting Up the Blender Add-On

• After compiling the Go code, open the Blender plugin located at neurovolume/blender_plugin/__init__.py
• Edit the following lines to match the paths on your machine:

# Where you will save the VDB and metadata:
user_set_output_path = "/Users/username/repos/neurovolume/output"
# Path to your Go executable:
user_set_exe_path = "/Users/username/repos/neurovolume/cmd/neurovolume/main"
# Optional, the default path that appears when you first open the panel:
user_set_default_nifti = "/Users/username/repos/neurovolume/media/sub-01_T1w.nii" 

• Install the Blender plugin using one of the following methods::
  • With Jacques Lucke's vsCode extension for Blender (recommended)
  • Via the Add-ons section
  • Copy-pasting the add-on into Blender's Text-editor and then clicking the triangular "play" button to run.

Running The Blender Plugin

• From the Neurovolume panel, enter the path to your NIfTI file and click Load VDB from NIfTI
• 🕰️ Please Note, this might take a few seconds to a few minutes. The program is not responsive at this point yet. If you would like to check progress I recommend running Blender from the terminal to see the print statements roll by.
• Enjoy!

Why VDB?

VDBs are a highly performant, art-directable, volumetric data structure that supports animations. Unlike typical meshed-based pipelines using the marching cubes algorithm, our volume-based approach will preserve the scan’s normalized density data throughout the visualization pipeline. The animation support is particularly useful for animating BOLD response.

For more information on VDBs, see the openVDB website

To-Do

Blender

• Blender Plugin can directly import and process NIFTI files
  • Blender Plugin can implement method of subtraction for fMRI sequences
• VDB Grid Alignment and Combination in Blender
• GUI Loading animations

fMRI

• Add fMRI Sequence import functionality in Blender Plugin
• Method of Subtraction from Neutral Stimulus
  • Exists in the bold_diffing notebook. Currently this gives the user the most control, although we should integrate this into the Blender plugin when we implement the native NIFTI file parsing.
• Frame Interpolation Options for Realtime Playback (re implement in the Go-Backend)
  • Cross dissolve
  • Morph

Dev

• Increase performance in native VDB writer (try to match PyOpenVDB)
• Add support for gz files
• Add support for NIfTI-2 files

Dataset Citation

This software was tested using the following datasets.

Isaac David and Victor Olalde-Mathieu and Ana Y. Martínez and Lluviana Rodríguez-Vidal and Fernando A. Barrios (2021). Emotion Category and Face Perception Task Optimized for Multivariate Pattern Analysis. OpenNeuro. [Dataset] doi: 10.18112/openneuro.ds003548.v1.0.1

OpenNeuro Link

The MNI Template can be found Here