clearex.registration.nonlinear

Functions

inspect_warp_transform(image_path, ...)

Inspect a warp (displacement) transform and summarize displacements inside an image mask.

register_image(moving_image, fixed_image[, ...])

Linear Image Registration.

transform_image(moving_image, fixed_image, ...)

Use a pre-existing warp transform to transform on a naive image to the coordinate space of the fixed_image.
clearex.registration.nonlinear.register_image(moving_image, fixed_image, moving_mask=None, fixed_mask=None, registration_type='SyNOnly', accuracy='high', verbose=False)

Linear Image Registration.

Perform nonlinear image registration between the moving image and the fixed image. Registration is by default performed with Symmetric Normalization.

Parameters:

  • moving_image (ants.core.ants_image.ANTsImage | np.ndarray) – The moving image.

  • fixed_image (ants.core.ants_image.ANTsImage | np.ndarray) – The image which the moving_image will be registered to. It remains fixed.

  • moving_mask (ants.core.ants_image.ANTsImage | None) – An optional mask for the moving image to limit registration to a region of interest.

  • fixed_mask (ants.core.ants_image.ANTsImage | None) – An optional mask for the fixed image to limit registration to a region of interest.

  • registration_type (str) – The type of registration method to use. Options include Elastic, SyN, SyNOnly. Default is SyNOnly.

  • accuracy (str) – Controls the number of registration iterations. Options are “high” (100, 70, 50 iterations), “low” (5, 5, 5 iterations), or “dry run” (1, 1, 1 iterations). Default is “high”.

  • verbose (bool) – The verbosity of the registration routine, showing iteration index, duration, registration error, etc.

Returns:

  • transformed_image (ants.core.ants_image.ANTsImage) – The registered image, moved to the coordinate space of the fixed image.

  • transformed_mask (ants.core.ants_image.ANTsImage | None) – The registered mask, moved to the coordinate space of the fixed image.

  • transform (ants.core.ants_transform.ANTsTransform) – The nonlinear transform used in the transformation of the transformed_image.

Raises:

ValueError – If the fixed and moving images do not have the same number of dimensions, or if an unsupported registration type is specified.

Return type:

tuple[_install_ants_stub.<locals>.ANTsImage, _install_ants_stub.<locals>.ANTsTransform]

References

https://antspy.readthedocs.io/en/latest/registration.html

clearex.registration.nonlinear.transform_image(moving_image, fixed_image, transformed_image)

Use a pre-existing warp transform to transform on a naive image to the coordinate space of the fixed_image. Performs histogram matching to the original.

Parameters:

  • moving_image (ants.core.ants_image.ANTsImage) – The image that will be transformed.

  • fixed_image (ants.core.ants_image.ANTsImage) – The stationary image.

  • transformed_image (ants.core.ants_image.ANTsImage) – The previously registered image, which contains a reference to the warp transform.

Returns:

registered_image – The registered image.

Return type:

ants.core.ants_image.ANTsImage

clearex.registration.nonlinear.inspect_warp_transform(image_path, transform_path)

Inspect a warp (displacement) transform and summarize displacements inside an image mask.

Parameters:

  • image_path (str) – Path to the registered image file. The image is read with tifffile.imread and converted to an ANTs image for mask extraction.

  • transform_path (str) – Path to the warp/displacement field image. This is read with ants.image_read and expected to be a vector image with one component per spatial dimension.

Returns:

stats – Dictionary with summary statistics of the displacement magnitude (within the image mask): - mean (float): mean displacement magnitude - min (float): minimum displacement magnitude - std (float): standard deviation of displacement magnitude - max (float): maximum displacement magnitude - n_vox (int): number of voxels included in the mask

Return type:

dict

Raises:

ValueError – If the warp array shape is not compatible with the expected number of dimensions (i.e. components not on the last axis or first axis).

Notes

The function uses ANTs for reading the warp (to preserve vector field semantics) and for creating a binary mask from the provided image. The image is expected to be readable by tifffile.