microcorrelate.core
===================

.. py:module:: microcorrelate.core

.. autoapi-nested-parse::

   This module contains the core functionality of the microcorrelate package.



Classes
-------

.. autoapisummary::

   microcorrelate.core.ImageRegistration


Functions
---------

.. autoapisummary::

   microcorrelate.core.register_images


Module Contents
---------------

.. py:class:: 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: :py:obj:`SimpleITK.ImageRegistrationMethod`


   Intensity-based image registration using SimpleITK.

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

   :param transform_function: Type of spatial transform to estimate. Default is ``"affine"``.
   :type transform_function: {"affine", "rigid", "similarity"}
   :param num_histogram_bins: Number of histogram bins for the Mattes mutual information metric.
                              Default is 30.
   :type num_histogram_bins: int
   :param learning_rate: Learning rate for the gradient descent optimiser. Default is 1.0.
   :type learning_rate: float
   :param max_iterations: Maximum number of optimiser iterations. Default is 200.
   :type max_iterations: int
   :param plot_metrics: If True, plot the metric value live during registration. Default is True.
   :type plot_metrics: bool
   :param initial_rotation: Initial rotation angle in degrees (counterclockwise) applied before
                            optimisation. If None, no pre-rotation is applied. Default is None.
   :type initial_rotation: float or None

   .. attribute:: final_transform

      Estimated transform after calling :meth:`register_images`.
      ``None`` until registration has been run.

      :type: sitk.CompositeTransform or None


   .. py:method:: 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.

      :param fixed_image: Reference image defining the output grid.
      :type fixed_image: sitk.Image
      :param moving_image: Image to be resampled.
      :type moving_image: sitk.Image

      :returns: Registered image array, or None if no transform has been estimated yet.
      :rtype: np.ndarray or None



   .. py:method:: register_images(fixed_image: SimpleITK.Image, moving_image: SimpleITK.Image, initial_rotation: float | None = None) -> None

      Register moving image to fixed image.

      :param fixed_image: Reference image.
      :type fixed_image: sitk.Image
      :param moving_image: Image to be registered.
      :type moving_image: sitk.Image
      :param initial_rotation: Initial rotation angle in degrees. If provided, overrides the
                               initial_rotation set in __init__. If None, uses the value from
                               __init__. Default is None.
      :type initial_rotation: float or None



.. py:function:: 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.

   :param fixed_image: Fixed image in the registration.
   :type fixed_image: np.ndarray
   :param moving_image: Moving image to register to the fixed image.
   :type moving_image: np.ndarray
   :param transform_function: Type of transformation to use. Options are 'affine', 'rigid', and 'similarity'.
   :type transform_function: str
   :param num_histogram_bins: Number of histogram bins for the Mattes mutual information metric.
   :type num_histogram_bins: int
   :param learning_rate: Learning rate for the gradient descent optimizer.
   :type learning_rate: float
   :param max_iterations: Maximum number of iterations for the gradient descent optimizer.
   :type max_iterations: int
   :param initial_rotation: 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.
   :type initial_rotation: float or None

   :returns: **final_transform** -- The final transformation composed of manual rotation (if specified),
             centered initialization, and optimized registration.
   :rtype: sitk.Transform