itk_dreg.register

Module Contents

Classes

RegistrationScheduleResult

Encapsulate the results from registration schedule generation prior to actually running image registration.

Functions

register_images

Register blocks of an input image.

iterate_block_info

Return an iterator over chunks in the input array with metadata.

register_subimage

Callback to register one moving block to a fixed image subregion.

compose_block_status_output

Compose status codes from pairwise registration into an ND array.

compose_output

Helper method to compose registration result output.

Data

logger

worker_logger

Entry point for ITK-DReg multiresolution registration framework.

API

itk_dreg.register.logger

‘getLogger(…)’

itk_dreg.register.worker_logger

‘getLogger(…)’

Entry point for ITK-DReg multiresolution registration framework.

class itk_dreg.register.RegistrationScheduleResult

Encapsulate the results from registration schedule generation prior to actually running image registration.

registration_result: dask.delayed.Delayed

None

The dask.delayed callable object to prompt registration.

fixed_da: dask.array.Array

None

The lazy dask array representation of the fixed image voxel buffer, subdivided into subimage “chunks” over which pairwise registration tasks are scheduled.

The fixed image dask array representation is used only for scheduling purposes, i.e. determining the number and size of subimages to register. Fixed subimage voxel buffers are loaded independently at registration task time using the itk.ImageFileReader construction mechanism.

itk_dreg.register.register_images(fixed_reader_ctor: itk_dreg.base.registration_interface.ConstructReaderMethod, moving_reader_ctor: itk_dreg.base.registration_interface.ConstructReaderMethod, block_registration_method: itk_dreg.base.registration_interface.BlockPairRegistrationMethod, reduce_method: itk_dreg.base.registration_interface.ReduceResultsMethod, initial_transform: itk.Transform, fixed_chunk_size: Optional[List[int]], overlap_factors: Optional[List[float]] = None, debug_iter: Optional[Iterator[bool]] = None, **kwargs) → itk_dreg.base.image_block_interface.RegistrationResult

Register blocks of an input image.

This is the main entry point into itk-dreg registration infrastructure.

Parameters:

  • fixed_reader_ctor – A callable method to create an unbuffered itk.ImageFileReader to retrieve the fixed image from local or remote storage. See itk_dreg.base.registration_interface for more details.

  • moving_reader_ctor – A callable method to create an unbuffered itk.ImageFileReader to retrieve the moving image from local or remote storage. See itk_dreg.base.registration_interface for more details.

  • block_registration_method – A callable method to register a fixed and a moving subimage together. See itk_dreg.base.registration_interface for more details.

  • reduce_method – A callable method to compose results from multiple subimage pairwise registration computations into a single itk.Transform representation that is valid across the fixed image domain. See itk_dreg.base.registration_interface for more details.

  • initial_transform – The initial transform to map from fixed image to moving image space. Use an itk.CompositeTransform to compose transforms from previous registration stages.

  • fixed_chunk_size – The desired size of each fixed subimage to register. Used to subdivide the fixed image into subimage registration tasks. Subdivision schedule may be viewed on the result.fixed_da output. See overlap_factors to additionally configure subimage size.

  • overlap_factors – The desired overlap along each subimage axis in NumPy access order. In practice the actual voxel overlap is split evenly along each image edge such that the overlap factor represents total overlap length along each axis. For instance, running with fixed_chunk_size==[100,100,100] and overlap_factors==[0.1,0.1,0.1] would result in pairwise registration with fixed subimages of approximately [110,110,110] voxels, where the input buffered region is enlarged to include 5 voxels in either side of each axis. An overlap that would cause the buffered region to extend outside the largest available image region is discarded by cropping to the available region.

Returns:

A RegistrationResult instance containing the following:

  1. An unbuffered dask.array.Array representing the registration schedule according to fixed image subdivision into chunks;

  2. A dask.delayed result representing the registration task graph. result.registration_result may be visualized, initiated locally with .compute(), or deferred to a cluster for computation with the dask.distributed library.

itk_dreg.register.iterate_block_info(arr: dask.array) → Iterator[itk_dreg.base.image_block_interface.BlockInfo]

Return an iterator over chunks in the input array with metadata.

Parameters:

arr – The input dask array to iterate over by chunks. The underlying buffer is not directly interrogated, meaning a lazy or unbuffered representation is acceptable for iteration.

Returns:

An interator interface for the input array. Each iteration yields a new array chunk specifier.

itk_dreg.register.register_subimage(fixed_reader_ctor: itk_dreg.base.registration_interface.ConstructReaderMethod, moving_reader_ctor: itk_dreg.base.registration_interface.ConstructReaderMethod, block_registration_method: itk_dreg.base.registration_interface.BlockPairRegistrationMethod, block_info: itk_dreg.base.image_block_interface.BlockInfo, initial_transform: itk.Transform, overlap_factors: Optional[List[float]] = None, default_result: Optional[itk_dreg.base.image_block_interface.BlockPairRegistrationResult] = None, **kwargs) → itk_dreg.base.image_block_interface.BlockPairRegistrationResult

Callback to register one moving block to a fixed image subregion.

register_subimage fetches voxel data representing initialized, physically aligned image subregions and then calls into a provided registration callback for the actual registration process.

Typically called indirectly via register_images.

Parameters:

  • fixed_reader_ctor – A callable method to create an unbuffered itk.ImageFileReader to retrieve the fixed image from local or remote storage. See itk_dreg.base.registration_interface for more details.

  • moving_reader_ctor – A callable method to create an unbuffered itk.ImageFileReader to retrieve the moving image from local or remote storage. See itk_dreg.base.registration_interface for more details.

  • block_registration_method – A callable method to register a fixed and a moving subimage together. See itk_dreg.base.registration_interface for more details.

  • block_info – Specifies the position and enumeration of the subvoxel grid to target for registration within the fixed image.

  • initial_transform – The initial transform to map from fixed image to moving image space.

  • overlap_factors – The desired overlap along each subimage axis in NumPy access order. In practice the actual voxel overlap is split evenly along each image edge such that the overlap factor represents total overlap length along each axis.

  • default_result – The default result to return in the event that subimage registration fails.

Returns:

The result of subimage-to-subimage registration.

itk_dreg.register.compose_block_status_output(blocks_shape: List[int], block_loc_list: Iterator[itk_dreg.base.image_block_interface.BlockInfo], results: List[itk_dreg.base.image_block_interface.BlockPairRegistrationResult]) → numpy.typing.ArrayLike

Compose status codes from pairwise registration into an ND array.

Typically called indirectly via register_images.

Parameters:

  • blocks_shape` – The fixed image subdivision into blocks in NumPy order. For instance, a 10x10x10 image subdivided into chunks of size 5x10x10 would have blocks_shape==(2,1,1).

  • block_loc_list – Iterable providing ordered traversal through fixed image blocks after subdivision.

  • results – Iterable providing ordered traversal through registration results corresponding to the order of block_loc_list.

Returns:

An array with shape block_shape where each voxel reflects the registration status code result from the corresponding block.

itk_dreg.register.compose_output(reduced_transform_result: itk_dreg.base.image_block_interface.RegistrationTransformResult, status: numpy.typing.ArrayLike)

Helper method to compose registration result output.

Parameters:

  • composed_transform_result – The reduced result of subimage registration computations.

  • status – The composed ND array of registration status codes per block in NumPy access order.