neurovolume 0.1.0a4

Python library for Neurovolume. Build VDBs for scientific visualizations

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. Currently some NIfTI1 files can be parsed natively.

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

This project is very much a work in progress. (see "Missing Features" below). As of now, I do not recommend regarding the images created by this software as scientifically accurate.

🐍 ndArray Example

The following following is an example of how you might use this project in a neuroscience pipeline. (While it requires external dependencies, this implementation actually runs faster than the native NIfTI1 parsing implementation)

import nibabel as nib
import neurovolume_lib as nv
import numpy as np
from datetime import datetime

static_testfile = "./media/sub-01_T1w.nii"

def normalize_array(arr):
    return (arr - np.min(arr)) / (np.max(arr) - np.min(arr))

img = nib.load(static_testfile)
data = np.array(img.get_fdata(), order='C', dtype=np.float64)
norm = normalize_array(data).astype(np.float64)

norm = np.transpose(norm, (1, 2, 0))
norm = np.ascontiguousarray(norm)

output = "./output/from_nib.vdb"
nv.ndarray_to_VDB(norm, output, img.affine)

Note that all data must be normalized from 0.0-1.0 before being written to a VDB.

☁️ Why VDB?

VDBs are a highly performant, art-directable, volumetric data structure that supports animations. 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.

🛠️ Missing Features

While a comprehensive road-map will be published soon, there are a few important considerations to take into account now.

• Presently the VDB writer isn't sparse nor does it support multiple grids. Tiles and multiple grids are in development.
• Neurovolume currently only natively supports NIfTI1 files (and only some variants). Full coverage and NIfTI2 will be supported soon. Until then, you can use an ndarray as an intermediary (see Python Usage).
• Frame interpolation (present in the original Go prototype) is currently under development on this branch. If you wish to access the old Go code, check out the archive
• Documentation has not been written yet.

🧠 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