kwneuro.reg
===========

.. py:module:: kwneuro.reg


Classes
-------

.. autoapisummary::

   kwneuro.reg.TransformResource


Functions
---------

.. autoapisummary::

   kwneuro.reg.register_volumes
   kwneuro.reg.register_dwi_to_structural


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

.. py:class:: TransformResource

   A wrapper for ANTs registration results that simplifies viewing and
   applying transforms. While the underlying transform files are always
   stored on-disk, they remain in a temporary directory until explicitly
   persisted via the save() method.


   .. py:property:: matrices
      :type: list[ants.ANTsTransform]


      Returns the affine transform if it exists.


   .. py:property:: warp_fields
      :type: list[kwneuro.resource.InMemoryVolumeResource]


      Returns the non-linear displacement field if it exists.


   .. py:method:: initialize_from_ants(ants_result: dict[str, list[str]]) -> TransformResource
      :staticmethod:


      Initializes a TransformResource from an ANTs registration result by
      wrapping references to the temporary transform files generated by ANTs.



   .. py:method:: apply(fixed: kwneuro.resource.VolumeResource, moving: kwneuro.resource.VolumeResource, invert: bool = False, interpolation: str = 'linear') -> kwneuro.resource.InMemoryVolumeResource

      Wrapper around ants.apply_transforms using this result.



   .. py:method:: save(output_dir: kwneuro.util.PathLike) -> TransformResource

      Copies the underlying ANTs transformation files to a permanent directory
      and returns a new TransformResource pointing to the saved locations



.. py:function:: register_volumes(fixed: kwneuro.resource.VolumeResource, moving: kwneuro.resource.VolumeResource, type_of_transform: str = 'SyN', mask: kwneuro.resource.VolumeResource | None = None, moving_mask: kwneuro.resource.VolumeResource | None = None) -> tuple[kwneuro.resource.InMemoryVolumeResource, TransformResource]

   Registers a moving volume to a fixed reference volume using ANTs.

   :param fixed: The reference volume.
   :param moving: The volume to be warped.
   :param type_of_transform: The transformation model (e.g., "SyN", "Rigid"). The full list of
                             supported transforms can be found in the ANTs documentation.
   :param mask: Optional mask for the fixed image space.
   :param moving_mask: Optional mask for the moving image space.

   :returns: A tuple containing the registered volume and the transform object.


.. py:function:: register_dwi_to_structural(dwi: kwneuro.dwi.Dwi, structural: kwneuro.structural.StructuralImage, type_of_transform: str = 'Rigid', dwi_mask: kwneuro.resource.VolumeResource | None = None, structural_mask: kwneuro.resource.VolumeResource | None = None) -> TransformResource

   Register a DWI (mean b0) to a structural (T1) image.

   Convenience wrapper around :func:`register_volumes`. The returned
   :class:`TransformResource` maps DWI space → T1 space. To warp T1-derived
   labels back into DWI space call
   ``transform.apply(..., invert=True, interpolation="genericLabel")``.
   See :meth:`TransformResource.apply` for details.

   :param dwi: The DWI to register. The mean b0 is used as the moving image.
   :param structural: The structural image used as the fixed reference.
   :param type_of_transform: The transformation model (e.g., "Rigid", "Affine", "SyN").
   :param dwi_mask: Optional brain mask in DWI space (used as the moving mask).
   :param structural_mask: Optional brain mask in structural space (used as the fixed mask).

   :returns: A :class:`TransformResource` mapping DWI space → structural space.