`itk_dreg.block.convert`¶

General ITK image utilities for converting between voxel and physical space specifiers.

Migrated from https://github.com/AllenNeuralDynamics/aind-ccf-alignment-experiments

Module Contents¶

Functions¶

`arr_to_continuous_index`	Convert Python array-like representation of a continuous index into an `itk.ContinuousIndex` representation.
`estimate_bounding_box`	Estimate a 3D axis-aligned bounding box for a physical region with a transform applied.
`block_to_physical_size`	Convert from 3D voxel block size to corresponding size in physical space.
`physical_to_block_size`	Convert from physical size to corresponding discrete voxel size.
`block_to_physical_region`	Convert from a voxel region to a corresponding axis-aligned physical region.
`physical_to_block_region`	Convert from a physical region to a corresponding voxel block.
`block_to_image_region`	Convert from 2x3 bounds representation to `itk.ImageRegion` representation.
`image_to_block_region`	Convert from `itk.ImageRegion` to a 2x3 bounds representation.
`physical_to_image_region`	Convert from a physical region to an `itk.ImageRegion` representation.
`image_to_physical_region`	Convert from an `itk.ImageRegion` to a physical region representation.
`get_target_block_size`	Given a voxel region size in source image space, compute the corresponding voxel region size with physical alignment in target image space.
`get_target_block_region`	Given a voxel region in source image space, compute the corresponding voxel region with physical alignment in target image space.

API¶

itk_dreg.block.convert.arr_to_continuous_index(index: Union[List, numpy.typing.ArrayLike]) → itk.ContinuousIndex¶

Convert Python array-like representation of a continuous index into an itk.ContinuousIndex representation.

Workaround for conversion issue:

Traceback (most recent call last):
    File "<stdin>", line 1, in <module>
    File "C:\Users\tom.birdsong\Anaconda3\envs\venv-itk11\Lib\site-packages\itk\itkContinuousIndexPython.py", line 158, in __init__
        _itkContinuousIndexPython.itkContinuousIndexD3_swiginit(self, _itkContinuousIndexPython.new_itkContinuousIndexD3(*args))
                                                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ValueError: Expecting a sequence of int (or long)

Parameters:

arr – The list or array representing a continuous index. The list or array must be a one dimensional collection of floating point scalar values.

Returns:

An itk.ContinuousIndex object representing the index.

Raises:

ValueError – if the input does not represent a valid index
KeyError – if the input index length is not supported by itk.ContinuousIndex

itk_dreg.block.convert.estimate_bounding_box(physical_region: numpy.typing.ArrayLike, transform: itk.Transform) → numpy.typing.ArrayLike¶

Estimate a 3D axis-aligned bounding box for a physical region with a transform applied.

Returns two points representing axis-aligned bounds that contain the corners of the transformed region.

The resulting bounding box may not fully contain all transformed image points in the case that a deformable transform is applied. Also, an axis-aligned bounding box may not be a good representation of an image that is not aligned to physical axes. Use with care.

Parameters:

physical_region – A 2x3 voxel array representing axis-aligned inclusive upper and lower bounds in physical space.
transform – The transform to apply at bounding box vertices.

Returns:

A 2x3 voxel array representing axis-aligned inclusive upper and lower bounds in physical space after the transform is applied.

itk_dreg.block.convert.block_to_physical_size(block_size: numpy.typing.ArrayLike, ref_image: itk.Image, transform: Optional[itk.Transform] = None) → numpy.typing.ArrayLike¶

Convert from 3D voxel block size to corresponding size in physical space.

Naive transform approach assumes that both the input and output regions are constrained along x/y/z planes aligned at two point extremes. May not be suitable for deformable regions.

#TODO: Verify that we are handling the offset between voxel centers/edges correctly.

Parameters:

block_size – Size of each edge of a voxel block in ITK access order (I,J,K).
ref_image – The image to reference for voxel-to-physical-space conversion.
transform – The transform to apply to the physical bounds before returning.

Returns:

The corresponding size (X,Y,Z) in physical space.

itk_dreg.block.convert.physical_to_block_size(physical_size: numpy.typing.ArrayLike, ref_image: itk.Image) → numpy.typing.ArrayLike¶

Convert from physical size to corresponding discrete voxel size.

Parameters:

physical_size – Axis-aligned physical size (X,Y,Z).
ref_image – The image to reference for physical-to-voxel-space conversion.

Returns:

The discrete voxel size in ITK access order (I,J,K).

itk_dreg.block.convert.block_to_physical_region(block_region: numpy.typing.ArrayLike, ref_image: itk.Image, transform: Optional[itk.Transform] = None, estimate_bounding_box_method: Callable[[numpy.typing.ArrayLike, itk.Transform], numpy.typing.ArrayLike] = estimate_bounding_box) → numpy.typing.ArrayLike¶

