ANTs Registration
RegisterImagesANTs provides optimization-based deformable image
registration through ANTs.
Class Reference
- class physiomotion4d.RegisterImagesANTs(log_level=20)[source]
Bases:
RegisterImagesBaseANTs-based deformable image registration implementation.
This class extends RegisterImagesBase to provide deformable image registration using the Advanced Normalization Tools (ANTs) algorithm. It supports various registration types including affine, deformable (SyN), and elastic registration for aligning medical images.
ANTs is a well-established image registration framework with proven accuracy and robustness for medical imaging applications. The SyN (Symmetric Normalization) algorithm provides diffeomorphic registration with inverse consistency.
ANTs-specific features: - Multiple transform types: Rigid, Affine, SyN, ElasticSyN - Robust optimization algorithms - Support for multi-resolution registration - Symmetric normalization for inverse consistency - Comprehensive metric options (MI, CC, Mattes)
Inherits from RegisterImagesBase: - Fixed and moving image management - Binary mask processing with optional dilation - Modality-specific parameter configuration - Standardized registration interface
Example
>>> registrar = RegisterImagesANTs() >>> registrar.set_modality('ct') >>> registrar.set_fixed_image(reference_image) >>> registrar.set_transform_type('Affine') >>> registrar.set_metric('Mattes') >>> result = registrar.register(moving_image) >>> inverse_transform = result['inverse_transform']
- __init__(log_level=20)[source]
Initialize the ANTs image registration class.
Calls the parent RegisterImagesBase constructor to set up common parameters. Default ANTs registration parameters are set to work well for medical images.
- set_number_of_iterations(number_of_iterations)[source]
Set the number of iterations for ANTs registration.
- itk_affine_transform_to_ants_transform(itk_tfm)[source]
Convert ITK affine/rigid transform to ANTs affine transform.
Converts an ITK MatrixOffsetTransformBase-derived transform (such as AffineTransform or Rigid3DTransform) to an ANTs affine transform object.
The conversion extracts: - 3x3 transformation matrix (converted to row-major order for ANTs) - Translation vector - Center of rotation (fixed parameters)
- Parameters:
itk_tfm (itk.Transform) – ITK affine or rigid transform derived from itkMatrixOffsetTransformBase (e.g., itk.AffineTransform[itk.D, 3], itk.Rigid3DTransform, etc.)
- Returns:
ANTs affine transform object
- Return type:
ants.ANTsTransform
- Raises:
ValueError – If transform dimension is not 3D
Example
>>> # Create ITK affine transform >>> affine_itk = itk.AffineTransform[itk.D, 3].New() >>> affine_itk.SetIdentity() >>> # Convert to ANTs >>> affine_ants = registrar.itk_affine_transform_to_ants_transform(affine_itk) >>> # Use in ANTs operations >>> result = ants.apply_ants_transform(affine_ants, moving_image)
- itk_transform_to_antsfile(itk_tfm, reference_image, output_filename)[source]
Convert ITK transform to ANTs transform file.
This method converts any ITK transform (Affine, Rigid, DisplacementField, etc.) to an ANTs transform file that can be used as initial_transform in ants.registration() or ants.label_image_registration().
The conversion process: 1. Uses TransformTools to convert the ITK transform to a displacement field 2. Converts the displacement field image from ITK to ANTs format 3. Creates an ANTsPy transform object from the displacement field 4. Writes the ANTs transform to a file
- Parameters:
itk_tfm (itk.Transform) – Input ITK transform to convert. Can be any ITK transform type (AffineTransform, DisplacementFieldTransform, CompositeTransform, etc.)
reference_image (itk.Image) – Reference image that defines the spatial domain for the displacement field (spacing, size, origin, direction)
output_filename (str) – Path where the ANTs transform file will be written. Typically should have .mat extension for ANTs transforms.
- Returns:
List containing the path to the written ANTs transform file
- Return type:
Example
>>> # Convert ITK affine transform to ANTs file >>> affine_itk = itk.AffineTransform[itk.D, 3].New() >>> affine_itk.SetIdentity() >>> transform_files = registrar.itk_transform_to_antsfile( ... affine_itk, reference_image, 'initial_transform.mat' ... ) >>> >>> # Use in registration >>> result = ants.registration( ... fixed=fixed_ants, moving=moving_ants, initial_transform=transform_files ... )
- registration_method(moving_image, moving_mask=None, moving_labelmap=None, moving_image_pre=None, initial_forward_transform=None)[source]
Register moving image to fixed image using ANTs registration algorithm.
Implementation of the abstract register() method from RegisterImagesBase. Performs deformable registration to align the moving image with the fixed image using ANTs SyN or other specified algorithms.
- Parameters:
moving_image (itk.image) – The 3D image to be registered/aligned.
moving_mask (itk.image, optional) – Binary mask defining the region of interest in the moving image
moving_image_pre (ants.core.ANTsImage, optional) – Pre-processed moving image in ANTs format. If None, preprocessing is performed automatically
initial_forward_transform (itk.Transform, optional) – Initial transform from moving to fixed space. Can be any ITK transform type (Affine, Rigid, DisplacementField, Composite, etc.). Will be converted to ANTs format automatically. The returned transforms will include this initial transform composed with the registration result.
- Returns:
- Dictionary containing:
”forward_transform”: Transformation from moving to fixed
”inverse_transform”: Transformation from fixed to moving
”loss”: Loss value from the registration
- Return type:
Note
For SyN registration, the transformations are approximately inverse consistent. The forward and inverse transforms are stored separately by ANTs.
IMPORTANT: ANTs registration does NOT include the initial_transform in its output fwdtransforms/invtransforms. This method automatically composes the initial transform with the registration result, so the returned transforms include both the initial alignment and the registration refinement.
- Implementation details:
Uses ANTs registration with configurable transform types
Supports multi-resolution optimization
Handles masked and unmasked registration
Returns ITK-compatible displacement field transforms
Initial transforms are converted from ITK to ANTs format automatically
Example
>>> # Basic registration >>> result = registrar.register(moving_image) >>> inverse_transform = result['inverse_transform'] >>> forward_transform = result['forward_transform'] >>> >>> # Masked registration for cardiac structures >>> registrar.set_fixed_mask(heart_mask_fixed) >>> result = registrar.register(moving_image, moving_mask=heart_mask_moving) >>> >>> # Registration with initial transform >>> initial_tfm = itk.AffineTransform[itk.D, 3].New() >>> result = registrar.register(moving_image, initial_forward_transform=initial_tfm)
Basic Registration
import itk
from physiomotion4d import RegisterImagesANTs
fixed = itk.imread("reference.mha")
moving = itk.imread("moving.mha")
registrar = RegisterImagesANTs()
registrar.set_modality("ct")
registrar.set_transform_type("SyN")
registrar.set_number_of_iterations([30, 15, 7])
registrar.set_fixed_image(fixed)
result = registrar.register(moving)
forward_transform = result["forward_transform"]
inverse_transform = result["inverse_transform"]
registered = registrar.get_registered_image()