AIND ANTs Transform Sidecar

Metadata for ANTs transform objects

Overview

This package provides metadata "sidecars" for ANTs (Advanced Normalization Tools) transform objects. ANTs produces spatial transformations (affine matrices and displacement fields) for medical image registration, but the transform files alone don't document important context like:

• The spatial domains (bounding boxes, spacing, voxel dimensions) of the fixed and moving images
• The coordinate system and units being used
• How to correctly chain and apply multiple transformation steps

This package provides Pydantic models that bundle ANTs transform file paths with their spatial metadata, enabling:

• Easy domain comparison: Hash functions make it simple to verify domains match
• Documentation: Clear specification of coordinate frames (LPS), units (mm), and domain definitions
• Interoperability: Standardized JSON format for sharing transformation metadata
• Convenience: Easy conversion to ANTsPy function arguments for applying transforms

Installation

If you choose to clone the repository, you can install the package by running the following command from the root directory of the repository:

pip install .

Otherwise, you can use pip:

pip install aind-ants-transform-sidecar

Usage

from aind_ants_transform_sidecar import (
    TransformSidecarV1,
    Domain,
    BBox,
    SynTriplet,
    load_package,
    dump_package,
)

# Define spatial domains for fixed and moving images
fixed_domain = Domain(
    spacing_LPS=(0.5, 0.5, 0.5),
    bbox=BBox(L=(-50.0, 50.0), P=(-50.0, 50.0), S=(-50.0, 50.0)),
    shape_canonical=(200, 200, 200),
)

moving_domain = Domain(
    spacing_LPS=(0.5, 0.5, 0.5),
    bbox=BBox(L=(-50.0, 50.0), P=(-50.0, 50.0), S=(-50.0, 50.0)),
    shape_canonical=(200, 200, 200),
)

# Create sidecar for ANTs SyN registration output
sidecar = TransformSidecarV1(
    fixed_domain=fixed_domain,
    moving_domain=moving_domain,
    transform=SynTriplet(
        affine="0GenericAffine.mat",
        warp="1Warp.nii.gz",
        inverse_warp="1InverseWarp.nii.gz",
    ),
)

# Serialize to JSON
json_str = dump_package(sidecar)

# Load from JSON
loaded = load_package(json_str)

# Get transformation chains
forward_chain = loaded.forward_chain()  # moving → fixed
inverse_chain = loaded.inverse_chain()  # fixed → moving

# Convert to ANTsPy arguments
transforms, whichtoinvert = forward_chain.antspy_apply_transforms_args()

Development

To develop the code, run:

uv sync

Development

Please test your changes using the full linting and testing suite:

./scripts/run_linters_and_checks.sh -c

Or run individual commands:

uv run --frozen ruff format          # Code formatting
uv run --frozen ruff check           # Linting
uv run --frozen mypy                 # Type checking
uv run --frozen interrogate -v       # Documentation coverage
uv run --frozen codespell --check-filenames  # Spell checking
uv run --frozen pytest --cov  # Tests with coverage

Documentation

sphinx-build -b html docs/source/ docs/build/html

License

This project is licensed under the MIT License - see the LICENSE file for details.