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

🚀 Zero-Effort Registration: syntx.auto_reg(fixed, moving)

syntx.auto_reg provides a zero-effort, "best defaults" registration function requiring zero parameter configuration from the user. It auto-detects hardware acceleration (CUDA / Apple Silicon MPS / CPU), selects the optimal compute engine (jax $\rightarrow$ pytorch), and computes comprehensive evaluation metrics directly in the return dictionary.

import ants
import syntx

# Load ANTs images (or numpy arrays)
fi = ants.image_read("fixed_brain.nii.gz")
mi = ants.image_read("moving_brain.nii.gz")

# Zero-effort registration — automatically selects GPU hardware and best defaults
res = syntx.auto_reg(fixed=fi, moving=mi)

# Output warped image and transforms
warped_img = res['warpedmovout']
fwd_transforms = res['fwdtransforms']

# Access integrated evaluation metrics
metrics = res['metrics']
print(f"Execution Time:  {metrics['execution_time_seconds']:.2f}s")
print(f"Device Used:     {metrics['device_used']}")
print(f"LNCC Score:      {metrics['lncc_score']:.4f}")
print(f"Folding Rate:    {metrics['folding_pct']:.4f}%")

CLI Command Line Usage

Run the ready-to-use example script from your terminal:

# 1. Zero-effort auto-detection
python examples/run_auto_reg_example.py

# 2. Custom input files, output directory, backend, and hardware overrides
python examples/run_auto_reg_example.py \
  --fixed ~/.antspyt1w/T_template0.nii.gz \
  --moving ~/data/blast_cohorts/BIDS/SOCOM/sub-Blast-05/ses-01/anat/sub-Blast-05_ses-01_run-001_T1w.nii.gz \
  --outdir ./auto_reg_output \
  --backend jax \
  --device mps

📊 Mindboggle Performance Benchmark & Cross-Study Results

Evaluated systematically across 90 3D Mindboggle brain volume pairs (40 intra-cohort + 50 inter-cohort cross-study pairs like NKI-RS-22 $\rightarrow$ OASIS-TRT-20):

Key Performance Advantages:

1. $24\times$ Acceleration: Syntx PyTorch completes full 3D volume registrations in ~13–19 seconds on Apple Silicon Metal (MPS) / NVIDIA GPUs vs 5.3 minutes (316s) for standard ITK C++ SyN.
2. Superior Accuracy: Syntx JAX achieves a mean Cortical DKT Dice score of 0.5968, outperforming classic ANTs C++ SyN (0.5948).
3. Topology Preserving: 100% fold-free diffeomorphic transformations (0.0000% negative Jacobians) across both intra- and inter-cohort registration tasks.

Usage Example (Standard API)

syntx also exposes syn and registration APIs mirroring 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/*