Registration#

Deformable Image Registration#

platipy.imaging.registration.deformable.bspline_registration(fixed_image, moving_image, fixed_structure=False, moving_structure=False, resolution_staging=[8, 4, 2], smooth_sigmas=[4, 2, 1], sampling_rate=0.1, optimiser='LBFGS', metric='mean_squares', initial_grid_spacing=64, grid_scale_factors=[1, 2, 4], interp_order=3, default_value=-1000, number_of_iterations=20, isotropic_resample=False, initial_isotropic_size=1, number_of_histogram_bins_mi=30, verbose=False, ncores=8)#

B-Spline image registration using ITK

IMPORTANT - THIS IS UNDER ACTIVE DEVELOPMENT

Parameters:

fixed_image ([SimpleITK.Image]) – The fixed (target/primary) image.
moving_image ([SimpleITK.Image]) – The moving (secondary) image.
fixed_structure (bool, optional) – If defined, a binary SimpleITK.Image used to mask metric evaluation for the moving image. Defaults to False.
moving_structure (bool, optional) – If defined, a binary SimpleITK.Image used to mask metric evaluation for the fixed image. Defaults to False.
resolution_staging (list, optional) – The multi-resolution downsampling factors. Defaults to [8, 4, 2].
smooth_sigmas (list, optional) – The multi-resolution smoothing kernel scale (Gaussian). Defaults to [4, 2, 1].
sampling_rate (float, optional) – The fraction of voxels sampled during each iteration. Defaults to 0.1.
optimiser (str, optional) –
The optimiser algorithm used for image registration. Available options:
- LBFSGS (limited-memory Broyden–Fletcher–Goldfarb–Shanno (bounded).)
- LBFSG (limited-memory Broyden–Fletcher–Goldfarb–Shanno (unbounded).)
- CGLS (conjugate gradient line search)
- gradient_descent
- gradient_descent_line_search
Defaults to “LBFGS”.
metric (str, optional) –
The metric to be optimised during image registration. Available options:
- correlation
- mean_squares
- demons
- mutual_information (used with parameter number_of_histogram_bins_mi)
Defaults to “mean_squares”.
initial_grid_spacing (int, optional) – Grid spacing of lower resolution stage (in mm). Defaults to 64.
grid_scale_factors (list, optional) – Factors to determine grid spacing at each multiresolution stage. Defaults to [1, 2, 4].
interp_order (int, optional) – Interpolation order of final resampling. Defaults to 3 (cubic).
default_value (int, optional) – Default image value. Defaults to -1000.
number_of_iterations (int, optional) – Number of iterations at each resolution stage. Defaults to 20.
isotropic_resample (bool, optional) – Flag whether to resample to isotropic resampling prior to registration. Defaults to False.
initial_isotropic_size (int, optional) – Voxel size (in mm) of resampled isotropic image (if used). Defaults to 1.
number_of_histogram_bins_mi (int, optional) – Number of histogram bins used when calculating mutual information. Defaults to 30.
verbose (bool, optional) – Print image registration process information. Defaults to False.
ncores (int, optional) – Number of CPU cores used. Defaults to 8.

Returns:

The registered moving (secondary) image. [SimleITK.Transform]: The linear transformation.

Return type:

[SimpleITK.Image]

Notes

smooth_sigmas are relative to resolution staging
e.g. for image spacing of 1x1x1 mm^3, with smooth sigma=2 and resolution_staging=4, the scale of the Gaussian filter would be 2x4 = 8mm (i.e. 8x8x8 mm^3)

platipy.imaging.registration.deformable.fast_symmetric_forces_demons_registration(fixed_image, moving_image, resolution_staging=[8, 4, 1], iteration_staging=[10, 10, 10], isotropic_resample=False, initial_displacement_field=None, regularisation_kernel_mm=1.5, smoothing_sigma_factor=1, smoothing_sigmas=False, default_value=None, ncores=1, interp_order=2, verbose=False)#

Deformable image propagation using Fast Symmetric-Forces Demons

Args

fixed_image (sitk.Image) : the fixed image moving_image (sitk.Image) : the moving image, to be deformable registered (must be in

the same image space)

resolution_staging (list[int]) : down-sampling factor for each resolution level iteration_staging (list[int]) : number of iterations for each resolution level isotropic_resample (bool) : flag to request isotropic resampling of images, in which

case resolution_staging is used to define voxel size (mm) per level

initial_displacement_field (sitk.Image) : Initial displacement field to use regularisation_kernel_scale (float) : Relative scale (var/voxel size) of the regularisation kernel (Gaussian) ncores (int) : number of processing cores to use smoothing_sigma_factor (float) : the relative width of the Gaussian smoothing kernel interp_order (int) : the interpolation order

