itk_dreg.base.registration_interface¶

Module Contents¶

Classes¶

ConstructReaderMethod

A method that generates a new itk.ImageFileReader for image registration.

BlockPairRegistrationMethod

A method that registers two spatially located image blocks together.

ReduceResultsMethod

A method that reduces a sparse collection of pairwise block registration results to yield a generalized fixed-to-moving transform.

API¶

class itk_dreg.base.registration_interface.ConstructReaderMethod¶

Bases: abc.ABC

A method that generates a new itk.ImageFileReader for image registration.

ITK provides the itk.ImageFileReader mechanism to retrieve all or part of a spatial image from a provided local or remote image source. itk-dreg registration infrastructure attempts to stream image subregions into memory at runtime in order to perform block-based pairwise registration without ever loading an entire image into memory at once.

Extend this class to customize the image reading step for cases such as to attach domain-specific metadata or to convert from a reference type not supported by ITK by default.

The resulting itk.ImageFileReader object MUST be initialized with metadata to represent the extent of the underlying data in voxel and physical space.

It is strongly recommended that the resulting itk.ImageFileReader is NOT initialized with underlying voxel data. Voxel regions should be lazily initialized by itk-dreg registration infrastructure to match block requested regions.

.. code-block:: python

ReaderSource = ConstructReaderMethodSubclass(...)
image_source = ReaderSource()
image = image_source.UpdateLargestPossibleRegion()
abstract __call__(**kwargs) → itk_dreg.base.itk_typing.ImageReaderType¶
class itk_dreg.base.registration_interface.BlockPairRegistrationMethod¶

Bases: abc.ABC

A method that registers two spatially located image blocks together.

fixed_subimage and moving_image inputs are itk.Image representations of block subregions within greater fixed and moving inputs.

Extend this class to implement custom registration method that plugs in to itk-dreg registration infrastructure.

abstract __call__(fixed_subimage: itk_dreg.base.itk_typing.ImageType, moving_subimage: itk_dreg.base.itk_typing.ImageType, initial_transform: itk_dreg.base.itk_typing.TransformType, block_info: itk_dreg.base.image_block_interface.BlockInfo, **kwargs) → itk_dreg.base.image_block_interface.BlockPairRegistrationResult¶

Run image-to-image pairwise registration.

Parameters:

  • fixed_subimage – The reference fixed subimage. fixed_subimage.RequestedRegion reflects the requested subregion corresponding to the scheduled dask array chunk. The initial fixed_subimage.BufferedRegion includes the requested region and possibly an extra padding factor introduced before fetching fixed image voxel data.

  • moving_subimage – The moving subimage to be registered onto fixed image space. moving_subimage.RequestedRegion reflects the requested subregion corresponding to the approximate physical bounds of fixed_subimage.RequestedRegion after initialization with initial_transform. The initial moving_subimage.BufferedRegion includes the requested region and possibly an extra padding factor introduced before fetching fixed image voxel data.

  • initial_transform – The forward transform representing an initial alignment mapping from fixed to moving image space.

Returns:

The result of block pairwise registration, including a status code indicating whether registration succeeded, a forward transform to run after the initial transform, the domain over which the forward transform is considered valid, and an optional inverse transform. May be extended with additional implementation-specific information.

class itk_dreg.base.registration_interface.ReduceResultsMethod¶

Bases: abc.ABC

A method that reduces a sparse collection of pairwise block registration results to yield a generalized fixed-to-moving transform.

Extend this class to implement a custom method mapping block results to a general transform.

Possible implementations could include methods for finding global consensus among results, combination methods to yield a piecewise transform, or patchwise methods to normalize among bounded transform domains.

abstract __call__(block_results: Iterable[itk_dreg.base.image_block_interface.LocatedBlockResult], fixed_reader_ctor: itk_dreg.base.registration_interface.ConstructReaderMethod, initial_transform: itk.Transform, **kwargs) → itk_dreg.base.image_block_interface.RegistrationTransformResult¶
Parameters:

  • block_results – An iterable collection of subimages in fixed space and the corresponding registration result for the given subimage. Subimages are not buffered and represent the subdomains within the original fixed image space prior to initial transform application.

  • fixed_reader_ctor – Method to create an image reader to stream part or all of the fixed image.

  • initial_transform – Initial forward transform used in registration. The forward transform maps from the fixed to moving image.