microcorrelate.napari
=====================

.. py:module:: microcorrelate.napari

.. autoapi-nested-parse::

   This module contains functions intendend for interactive landmark-based registration
   with Napari.



Classes
-------

.. autoapisummary::

   microcorrelate.napari.NapariRegistrator
   microcorrelate.napari.ViewerParams


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

.. py:class:: NapariRegistrator(fixed_data: numpy.ndarray, moving_data: numpy.ndarray, fixed_spacing: tuple[float, float], moving_spacing: tuple[float, float], transform_type: Literal['affine', 'rigid', 'similarity'] = 'affine', fixed_channel_axis: int | None = None, moving_channel_axis: int | None = None, viewer_params: ViewerParams | None = None)

   Interactive landmark-based image registrator using a Napari viewer.

   Place matching point pairs on the ``landmarks_fixed`` and
   ``landmarks_moving`` layers, then close the viewer to trigger transform
   estimation and resampling of the moving image onto the fixed grid.

   :param fixed_data: Reference image. The moving image will be registered onto this grid.
   :type fixed_data: np.ndarray
   :param moving_data: Moving image to be registered.
   :type moving_data: np.ndarray
   :param fixed_spacing: Pixel pitch of the fixed image (row, col) in physical units.
   :type fixed_spacing: tuple[float, float]
   :param moving_spacing: Pixel pitch of the moving image (row, col) in physical units.
   :type moving_spacing: tuple[float, float]
   :param transform_type: Type of spatial transform to estimate. Default is ``"affine"``.
   :type transform_type: {"affine", "rigid", "similarity"}, optional
   :param fixed_channel_axis: Channel axis index in ``fixed_data``, or None for single-channel.
   :type fixed_channel_axis: int, optional
   :param moving_channel_axis: Channel axis index in ``moving_data``, or None for single-channel.
   :type moving_channel_axis: int, optional
   :param viewer_params: Visual parameters for the Napari viewer. If None, uses
                         :class:`ViewerParams` defaults.
   :type viewer_params: ViewerParams, optional

   .. attribute:: fixed_image

      Fixed image converted to SimpleITK format (for internal use).

      :type: sitk.Image

   .. attribute:: transform

      Estimated spatial transform. Populated after calling :meth:`run`.

      :type: sitk.Transform

   .. attribute:: resampled_data

      Registered moving image. Populated after calling :meth:`run`.

      :type: np.ndarray

   .. seealso::

      :py:obj:`ViewerParams`
          Visual settings for the Napari viewer.

   .. rubric:: Examples

   Register a two-photon microscopy image to an SEM image:

   .. code-block:: python

       from microcorrelate.napari import NapariRegistrator

       registrator = NapariRegistrator(
           fixed_data=sem_image,
           moving_data=tpef_image,
           fixed_spacing=(0.15, 0.15),
           moving_spacing=(1.3, 1.3),
           transform_type='affine'
       )

       # Opens napari viewer for interactive landmark placement
       registrator.run()

       # After closing viewer, access results
       registered_image = registrator.resampled_data
       transform = registrator.transform

   Visualize the registration result:

   .. code-block:: python

       # After running registration
       registrator.show_registered()


   .. py:method:: register_image(moving_array: numpy.ndarray, moving_spacing: tuple[float, float], moving_channel_axis: int | None = None, default_value: float = 0.0) -> numpy.ndarray

      Apply transform and resample moving image onto fixed image grid.

      :param moving_array: Moving image array.
      :type moving_array: np.ndarray
      :param moving_spacing: Moving image pixel pitch (row, col).
      :type moving_spacing: Tuple[float, float]
      :param moving_channel_axis: Index of the channel axis of the moving image, if present. If None, the
                                  image is treated as single channel.
      :type moving_channel_axis: int | None
      :param default_value: Fill value for regions outside moving image bounds.
      :type default_value: float

      :returns: Registered image on fixed image grid.
      :rtype: np.ndarray



   .. py:method:: run(verbose=False) -> None

      Open a Napari viewer for interactive landmark placement and run registration.

      Place matching point pairs on the ``landmarks_fixed`` and
      ``landmarks_moving`` layers, then close the viewer window to trigger
      transform estimation and resampling of the moving image.

      :param verbose: If True, print progress messages. Default is False.
      :type verbose: bool

      :raises ValueError: If landmark counts don't match or fewer than 3 points provided.



   .. py:method:: show_registered()

      Show the resampled image overlaid to the fixed image



.. py:class:: ViewerParams

   Visual parameters for the :class:`NapariRegistrator` viewer.

   .. attribute:: fixed_color

      Colormap name for the fixed image layer. Default is ``"green"``.

      :type: str

   .. attribute:: moving_color

      Colormap name for the moving image layer. Default is ``"magenta"``.

      :type: str

   .. attribute:: pts_size

      Size of landmark points in data units. Default is 10.0.

      :type: float

   .. attribute:: pts_border_width

      Relative border width of landmark points (0-1). Default is 0.2.

      :type: float

   .. attribute:: pts_border_color

      Border color of landmark points. Default is ``"white"``.

      :type: str

   .. attribute:: text_color

      Color of the point index labels. Default is ``"white"``.

      :type: str

   .. attribute:: text_size

      Font size of the point index labels. Default is 12.

      :type: int

   .. attribute:: text_anchor

      Anchor position for the point index labels. Default is ``"upper_right"``.

      :type: str