1 = Nearest neighbour 2 = Bi-linear splines 3 = B-Spline (cubic)

default_value (float) : Default voxel value. Defaults to 0 unless image is CT-like.

Returns

registered_image (sitk.Image) : the registered moving image output_transform : the displacement field transform [optional] deformation_field

platipy.imaging.registration.deformable.multiscale_demons(registration_algorithm, fixed_image, moving_image, initial_transform=None, initial_displacement_field=None, isotropic_resample=None, resolution_staging=None, smoothing_sigmas=None, iteration_staging=None, interp_order=2)#

Run the given registration algorithm in a multiscale fashion. The original scale should not be given as input as the original images are implicitly incorporated as the base of the pyramid. :param registration_algorithm: Any registration algorithm that has an Execute(fixed_image,

moving_image, displacement_field_image) method.

Parameters:

fixed_image – Resulting transformation maps points from this image’s spatial domain to the moving image spatial domain.
moving_image – Resulting transformation maps points from the fixed_image’s spatial domain to this image’s spatial domain.
initial_transform – Any SimpleITK transform, used to initialize the displacement field.
initial_displacement_field – Initial displacement field, if this is provided initial_transform will be ignored
shrink_factors – Shrink factors relative to the original image’s size.
smoothing_sigmas – Amount of smoothing which is done prior to resmapling the image using the given shrink factor. These are in physical (image spacing) units.

Returns:

SimpleITK.DisplacementFieldTransform [Optional] Displacemment (vector) field

Rigid Registration#

platipy.imaging.registration.linear.alignment_registration(fixed_image, moving_image, moments=True)#

A simple registration procedure that can align images in a single step. Uses the image centres-of-mass (and optionally second moments) to estimate the shift (and rotation) needed for alignment.

Parameters:

fixed_image ([SimpleITK.Image]) – The fixed (target/primary) image.
moving_image ([SimpleITK.Image]) – The moving (secondary) image.
moments (bool, optional) – Option to align images using the second moment. Defaults to True.

Returns:

The registered moving (secondary) image. [SimleITK.Transform]: The linear transformation.

Return type:

[SimpleITK.Image]

platipy.imaging.registration.linear.linear_registration(fixed_image, moving_image, fixed_structure=None, moving_structure=None, reg_method='similarity', metric='mean_squares', optimiser='gradient_descent', shrink_factors=[8, 2, 1], smooth_sigmas=[4, 2, 0], sampling_rate=0.25, final_interp=2, number_of_iterations=50, default_value=None, verbose=False)#

Initial linear registration between two images. The images are not required to be in the same space. There are several transforms available, with options for the metric and optimiser to be used. Note the default_value, which should be set to match the image modality.

Parameters:

fixed_image ([SimpleITK.Image]) – The fixed (target/primary) image.
moving_image ([SimpleITK.Image]) – The moving (secondary) image.
fixed_structure (bool, optional) – If defined, a binary SimpleITK.Image used to mask metric evaluation for the moving image. Defaults to False.
moving_structure (bool, optional) – If defined, a binary SimpleITK.Image used to mask metric evaluation for the fixed image. Defaults to False.
reg_method (str, optional) –
The linear transformtation model to be used for image registration. Available options:
- translation
- rigid
- similarity
- affine
- scale
- scaleversor
- scaleskewversor
Defaults to “Similarity”.
metric (str, optional) –
The metric to be optimised during image registration. Available options:
- correlation
- mean_squares
- mattes_mi
- joint_hist_mi
Defaults to “mean_squares”.
optimiser (str, optional) –
The optimiser algorithm used for image registration. Available options:
- lbfgsb (limited-memory Broyden–Fletcher–Goldfarb–Shanno (bounded).)
- gradient_descent
- gradient_descent_line_search
Defaults to “gradient_descent”.
shrink_factors (list, optional) – The multi-resolution downsampling factors. Defaults to [8, 2, 1].
smooth_sigmas (list, optional) – The multi-resolution smoothing kernel scale (Gaussian). Defaults to [4, 2, 0].
sampling_rate (float, optional) – The fraction of voxels sampled during each iteration. Defaults to 0.25.
ants_radius (int, optional) – Used is the metric is set as “ants_radius”. Defaults to 3.
final_interp (int, optional) – The final interpolation order. Defaults to 2 (linear).
number_of_iterations (int, optional) – Number of iterations in each multi-resolution step. Defaults to 50.
default_value (int, optional) – Default voxel value. Defaults to 0 unless image is CT-like.
verbose (bool, optional) – Print image registration process information. Defaults to False.

