Registration Base Class

Abstract base class for all image registration methods.

Class Reference

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

Bases: PhysioMotion4DBase

Base class for deformable image registration algorithms.

This class provides a common interface and shared functionality for implementing different image registration algorithms. It handles standard operations like image and mask management, preprocessing, and parameter configuration that are common across registration methods.

The base class is designed to support various registration algorithms including deep learning-based methods (Icon, UniGradIcon) and traditional methods (ANTs, ITK). Concrete implementations should inherit from this class and implement the register() method.

Key features: - Standardized interface for different registration algorithms - Fixed and moving image management - Binary mask processing with optional dilation - Modality-specific parameter configuration - Support for region-of-interest registration

net

Algorithm-specific network or registration object

Type:

object

modality

Image modality (‘ct’, ‘mri’, etc.) for parameter optimization

Type:

str

fixed_image

The target/reference image

Type:

itk.image

fixed_image_pre

Preprocessed fixed image

Type:

itk.image

fixed_mask

Binary mask for fixed image ROI

Type:

itk.image

mask_dilation_mm

Mask dilation amount in millimeters

Type:

float

Example

>>> class MyRegistration(RegisterImagesBase):
...     def registration_method(self, moving_image, **kwargs):
...         # Implement specific registration algorithm
...         return {
...             'forward_transform': tfm_forward,  # Moving → Fixed
...             'inverse_transform': tfm_inverse,  # Fixed → Moving
...             'loss': 0.0,
...         }
>>>
>>> registrar = MyRegistration()
>>> registrar.set_modality('ct')
>>> registrar.set_fixed_image(reference_image)
>>> result = registrar.register(moving_image)
>>> forward_tfm = result['forward_transform']  # Moving → Fixed
>>> inverse_tfm = result['inverse_transform']  # Fixed → Moving
__init__(log_level=20)[source]

Initialize the base image registration class.

Sets up the common registration parameters with default values. Algorithm-specific components (like neural networks or optimization objects) should be initialized in the concrete implementation to avoid unnecessary resource allocation.

Parameters:

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

set_modality(modality)[source]

Set the imaging modality for registration optimization.

Different imaging modalities benefit from different registration parameters. CT images.

Parameters:

modality (str) – The imaging modality. Supported values: ‘ct’, ‘mri’

Return type:

None

Example

>>> registrar.set_modality('ct')
>>> registrar.set_modality('mri')
set_fixed_image(fixed_image)[source]

Set the fixed/target image for registration.

The fixed image serves as the reference coordinate system to which all moving images will be aligned. Setting a new fixed image clears any preprocessed data to ensure consistency.

Parameters:

fixed_image (itk.image) – The 3D reference image that serves as the target for registration

Return type:

None

Example

>>> registrar.set_fixed_image(reference_frame)
set_mask_dilation(mask_dilation_mm)[source]

Set the dilation of the fixed and moving image masks.

Parameters:

mask_dilation_mm (float) – The dilation in millimeters.

Return type:

None

set_fixed_mask(fixed_mask)[source]

Set a binary mask for the fixed image region of interest.

The mask constrains registration to focus on specific anatomical regions, improving accuracy and reducing computation time. The mask is automatically converted to binary format. If mask_dilation_mm is set, the mask is dilated by the specified amount.

Parameters:

fixed_mask (itk.image) – Binary or label mask defining the region of interest in the fixed image. Non-zero values are treated as foreground

Return type:

None

Example

>>> # Use heart mask to focus registration on cardiac structures
>>> registrar.set_fixed_mask(heart_mask)
set_fixed_labelmap(fixed_labelmap)[source]

Set the fixed image labelmap (multi-label segmentation).

Parameters:

fixed_labelmap (itk.Image, optional) – Multi-label segmentation co-registered with the fixed image, or None to clear.

Return type:

None

preprocess(image, modality='ct')[source]

Preprocess the image based on modality-specific requirements.

This method applies preprocessing steps such as intensity normalization, histogram equalization, or noise reduction tailored to the specified imaging modality. Preprocessing enhances image quality and improves registration accuracy.

Parameters:

  • image (itk.image) – The 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]

Main registration method to align moving image to fixed image.

This method serves as the primary interface for performing image registration. It takes a moving image and optional mask and preprocessed image, and returns the forward and backward transformations.

Note: This is an internal method that should be implemented by subclasses. The public API is register() which wraps this method.

Parameters:

  • moving_image (itk.image) – The 3D image to be registered to the fixed image

  • moving_mask (itk.image, optional) – Binary mask for moving image ROI

  • moving_labelmap (itk.image, optional) – Multi-label segmentation for the moving image

  • moving_image_pre (itk.image, optional) – Preprocessed moving image

  • initial_forward_transform (itk.Transform, optional) – Initial transformation from moving to fixed

Returns:

Dictionary containing:

  • ”forward_transform”: Transform that warps moving image into fixed space

  • ”inverse_transform”: Transform that warps fixed image into moving space

  • ”loss”: Registration loss/metric value

Return type:

dict

Raises:

ValueError – If fixed image is not set

register(moving_image, moving_mask=None, moving_labelmap=None, moving_image_pre=None, initial_forward_transform=None)[source]

Register a moving image to the fixed image.

This is the main registration method that must be implemented by concrete subclasses. It should align the moving image to the fixed image using the specific algorithm implemented by the subclass.

Parameters:

  • moving_image (itk.image) – The 3D image to be registered to the fixed image

  • moving_mask (itk.image, optional) – Binary mask for moving image ROI

  • moving_labelmap (itk.image, optional) – Multi-label segmentation for the moving image

  • moving_image_pre (itk.image, optional) – Preprocessed moving image

  • initial_forward_transform (itk.Transform, optional) – Initial transformation from moving to fixed

