ICON Image Registration

RegisterImagesICON performs deformable image registration using the uniGradICON registration backend.

Class Reference

class physiomotion4d.RegisterImagesICON(log_level=20)[source]

Bases: RegisterImagesBase

ICON-based deformable image registration implementation.

This class extends RegisterImagesBase to provide GPU-accelerated deformable image registration using the ICON (Inverse Consistent Image Registration) algorithm implemented with deep learning models. It supports both full image registration and mask-constrained registration for specific anatomical regions.

The ICON algorithm ensures inverse consistency, meaning the forward and backward transformations are true inverses of each other. This is important for maintaining spatial relationships and avoiding registration artifacts.

ICON-specific features: - GPU acceleration using UniGradIcon framework - Mass preservation - LNCC (Local Normalized Cross Correlation) similarity metric - Inverse consistent transformations - Fine-tuning with 50 optimization steps per registration

Inherits from RegisterImagesBase: - Fixed and moving image management - Binary mask processing with optional dilation - Modality-specific parameter configuration - Standardized registration interface

net

The ICON deep learning registration network

Type:

unigradicon model

Example

>>> registrar = RegisterImagesICON()
>>> registrar.set_modality('ct')
>>> registrar.set_fixed_image(reference_image)
>>> result = registrar.register(moving_image)
>>> forward_transform = result['forward_transform']
__init__(log_level=20)[source]

Initialize the ICON image registration class.

Calls the parent RegisterImagesBase constructor to set up common parameters. The ICON deep learning network is initialized lazily on first use to avoid unnecessary GPU memory allocation.

Parameters:

log_level (int | str) – Logging level (default: logging.INFO)

set_weights_path(weights_path)[source]

Set a custom weights file for the uniGradICON network.

Use this to load a fine-tuned checkpoint instead of the default pretrained weights. Clears any previously loaded network so the new weights are applied on the next call to register().

Parameters:

weights_path (str) – Path to a uniGradICON checkpoint, e.g. “results/duke_4d_finetune/checkpoints/network_weights_100”

Return type:

None

set_number_of_iterations(number_of_iterations)[source]

Set the number of iterations for ICON registration.

Parameters:

number_of_iterations (int) – Number of fine-tuning steps for ICON registration

Return type:

None

set_multi_modality(enable)[source]

Enable or disable multi-modality registration.

Multi-modality registration is useful when aligning images from different imaging modalities (e.g., CT to MRI). Enabling this option adjusts the registration parameters to better handle differences in intensity distributions and contrast between modalities.

Parameters:

enable (bool) – True to enable multi-modality registration, False to disable

Return type:

None

Example

>>> registrar.set_multi_modality(True)  # Enable for CT to MRI
>>> registrar.set_multi_modality(False)  # Disable for CT to CT
set_mass_preservation(enable)[source]

Enable or disable mass preservation constraint.

Mass preservation is particularly useful for CT images where the intensity values correspond to physical tissue densities. Enabling this constraint helps maintain realistic intensity distributions during registration.

Parameters:

enable (bool) – True to enable mass preservation, False to disable

Return type:

None

Example

>>> registrar.set_mass_preservation(True)  # Enable for CT
>>> registrar.set_mass_preservation(False)  # Disable for MRI
preprocess(image, modality='ct')[source]

Preprocess the image for ICON registration.

Applies modality-specific preprocessing steps to prepare the image for registration. This may include intensity normalization, bias field correction, and resampling.

Parameters:

  • image (itk.image) – The input 3D image to preprocess

  • modality (str) – The imaging modality (‘ct’, ‘mri’, etc.)

Returns:

The preprocessed image

Return type:

itk.image

Example

>>> preprocessed_image = registrar.preprocess(raw_image, modality='ct')
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 ICON registration algorithm.

Implementation of the abstract register() method from RegisterImagesBase. Performs deformable registration to align the moving image with the fixed image using the ICON algorithm. The method automatically handles preprocessing, network initialization, and applies the computed transformation.

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. If provided along with fixed_mask, enables mask-constrained registration

  • moving_image_pre (itk.image, optional) – Pre-processed moving image. If None, preprocessing is performed automatically

  • initial_forward_transform (itk.Transform, optional) – Initial transformation from moving to fixed. If provided, it is used to transform the moving image before registration.

Returns:

Dictionary containing:

  • ”forward_transform”: transform moving image into fixed space

  • ”inverse_transform”: transform fixed image to moving space

  • ”loss”: Loss value from the registration

Return type:

dict

Note

The transformations are inverse consistent, meaning forward_transform ≈ inverse(inverse_transform). The inverse_transform is used to warp the fixed image to the moving image space. The forward_transform is used to warp the moving image to the fixed image space.

Implementation details:

  • Uses UniGradIcon with LNCC loss function

  • Optionally applies mass preservation

  • Performs 50 fine-tuning steps per registration

  • Supports both masked and unmasked registration modes

Example

>>> # Basic registration
>>> result = registrar.register(moving_image)
>>> forward_transform = result['forward_transform']
>>> inverse_transform = result['inverse_transform']
>>>
>>> # Masked registration for cardiac structures
>>> registrar.set_fixed_mask(heart_mask_fixed)
>>> result = registrar.register(moving_image, moving_mask=heart_mask_moving)

Basic Registration

import itk

from physiomotion4d import RegisterImagesICON

fixed = itk.imread("reference_frame.mha")
moving = itk.imread("moving_frame.mha")

registrar = RegisterImagesICON()
registrar.set_modality("ct")
registrar.set_number_of_iterations(50)
registrar.set_fixed_image(fixed)

result = registrar.register(moving)

forward_transform = result["forward_transform"]
inverse_transform = result["inverse_transform"]
loss = result["loss"]
registered = registrar.get_registered_image()

Result Dictionary

register() returns:

  • forward_transform: transform from moving image space to fixed image space

  • inverse_transform: transform from fixed image space to moving image space

  • loss: registration loss value reported by the backend

Configuration

Use set_number_of_iterations() to control per-pair refinement. Use set_multi_modality() and set_mass_preservation() for modality-specific behavior. There is no public set_device() method; device selection is owned by the underlying PyTorch/ICON runtime and installed CUDA environment.

See Also