Neurovolume is a Python library for manipulating and visualizing volumetric data. It includes a custom-built, scientific data-focused, VDB writer. The VDB writer is written in Zig with no external dependencies.

While this project focuses on neuroscience, it includes ndarray to VDB to support virtually any volumetric data pipeline.

This project is under active development and might not have everything you need. Please reference reference our roadmap to see what is in the works!

This project is available as a pre-release alpha on pypi. Presently it is only available for arm64. More operating systems coming soon!

🏗️ Building

If you are building locally, we use uv to build and test the project:

uv run python -m ziglang build && uv run pytest tests -s

This is how you might overlay a BOLD sequence onto an anatomical scan:

# acquire arrays and fps from the nibable image (see test_integration.py)

bold_diff = nv.Channel(
    "bold",
    sub(nv.prep_ndarray(bold_arr)),
    transform=bold_affine,
    source_fps=fps,
    playback_fps=24,
    speed=1,
    interpolation=nv.modes.Interpolation.direct,
)
t1 = nv.Channel(
    "t1",
    nv.prep_ndarray(t1_arr),
    transform=t1_affine,
    num_source_frames=bold_diff.num_output_frames,
    interpolation=nv.modes.Interpolation.frozen,
    prune=np.float32(0.1),
)

save_config = nv.SaveConfig("fmri_bold_sub_fade", folder=vdb_out / "fmri_seq")
fmri = nv.Sequence([bold_diff, t1], save_config)
fmri.write()

See tests/test_integration.py for more examples.

Higher sparsity amounts will result in better performance and lower disk space usage. However, after a certain point, they begin to degrade the VDB quality.

📀 Projects

• BoldViz: a Blender plugin for fMRI and MRI visualizations. It was used to create the renders in this README. A great place to start if you don't want to deal with writing any Python.
• Neurovolume Examples and Physarum include some good starting points for how one might use this library with numpy.
• The nibabel example shows how to use an external NIfTI parser, which could be of use for not-yet-supported filetypes. We're moving away from native file parsing as everyone seems to use numpy, but please reach out if this is something that you'd want!

☁️ Why VDB?

VDBs are a highly performant, art-directable, sparse volumetric data structure. Our volume-based approach aims to provide easy access to the original density data throughout the visualization and analysis pipeline. Unlike the openVDB repo, our smaller version is much more readable and does not need to be run in a docker container.

🧠 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 Study Link

Direct Download Link for T1 Anat test file

Direct Download Link for BOLD test file

The MNI Template can be found Here