syntx 0.1.8

Symmetric diffeomorphic and affine image registration methods in PyTorch and JAX

syntx

syntx is a high-performance Python package focusing on symmetric diffeomorphic (SyN) and affine image registration methods, built on top of PyTorch and JAX for GPU/MPS acceleration and auto-differentiation capabilities.

Ported from the registration modules of the sulceye package, syntx is designed for distribution on PyPI and works seamlessly with standard medical image types, particularly ANTsImage from the antspyx library.

---

⚠️ Disclaimer & Differences from ants.registration

[!IMPORTANT] Validation Status: The deep-learning feature-space similarity metrics (VGG19, DINOv2, Swin UNETR) in this repository are experimental and have not been deeply validated on large-scale clinical cohorts. They are intended strictly for research and exploration.

Key Differences from ants.registration:

1. GPU Acceleration: Unlike standard ants.registration (which runs on CPU via ITK C++), Syntx supports PyTorch and JAX optimization backends for fast GPU/MPS execution.
2. Optimizers: Syntx uses Adam/Rprop for the affine stage and greedy composition steps scaling by ITK-style CFL (Courant-Friedrichs-Lewy) max voxel displacement bounds, while ANTs relies on C++ variants of L-BFGS or regularized gradient descent.
3. Velocity-Field & Elastic Smoothing: Separable Gaussian filters are implemented natively in JAX/PyTorch to perform fluid-like smoothing of update fields and elastic-like smoothing of composed fields, matching ITK's Gaussian regularization on the GPU.
4. Multi-Resolution Pyramid: Downsampling is performed dynamically using bilinear/trilinear grid interpolation in PyTorch/JAX to build image pyramids, rather than ITK's C++ downsampling filters.
5. Feature-Space Metrics: Similarity is evaluated on multi-scale feature representations (from vision transformers or CNNs) via zero-copy DLPack autograd sharing, rather than raw intensity maps.

---

Key Features

• Auto-Differentiation Backends: Choose between 'pytorch' and 'jax' for core computations.
• Symmetric Normalization (SyN): Fully symmetric greedy optimization matching classic ITK/ANTs SyN implementations.
• Interoperability: Seamless conversions between PyTorch/JAX coordinate spaces and ITK physical coordinate matrices.
• Direct PyPy/PyPI Packaging: Implemented cleanly with minimum external dependencies.

---

Installation

To install syntx locally from the repository:

pip install -e .

Dependencies

• numpy
• scipy
• matplotlib
• antspyx
• torch
• jax
• jaxlib

---

Usage Example

syntx exposes a high-level syn and registration API that mirrors ants.registration:

import ants
import syntx

# Load ANTs images
fixed = ants.image_read( ants.get_data('r16') )
moving = ants.image_read( ants.get_data('r64')  )

# Run registration using PyTorch (default)
result = syntx.syn(
    fixed=fixed,
    moving=moving,
    type_of_transform='SyNTo',
    backend='pytorch',
    reg_iterations=[100, 100, 50],
    affine_iterations=[100, 50, 20],
)

# Access the warped moving output image
warped_moving = result['warpedmovout']

# Access transform files (saved to temporary paths for ANTs compatibility)
forward_transforms = result['fwdtransforms']
inverse_transforms = result['invtransforms']

For JAX backend acceleration:

result = syntx.syn(
    fixed=fixed,
    moving=moving,
    type_of_transform='SyNTo',
    backend='jax',
    reg_iterations=[100, 100, 50],
    affine_iterations=[100, 50, 20],
)

---

Running the Examples and Generating Reports

An example comparing classic ANTs, PyTorch, and JAX registration is included under examples/. It generates a comparison report summarizing Mutual Information, Jacobian Determinants (topological safety), and Execution Speed.

To run the comparison:

python examples/generate_ants_2d_comparison_report.py

This generates an HTML report under reports/ants_2d_syn_comparison.html.

---

Running Tests

Tests can be executed via pytest:

pytest

---

Makefile Automation

A Makefile is included to automate standard development tasks:

• Install (install package in editable mode):

  make install
  

• Test (run test suite in Fast mode, skipping slow 3D registrations, and printing a code coverage table):

  make test
  

• Test All (run the full test suite including slow 3D registrations, with coverage):

  make test-all
  

• Clean (remove build artifacts, cached directories, and temporary files):

  make clean
  

• Release (clean, build sdist and wheel packages, and upload to PyPI using twine):

  make release
  

It automatically detects and prioritizes the active python virtual environment (VIRTUAL_ENV).

Release

make clean 
python -m build .
python -m twine upload --config-file ~/.pypirc dist/*