MedVol

A lightweight Python wrapper that unifies SimpleITK, nibabel, and pynrrd under a single, simple API for reading and writing 2‑D, 3‑D, and 4‑D medical images in NIfTI (.nii/.nii.gz) and NRRD (.nrrd) formats.

✨ Features

• Unified API – one MedVol class works with all three back‑ends.
• Automatic backend selection based on file extension:
  • .nii/.nii.gz → nibabel
  • .nrrd → pynrrd
• Explicit backend override via the backend= argument.
• Canonical RAS+ orientation by default (no interpolation).
• Optional de‑obliquing via get_geometry(deoblique=True).
• Geometry is stored in a single source of truth – the affine matrix.
• Convenient derived properties: spacing, origin, direction, rotation, shear, coordinate_system.
• Direct access to the raw backend header through header.

📦 Installation

pip install medvol

🚀 Quick start

from medvol import MedVol

# Load the bundled 3‑D example image (NIfTI).
img = MedVol("examples/data/3d_img.nii.gz")

print("Backend:", img.backend)
print("Shape:", img.array.shape)
print("Coordinate system:", img.coordinate_system)
print("Spacing:", img.spacing)
print("Origin:", img.origin)
print("Direction:\n", img.direction)
print("Affine:\n", img.affine)
print("Rotation:\n", img.rotation)
print("Header type:", type(img.header).__name__)

# Access the centre voxel value.
center = tuple(s // 2 for s in img.array.shape)
print("Center voxel:", img.array[center])

To inspect the native geometry without canonicalisation:

native = MedVol(
    "examples/data/3d_img.nii.gz",
    backend="simpleitk",
    canonicalize=False,
)
print("Native coordinate system:", native.coordinate_system)

See the runnable demo at examples/example_showcase_3d_nifti.py.

Contributing

Contributions are welcome! Please open a pull request with clear changes and add tests when appropriate.

Acknowledgments

This repository is developed and maintained by the Applied Computer Vision Lab (ACVL) of Helmholtz Imaging and the Division of Medical Image Computing at DKFZ.