Metadata-Version: 2.3
Name: neurovolume
Version: 0.1.0a15
Summary: Python library for Neurovolume. Build VDBs for scientific visualizations
Author: joachimbbp
Author-email: joachimbbp <jbbpfefferkorn@gmail.com>
Requires-Dist: nibabel>=5.4.0
Requires-Dist: numpy>=1.26.4
Requires-Dist: pytest>=9.0.1
Requires-Dist: ziglang>=0.15.2
Requires-Python: >=3.14
Description-Content-Type: text/markdown

![Render of a non-skull stripped MNI Template](readme_media/mni_template_render.png)

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 the "Missing Features" section.

This project is available as a pre-release alpha on [pypi](https://pypi.org/project/neurovolume/). 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:
```bash
uv run python -m ziglang build && uv run pytest tests -s
```
# 
This is how you could save a BOLD sequence from a .nii file

````python
import numpy as np
import neurovolume as nv
import nibabel as nib

img = nib.load(anat)
data = np.array(img.get_fdata(), order="C", dtype=np.float32)

nv.ndarray_to_vdb(
    nv.prep_ndarray(data, (0, 2, 1)),
    "anat_offset",
    output_dir=vdb_out,
    transform=nv.scale(img.affine, 0.01), # scaled for blender viewport
)
````
To use sparsity, add a `prune` value to your `ndarray_to_vdb` function call. This example gives good results for our T1 Anatomy scan:
```python
nv.ndarray_to_vdb(
    nv.prep_ndarray(data, (0, 2, 1)),
    "anat_offset_0p05_prune",
    output_dir=vdb_out,
    transform=_test_pattern_pos(img.affine),
    prune=np.float32(0.05),
)
```
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](https://github.com/joachimbbp/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](https://github.com/joachimbbp/neurovolume_examples) and [Physarum](https://github.com/joachimbbp/physarum) include some good starting points for how one might use this library with numpy.
- The [nibabel example](https://github.com/joachimbbp/neurovolume_examples/blob/master/nibabel_example.py) 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](https://www.openvdb.org/), 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.
- pypi package presently only supports arm64. Coverage for linux and windows is in the works.
- Documentation has not been written yet. Specifically:
    - Documentation for sparsity: we should establish how/when sparsity might result in a lossy compression.
- Multiple grids has yet to be implemented


# 🧠 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](https://openneuro.org/datasets/ds003548/versions/1.0.1)

[Direct Download Link for T1 Anat test file](https://s3.amazonaws.com/openneuro.org/ds003548/sub-01/anat/sub-01_T1w.nii.gz?versionId=5ZTXVLawdWoVNWe5XVuV6DfF2BnmxzQz)

[Direct Download Link for BOLD test file](https://s3.amazonaws.com/openneuro.org/ds003548/sub-01/func/sub-01_task-emotionalfaces_run-1_bold.nii.gz?versionId=tq8Y3ktm31Aa8JB0991n9K0XNmHyRS1Q)
 
The MNI Template can be found [Here](https://github.com/Angeluz-07/MRI-preprocessing-techniques/tree/main/assets/templates)
