Skip to content

bifti (Python) 0.1.0

Choose a tag to compare

View all tags
@J-Endres J-Endres released this 27 Oct 13:28
· 26 commits to main since this release
python-v0.1.0
782c3ce

First release of bifti on PyPI: a Python package for loading, saving and resampling
BIfTI MRI simulation phantoms (one JSON file
plus NIfTI files).

pip install bifti          # or: uv add bifti
pip install "bifti[torch]" # optional: torch-accelerated resampling (CPU or CUDA)

Requires Python 3.12 or newer.

Features

  • Load phantoms into NumPy: NumpyPhantom.load(path) reads the phantom JSON and every
    NIfTI it references into one NumpyTissue per tissue (density, T1, T2, T2', ADC,
    dB0, multi-channel B1+/B1-), with property defaults and func value mappings applied.
  • Reslicing (reslice_to): density-weighted footprint averaging, so downsampling really
    averages instead of dropping data and edges are not pulled towards zero. Uses torch when it is
    installed, NumPy otherwise (override with BIFTI_RESAMPLE_BACKEND=numpy|torch).
  • Saving: NumpyPhantom.save(dir) writes a self-contained, deterministic folder (float64
    NIfTIs + JSON, func baked in, no reslice_to), so you can reslice a phantom on disk or
    export one you built in memory.
  • JSON data model: BiftiPhantom.load / .save parse and write just the JSON, for
    generating or editing phantoms without touching voxel data.
  • Patient position: patient_to_scanner / to_scanner_affine map phantom coordinates to
    scanner coordinates.
  • Public registry: load_catalog(), load_registry() and
    load_registry_phantom(collection, name) download phantoms from Zenodo into a local cache.
    Browse them at https://mrx-org.github.io/bifti-phantoms/.

Known limitations

  • func mappings are evaluated with Python's eval: only load phantoms you trust.
  • Complex-valued NIfTI data is not supported yet: the imaginary part of a complex B1+/B1-
    map is dropped.
  • Only the default units are accepted.

This package was built with LLM assistance and has not been reviewed thoroughly yet. Expect
rough edges while the version is 0.x. Please report problems at
https://github.com/mrx-org/bifti-phantoms/issues.

Full documentation: https://github.com/mrx-org/bifti-phantoms/blob/main/python/bifti/README.md

Assets 2
Loading