Convert from a voxel region to a corresponding axis-aligned physical region.

Parameters:

block_region – a 2x3 voxel array representing axis-aligned [lower,upper) voxel bounds in ITK access order (I,J,K).
ref_image – The image to reference for voxel-to-physical-space conversion.
transform – The transform to apply to the physical bounds before returning.
estimate_bounding_box_method – The method to use to approximate an axis aligned bounding box. Used only if transform is provided.

Returns:

A 2x3 voxel array representing axis-aligned inclusive upper and lower bounds in physical space.

itk_dreg.block.convert.physical_to_block_region(physical_region: numpy.typing.ArrayLike, ref_image: itk.Image) → numpy.typing.ArrayLike¶

Convert from a physical region to a corresponding voxel block.

Parameters:

physical_region – A 2x3 voxel array representing axis-aligned inclusive upper and lower bounds in (X,Y,Z) physical space.
ref_image – The image to reference for voxel-to-physical-space conversion.

Returns:

a 2x3 voxel array representing axis-aligned [lower,upper) voxel bounds in ITK access order (I,J,K).

itk_dreg.block.convert.block_to_image_region(block_region: numpy.typing.ArrayLike) → itk.ImageRegion[3]¶

Convert from 2x3 bounds representation to itk.ImageRegion representation.

Parameters:: block_region – a 2x3 voxel array representing axis-aligned [lower,upper) voxel bounds in ITK access order (I,J,K).
Returns:: An itk.ImageRegion representation of the voxel region.

itk_dreg.block.convert.image_to_block_region(image_region: itk.ImageRegion[3]) → numpy.typing.ArrayLike¶

Convert from itk.ImageRegion to a 2x3 bounds representation.

Parameters:: image_region – An itk.ImageRegion representation of the voxel region.
Returns:: A 2x3 voxel array representing axis-aligned [lower,upper) voxel bounds in ITK access order (I,J,K).

itk_dreg.block.convert.physical_to_image_region(physical_region: numpy.typing.ArrayLike, ref_image: itk.Image) → itk.ImageRegion[3]¶

Convert from a physical region to an itk.ImageRegion representation.

Parameters:: physical_region – A 2x3 voxel array representing axis-aligned inclusive upper and lower bounds in (X,Y,Z) physical space.
Returns:: An itk.ImageRegion representation of the voxel region.

itk_dreg.block.convert.image_to_physical_region(image_region: numpy.typing.ArrayLike, ref_image: itk.Image, src_transform: Optional[itk.Transform] = None) → itk.ImageRegion[3]¶

Convert from an itk.ImageRegion to a physical region representation.

Parameters:

image_region – An itk.ImageRegion representation of the voxel region.
ref_image – The image to reference for voxel-to-physical-space conversion.
src_transform – The transform to apply to the converted physical region.

Returns:

A 2x3 voxel array representing axis-aligned inclusive upper and lower bounds in (X,Y,Z) physical space.

itk_dreg.block.convert.get_target_block_size(block_size: numpy.typing.ArrayLike, src_image: itk.Image, target_image: itk.Image) → numpy.typing.ArrayLike¶

Given a voxel region size in source image space, compute the corresponding voxel region size with physical alignment in target image space.

Parameters:

block_size – Size of each edge of a voxel block in ITK access order (I,J,K) in source image voxel space.
src_image – The source image to use as a reference to convert between the input block size and physical space.
target_image – The target image to use as a reference to convert between physical space and the output block size.

Returns:

Size of each edge of a voxel block in ITK access order (I,J,K) in target image voxel space.

itk_dreg.block.convert.get_target_block_region(block_region: numpy.typing.ArrayLike, src_image: itk.Image, target_image: itk.Image, src_transform: Optional[itk.Transform] = None, crop_to_target: bool = False) → numpy.typing.ArrayLike¶

Given a voxel region in source image space, compute the corresponding voxel region with physical alignment in target image space.

Parameters:

block_region – A 2x3 voxel array representing axis-aligned [lower,upper) voxel bounds in ITK access order (I,J,K) in source image voxel space.
src_image – The source image to use as a reference to convert between the input block size and physical space.
target_image – The target image to use as a reference to convert between physical space and the output block size.
src_transform – A transform to apply to transform from source image physical space to target image physical space.
crop_to_target – Whether to crop the resulting voxel region in target image space so that the voxel region is guaranteed to lie either fully within or fully outside of the target image largest possible voxel region.

Returns:

A 2x3 voxel array representing axis-aligned [lower,upper) voxel bounds in ITK access order (I,J,K) in target image voxel space.

itk_dreg.block.convert¶

Module Contents¶

Functions¶

API¶

`itk_dreg.block.convert`¶