itk_dreg.block.image¶

General ITK image utilities for mapping between voxel and physical spaces.

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

Module Contents¶

Functions¶

get_sample_bounds

Get the axis-aligned physical boundaries of the space sampled by the ITK image.

get_physical_midpoint

Estimate the physical midpoint of the image in physical space.

block_to_itk_image

Return an ITK image view into an array block.

physical_region_to_itk_image

Represent a physical region as an unallocated itk.Image object.

Data¶

logger

API¶

itk_dreg.block.image.logger¶

‘getLogger(…)’

itk_dreg.block.image.get_sample_bounds(image: itk.Image, transform: Optional[itk.Transform] = None)¶

Get the axis-aligned physical boundaries of the space sampled by the ITK image.

Each voxel in an ITK image is considered to be a sample of the spatial volume occupied by that voxel taken at the spatial center of the volume. The physical point returned at each discrete voxel coordinate is considered to be the physical location of the sample point. We adjust by half a voxel in each direction to get the bounds of the space sampled by the image.

Always returns the largest possible physical size of the image. Use itk_dreg.block.convert.image_to_physical_region to estimate the physical size of an image subregion such as a buffered or requested region.

Parameters:

  • image – The image for which bounds should be estimated.

  • transform – Transform to apply to the image sample bounds.

Returns:

A 2x3 voxel array representing axis-aligned inclusive upper and lower bounds in (X,Y,Z) physical space for the largest possible physical space sampled by the image.

itk_dreg.block.image.get_physical_midpoint(image: itk.Image, transform: Optional[itk.Transform] = None) → numpy.typing.ArrayLike¶

Estimate the physical midpoint of the image in physical space.

Parameters:

  • image – The image representing an axis-aligned sampling region in physical space.

  • transform – The transform to apply to the sampling region.

Returns:

Physical coordinate (X,Y,Z) representing the center of the (transformed) image sampling region.

itk_dreg.block.image.block_to_itk_image(data: numpy.typing.ArrayLike, start_index: numpy.typing.ArrayLike, reference_image: itk.Image) → itk.Image¶

Return an ITK image view into an array block.

Parameters:

  • data – The array block data.

  • start_index – The image index of the first voxel in the data array in ITK access order.

  • reference_image – Reference ITK image metadata for the output image view.

Returns:

An itk.Image view into the array block with updated metadata.

itk_dreg.block.image.physical_region_to_itk_image(physical_region: numpy.typing.ArrayLike, spacing: List[float], direction: Union[itk.Matrix, numpy.typing.ArrayLike], extend_beyond: bool = True, image_type: Optional[type[itk.Image]] = None) → itk.Image¶

Represent a physical region as an unallocated itk.Image object.

An itk.Image metadata object represents a mapping from continuous physical space with X,Y,Z axes to a discrete voxel space with I,J,K axes. This method initializes an itk.Image to sample a given three-dimensional space over a discrete voxel grid.

A procedure is developed as follows:

  1. Process the requested direction and spacing to get the step size in physical space corresponding to a step in any voxel direction;

  2. Subdivide the physical region into discrete steps;

  3. Align to the center of the region such that any over/underlap is symmetric on opposite sides of the grid;

  4. Compute the origin at the centerpoint of the 0th voxel;

  5. Compute the output voxel size according to the equation:

size = ((D * S) ^ -1) * (upper_bound - lower_bound)

The resulting image is a metadata representation of the relationship between spaces and has no pixel buffer allocation.

Parameters:

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

  • spacing – The desired output image spacing. Determines how to subdivide the physical region into voxels.

  • direction – The desired output image direction. Assumes that the input direction represents some 90 degree orientation mapping from I,J,K to X,Y,Z axes.

  • extend_beyond – In the event that the physical region cannot be exactly subdivided into discrete voxels along any given axis, determines whether the sampling region represented by the output image may extend beyond the input physical region to fully cover the input physical region with the output voxel grid. If True, the region sampled by the output itk.Image may extend beyond the input physical region by up to one voxel width at each edge. If False, the region sampled by the output itk.Image may fail to fully cover the input physical region and may lay in the interior of the region by up to one voxel width at each edge.

  • image_type – The type of itk.Image to construct.

Returns:

A new itk.Image constructed with metadata to subdivide the input physical region into a discrete voxel grid. The image is unbuffered and may be manually allocated after its return by calling image.Allocate().