microcorrelate.core#

This module contains the core functionality of the microcorrelate package.

Classes#

ImageRegistration

Intensity-based image registration using SimpleITK.

Functions#

register_images(→ SimpleITK.Transform)

Register two images using SimpleITK. The fixed image is the reference image to

Module Contents#

class microcorrelate.core.ImageRegistration(transform_function: Literal['affine', 'rigid', 'similarity'] = 'affine', num_histogram_bins: int = 30, learning_rate: float = 1.0, max_iterations: int = 200, plot_metrics: bool = True, initial_rotation: float | None = None)#

Bases: SimpleITK.ImageRegistrationMethod

Intensity-based image registration using SimpleITK.

Wraps SimpleITK.ImageRegistrationMethod with Mattes mutual information metric and gradient descent with line search optimisation. Optionally plots the metric value at each iteration.

Parameters:

  • transform_function ({"affine", "rigid", "similarity"}) – Type of spatial transform to estimate. Default is "affine".

  • num_histogram_bins (int) – Number of histogram bins for the Mattes mutual information metric. Default is 30.

  • learning_rate (float) – Learning rate for the gradient descent optimiser. Default is 1.0.

  • max_iterations (int) – Maximum number of optimiser iterations. Default is 200.

  • plot_metrics (bool) – If True, plot the metric value live during registration. Default is True.

  • initial_rotation (float or None) – Initial rotation angle in degrees (counterclockwise) applied before optimisation. If None, no pre-rotation is applied. Default is None.

final_transform#

Estimated transform after calling register_images(). None until registration has been run.

Type:

sitk.CompositeTransform or None

apply_registration(fixed_image: SimpleITK.Image, moving_image: SimpleITK.Image) → numpy.ndarray | None#

Apply the estimated transform to resample a moving image onto the fixed grid.

Parameters:

  • fixed_image (sitk.Image) – Reference image defining the output grid.

  • moving_image (sitk.Image) – Image to be resampled.

Returns:

Registered image array, or None if no transform has been estimated yet.

Return type:

np.ndarray or None

register_images(fixed_image: SimpleITK.Image, moving_image: SimpleITK.Image, initial_rotation: float | None = None) → None#

Register moving image to fixed image.

Parameters:

  • fixed_image (sitk.Image) – Reference image.

  • moving_image (sitk.Image) – Image to be registered.

  • initial_rotation (float or None) – Initial rotation angle in degrees. If provided, overrides the initial_rotation set in __init__. If None, uses the value from __init__. Default is None.

microcorrelate.core.register_images(fixed_image: numpy.ndarray, moving_image: numpy.ndarray, transform_function: str = 'affine', num_histogram_bins: int = 50, learning_rate: float = 1.0, max_iterations: int = 200, initial_rotation: float | None = None) → SimpleITK.Transform#

Register two images using SimpleITK. The fixed image is the reference image to which the moving image is registered. Currently supported transformations are affine, rigid, and similarity. The registration is performed using the Mattes mutual information metric and gradient descent with line search optimization.

Parameters:

  • fixed_image (np.ndarray) – Fixed image in the registration.

  • moving_image (np.ndarray) – Moving image to register to the fixed image.

  • transform_function (str) – Type of transformation to use. Options are ‘affine’, ‘rigid’, and ‘similarity’.

  • num_histogram_bins (int) – Number of histogram bins for the Mattes mutual information metric.

  • learning_rate (float) – Learning rate for the gradient descent optimizer.

  • max_iterations (int) – Maximum number of iterations for the gradient descent optimizer.

  • initial_rotation (float or None) – Initial rotation angle in degrees (counterclockwise) to apply before registration. Useful for coarse manual alignment. If None or 0, no rotation is applied. Default is None.

Returns:

final_transform – The final transformation composed of manual rotation (if specified), centered initialization, and optimized registration.

Return type:

sitk.Transform