ICP with ITK Backend

ICP registration using ITK’s optimized implementation.

Class Reference

class physiomotion4d.RegisterModelsICPITK(fixed_model, reference_image=None, point_subsample_step=4, log_level=20)[source]

Bases: PhysioMotion4DBase

Register shape models using model to distance map minimization.

Optimization Objective:

Minimize the mean distance of the distance map sampled at model points using ITK’s LinearInterpolateImageFunction. This aligns the model with bright regions in target image.

fixed_model
Type:

pv.PolyData

moving_model
Type:

pv.PolyData

reference_image

Patient image providing coordinate frame and distance data

Type:

itk.Image

transform_type

Rigid or Affine

forward_point_transform

Optimized transformation

Type:

itk.ComposeScaleSkewVersor3DTransform

inverse_point_transform

Optimized transformation

Type:

itk.ComposeScaleSkewVersor3DTransform

registered_model

Final registered model

Type:

pv.PolyData

Note

The fixed_model and moving_model are typically extracted from VTU models using model.extract_surface(algorithm=”dataset_surface”) before passing to this class.

__init__(fixed_model, reference_image=None, point_subsample_step=4, log_level=20)[source]

Initialize the ICP-ITK model registration.

Parameters:

  • fixed_model (PolyData) – Target model (surface mesh) to register to

  • reference_image (Optional[Image]) – Optional patient image providing coordinate frame and distance data

  • point_subsample_step (int) – Step size for subsampling model points during registration (default: 4)

  • log_level (int | str) – Logging level (logging.DEBUG, logging.INFO, logging.WARNING) (default: logging.INFO)

set_reference_image(reference_image)[source]

Set the reference image for registration.

Parameters:

reference_image (Image) – ITK image providing coordinate frame and distance data

Return type:

None

set_fixed_model(fixed_model)[source]

Set the average model for registration.

Parameters:

fixed_model (PolyData) – PyVista model containing the mean 3D shape model (unstructured grid or polydata)

Return type:

None

register(moving_model, initial_transform=None, transform_type='Affine', method='L-BFGS-B', scale_bound=0.2, skew_bound=0.03, versor_bound=0.15, translation_bound=15, max_iterations=500)[source]

Optimize affine alignment to minimize mean distance.

to align the mean shape model with bright regions in the image.

Parameters:

  • initial_transform (Optional[MatrixOffsetTransformBase]) – Initial ITK ComposeScaleSkewVersor3DTransform for starting point

  • method (str) – Optimization method for scipy.optimize.minimize. Default: ‘Nelder-Mead’

  • max_iterations (int) – Maximum number of optimization iterations. Default: 500

Returns:

  • transform: Optimized ITK ComposeScaleSkewVersor3DTransform

  • mean_distance: Final mean distance metric value

Return type:

Tuple of (transform, mean_distance)

Raises:

ValueError – If reference image is not set

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')

Navigation

ICP (Iterative Closest Point) | Model Registration Modules | Distance Map Registration