Skip to content

Restore ants.to_nibabel / ants.from_nibabel short names (fixes #693) - #962

Open
eliem08 wants to merge 1 commit into
ANTsX:mainfrom
eliem08:feat/nibabel-interop
Open

eliem08 wants to merge 1 commit into
ANTsX:mainfrom
eliem08:feat/nibabel-interop

Conversation

@eliem08

@eliem08 eliem08 commented Nov 20, 2026

Copy link
Copy Markdown

Fixes #693.

Problem

ants.to_nibabel and ants.from_nibabel were removed in 0.5.3 (PR #637 renamed ants/utils/convert_nibabel.py and dropped the short names). The longer ants.to_nibabel_nifti / ants.from_nibabel_nifti names added later (PRs #877/#878/#892) do the conversion, but the names requested in #693 — and used by downstream code — are still missing:

>>> import ants
>>> ants.to_nibabel
AttributeError  # on 0.6.3, and on master

What this PR does

  • Restores ants/utils/convert_nibabel.py with to_nibabel / from_nibabel as thin wrappers over to_nibabel_nifti / from_nibabel_nifti, exported from ants.utils so they are available as ants.to_nibabel / ants.from_nibabel. The *_nifti names are unchanged and remain the canonical implementations.
  • Unlike the pre-0.5.3 versions, these do not round-trip through a temporary file on disk: the conversion is done directly from the image geometry, and uses get_fdata() (the old nifti_to_ants used the long-deprecated get_data(), which is what crashed downstream in to_nibabel and from_nibabel missing from version 0.5.3 api #693).
  • nibabel stays an optional dependency, as @ncullen93 intended when the functions were removed: it is only imported lazily, inside to_nibabel_nifti. from_nibabel does not import nibabel at all — it works on any object exposing the nibabel image interface (.affine, .header, .get_fdata()). to_nibabel without nibabel installed now raises an ImportError telling the user to pip install nibabel instead of failing with a bare import traceback.

Affine conventions

The part that historically went wrong (#52, #64), documented in the new module docstring and pinned down by tests:

  • nibabel / NIfTI use RAS+ world coordinates; ANTsPy / ITK use LPS+. Converting flips the sign of the first two world axes (diag(-1, -1, 1, 1)) in both directions.
  • from_nibabel reads nib_image.affine, which nibabel builds as the sform when sform_code > 0, otherwise the qform — so when both are present the sform wins, matching nibabel's own rule.
  • ITK cannot represent shear, so a sheared sform is orthogonalized ("desheared") before the direction is extracted; if deshearing would move an axis by more than max_angle_deviation degrees a ValueError is raised. A rigid sform converts exactly.
  • to_nibabel writes the geometry as the NIfTI sform (sform_code 2, 'aligned') and nibabel derives a matching qform from it, so sform and qform agree on the output. Units are set to mm / sec.

One gotcha found while writing the tests: setting a transform on a nibabel image's header alone does not update the image's cached .affine — the image-level set_sform / set_qform methods must be used. The sform/qform tests use the image-level setters.

Tests

New tests in tests/test_utils.py (TestModule_convert_nibabel, TestModule_convert_nibabel_no_nibabel), all run against installed antspyx 0.6.3 with the patched pure-Python files overlaid (no C++ build):

  • test_short_names_exist — ants.to_nibabel / ants.from_nibabel exist and live in ants.utils.convert_nibabel
  • test_roundtrip_3d — 3D oblique image round-trips (data + affine, geometry stable across round-trips)
  • test_affine_ras_lps_convention — origin x/y negated, z unchanged; direction matches the LPS-converted affine
  • test_sform_preferred_over_qform — sform and qform disagree, sform wins
  • test_qform_used_when_sform_absent — sform_code == 0, qform is used
  • test_to_nibabel_writes_sform — output has sform_code == 2 ('aligned'), sform == affine, qform == affine
  • test_orientation_roundtrip — permuted/flipped (det +1) orientation round-trips exactly
  • test_timeseries_roundtrip — 4D image, toffset preserved
  • test_from_nibabel_needs_no_nibabel_import — conversion works with nibabel hidden from sys.modules, using a stub image object
  • test_to_nibabel_without_nibabel_raises_helpful_error — ImportError mentioning pip install nibabel

Test results

pytest tests/test_utils.py -k "TestModule_convert_nibabel or TestModule_nibabel_to_ants"
14 passed, 88 deselected in 37.59s

10 new tests pass; the 4 pre-existing TestModule_nibabel_to_ants tests also pass (no regression from the lazy-import change). CPU-only; no GPU tests involved. Ruff: the new module is clean (ruff check + ruff format --check pass); tests/test_utils.py keeps its pre-existing 57 ruff findings, unchanged by this PR, and the touched nibabel_nifti_to_ants.py goes from 4 pre-existing findings to 3 (the dropped unused import nibabel as nib).

Signed-off-by: Ilyass Emssaad emssaadelias@gmail.com

)

Signed-off-by: Ilyass Emssaad <emssaadelias@gmail.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

to_nibabel and from_nibabel missing from version 0.5.3 api

1 participant