Returns:

The registered moving (secondary) image. [SimleITK.Transform]: The linear transformation.

Return type:

[SimpleITK.Image]

Registration Utils#

platipy.imaging.registration.utils.apply_deformable_transform(input_image, transform, is_structure=False, default_value=0, interpolator=1)#

Helper function for applying deformable transforms.

Args

input_image (SimpleITK.Image): The image, to which the transform is applied reference_image (SimpleITK.Image): The image will be resampled into this reference space. transform (SimpleITK.Transform): The transformation is_structure (bool): Will set appropriate parameters for transforming labels/structures. default_value: Default (background) value. Defaults to 0. interpolator (int, optional): The interpolation order.

Available options:

SimpleITK.sitkNearestNeighbor

SimpleITK.sitkLinear

SimpleITK.sitkBSpline

Defaults to SimpleITK.sitkNearestNeighbor

Returns

(SimpleITK.Image): the transformed image

platipy.imaging.registration.utils.apply_linear_transform(input_image, reference_image, transform, is_structure=False, default_value=0, interpolator=1)#

Helper function for applying linear transforms.

Args

Available options:

SimpleITK.sitkNearestNeighbor

SimpleITK.sitkLinear

SimpleITK.sitkBSpline

Defaults to SimpleITK.sitkNearestNeighbor

Returns

(SimpleITK.Image): the transformed image

platipy.imaging.registration.utils.apply_transform(input_image, reference_image=None, transform=None, default_value=0, interpolator=1)#

Transform a volume of structure with the given deformation field.

Args

input_image (SimpleITK.Image): The image, to which the transform is applied reference_image (SimpleITK.Image): The image will be resampled into this reference space. transform (SimpleITK.Transform): The transformation default_value: Default (background) value. Defaults to 0. interpolator (int, optional): The interpolation order.

Available options:

SimpleITK.sitkNearestNeighbor

SimpleITK.sitkLinear

SimpleITK.sitkBSpline

Defaults to SimpleITK.sitkNearestNeighbor

Returns

(SimpleITK.Image): the transformed image

platipy.imaging.registration.utils.control_point_spacing_distance_to_number(image, grid_spacing)#: Convert grid spacing specified in distance to number of control points

platipy.imaging.registration.utils.convert_mask_to_distance_map(mask, squared_distance=False, normalise=False)#

Generate a distance map from a binary label.

Parameters:

mask ([SimpleITK.Image]) – A binary label.
squared_distance (bool, optional) – Option to use the squared distance. Defaults to False.
normalise (bool, optional) – Normalise output to [0,1]. Defaults to False.

Returns:

The distance map as an image.

Return type:

[SimpleITK.Image]

platipy.imaging.registration.utils.convert_mask_to_reg_structure(mask, expansion=(0, 0, 0), scale=<function <lambda>>)#

Generate a mask-like image to make structure-guided registration more realistic via internal deformation within a binary mask.

Parameters:

mask ([SimpleITK.Image]) – The binary label.
expansion (int, optional) – For improved smoothness on the surface (particularly complex structures) it will often help to use some binary dilation. This parameter defines the expansion in mm. Defaults to 1.
scale ([function], optional) – Defines scaling to the distance map. For example: lambda x:sitk.Log(x). Defaults to lambda x:x.

Returns:

[description]

Return type:

[SimpleITK.Image]

platipy.imaging.registration.utils.deformable_registration_command_iteration(method)#: Utility function to print information during demons registration

platipy.imaging.registration.utils.registration_command_iteration(method)#: Utility function to print information during (rigid, similarity, translation, B-splines) registration

platipy.imaging.registration.utils.smooth_and_resample(image, isotropic_voxel_size_mm=None, shrink_factor=None, smoothing_sigma=None, interpolator=2)#

Parameters:

image (SimpleITK.Image) – The image we want to resample.
isotropic_voxel_size_mm (float | None) – New voxel size in millimetres
shrink_factor (list | float) – A number greater than one, such that the new image’s size is original_size/shrink_factor. Can also be specified independently for each dimension (sagittal, coronal, axial).
smoothing_sigma (list | float) – Scale for Gaussian smoothing, this is in physical (image spacing) units, not pixels. Can also be specified independently for each dimension (sagittal, coronal, axial).

Returns:

Image which is a result of smoothing the input and then resampling it using the specified Gaussian kernel and shrink factor.

Return type:

SimpleITK.Image

platipy.imaging.registration.utils.stage_iteration(method)#: Utility function to print information during stage change in registration