Returns:

Dictionary containing transformation results:

  • ”forward_transform”: Transforms moving image to fixed space (warps moving → fixed)

  • ”inverse_transform”: Transforms fixed image to moving space (warps fixed → moving)

  • ”loss”: Registration loss/metric value

Return type:

dict

Note

  • forward_transform: Use this to warp the moving image to match the fixed image

  • inverse_transform: Use this to warp the fixed image to match the moving image

Raises:

NotImplementedError – This method must be implemented by subclasses

get_registered_image()[source]

Get the registered image.

Returns:

The registered image

Return type:

itk.Image

classmethod get_log_classes()

Get the list of classes currently showing logs.

Return type:

list[str]

Returns:

List of class names that are allowed to show logs. Empty list if filter is disabled (all classes shown).

Example

>>> classes = PhysioMotion4DBase.get_log_classes()
>>> print(classes)
['RegisterModelsPCA', 'WorkflowFitStatisticalModelToPatient']
log_critical(message, *args)

Log a critical message with optional %-style formatting.

Parameters:

  • message (str) – The critical message to log (can contain %-style placeholders)

  • *args (Any) – Arguments for %-style string formatting

Return type:

None

Example

>>> self.log_critical('System failure at %s', timestamp)
>>> self.log_critical('Critical error: %(msg)s', {'msg': 'Out of memory'})
log_debug(message, *args)

Log a debug message with optional %-style formatting.

Parameters:

  • message (str) – The debug message to log (can contain %-style placeholders)

  • *args (Any) – Arguments for %-style string formatting

Return type:

None

Example

>>> self.log_debug('Processing %s with %d items', filename, count)
>>> self.log_debug('Value is %(value)d', {'value': 42})
log_error(message, *args)

Log an error message with optional %-style formatting.

Parameters:

  • message (str) – The error message to log (can contain %-style placeholders)

  • *args (Any) – Arguments for %-style string formatting

Return type:

None

Example

>>> self.log_error('Failed to load %s: %s', filename, error_msg)
>>> self.log_error('Error code: %(code)d', {'code': 404})
log_info(message, *args)

Log an info message with optional %-style formatting.

Parameters:

  • message (str) – The info message to log (can contain %-style placeholders)

  • *args (Any) – Arguments for %-style string formatting

Return type:

None

Example

>>> self.log_info('Loading file: %s', filepath)
>>> self.log_info('Iteration %(iter)d of %(total)d', {'iter': 5, 'total': 10})
log_progress(current, total, prefix='Progress')

Log progress information.

Parameters:

  • current (int) – Current step/iteration number

  • total (int) – Total number of steps/iterations

  • prefix (str) – Prefix text for the progress message. Default: ‘Progress’

Return type:

None

Example

>>> for i in range(100):
...     self.log_progress(i + 1, 100)
>>> self.log_progress(5, 10, prefix='Processing')

Note

For custom formatted progress messages, use log_info() directly: >>> self.log_info(‘Loading %s: %d/%d’, filename, current, total)

log_section(title, *args, width=70, char='=')

Log a formatted section header with optional %-style formatting.

Useful for visually separating major sections of output.

Parameters:

  • title (str) – The section title (can contain %-style placeholders)

  • *args (Any) – Arguments for %-style string formatting of title

  • width (int) – Total width of the header line. Default: 70

  • char (str) – Character to use for the header line. Default: ‘=’

Return type:

None

Example

>>> self.log_section('Stage 1: Initialization')
>>> self.log_section('Processing file: %s', filename)
>>> self.log_section('Stage %(num)d: %(name)s', {'num': 2, 'name': 'Analysis'})
# Outputs:
# ======================================================================
# Stage 2: Analysis
# ======================================================================
log_warning(message, *args)

Log a warning message with optional %-style formatting.

Parameters:

  • message (str) – The warning message to log (can contain %-style placeholders)

  • *args (Any) – Arguments for %-style string formatting

Return type:

None

Example

>>> self.log_warning('Memory usage at %d%%', usage_percent)
>>> self.log_warning('Parameter %(name)s out of range', {'name': 'threshold'})
classmethod set_log_all_classes()

Enable logging output from all PhysioMotion4D classes.

Disables the class filter so all classes show their logs.

Example

>>> PhysioMotion4DBase.set_log_all_classes()
>>> # Now all classes will show their logs
Return type:

None

classmethod set_log_classes(class_names)

Set which classes should show their logging output.

Only log messages from the specified classes will be displayed. All other classes will have their logs hidden.

Parameters:

class_names (list[str]) – List of class names to show logs from. Example: [“RegisterModelsPCA”, “WorkflowFitStatisticalModelToPatient”]

Return type:

None

Example

>>> PhysioMotion4DBase.set_log_classes(['RegisterModelsPCA'])
>>> # Now only RegisterModelsPCA logs will be shown
classmethod set_log_level(log_level)

Set the logging level for all PhysioMotion4D classes.

Parameters:

log_level (int | str) – Logging level. Can be an integer (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL) or a string (‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’).

Return type:

None

Example

>>> import logging
>>> PhysioMotion4DBase.set_log_level(logging.DEBUG)
>>> # or
>>> PhysioMotion4DBase.set_log_level('DEBUG')

Overview

RegisterImagesBase provides the foundation for all registration implementations.

Key Responsibilities:

  • Define standard registration interface

  • Provide transform management utilities

  • Handle image resampling operations

  • Manage registration parameters

See Also

Navigation

Image Registration Modules | ANTs Registration | ICON Image Registration