pirt.reg - The registration algorithms

The reg module implements the various registration algorithms.

Base registration classes

class pirt.AbstractRegistration(*images, makeFloat=True)

Base class for registration of 2 or more images. This class only provides a common interface for the user.

This base class can for example be inherited by registration classes that wrap an external registration algorithm, such as Elastix.

Also see pirt.BaseRegistration.

Implements:

  • progress, timer, and visualizer objects
  • properties to handle the mapping (forward or backward)
  • functionality to get and set parameters
  • basic functionality to get resulting deformations
  • functionality to show the result (2D only)
Parameters:
None
DeformationField

Depending on whether forward or backward mapping is used, returns the DeformationFieldForward or DeformationFieldBackward class.

DeformationGrid

Depending on whether forward or backward mapping is used, returns the DeformationGridForward or DeformationGridBackward class.

forward_mapping

Whether forward (True) or backward (False) mapping is to be used internally.

get_deform(i=0)

Get the DeformationField instance for image with index i. If groupwise registration was used, this deformation field maps image i to the mean shape.

get_final_deform(i=0, j=1, mapping=None)

Get the DeformationField instance that maps image with index i to the image with index j. If groupwise registration was used, the deform is a composition of deform ‘i’ with the inverse of deform ‘j’.

Parameters:
i : int

The source image

j : int

The target image

mapping : {‘forward’, ‘backward’, Deformation instance}

Whether the result should be a forward or backward deform. When specified here, the result can be calculated with less errors than for example using result.as_forward(). If a Deformation object is given, the mapping of that deform is used.
params

Get params structure (as a Parameters object).

progress

The progress object, can be used by the algorithm to indicate its progress.

register(verbose=1, fig=None)

Perform the registration process.

Parameters:
verbose : int

Verbosity level. 0 means silent, 1 means print some, 2 means print a lot.

fig : visvis figure or None

If given, will display the registration progress in the given figure.
classmethod register_and_get_object(*ims, **params)

Classmethod to register the given images with the given parameters, and return the resulting registration object (after the registration has been performed).

set_params(params=None, **kwargs)

Set any parameters. The parameters are updated with the given dict, Parameters object, and then with the parameters given via the keyword arguments.

Note that the parameter structure can also be accessed directly via the ‘params’ propery.

show_result(self, how=None, fig=None)

Convenience method to show the registration result. Only works for two dimensional data. Requires visvis.

timer

The timer object, can be used by the algorithm to measure the processing time of the different steps in the registration algorithm.

visualizer

The visualizer object, can be used by the algorithm to display the images as they are deformed during registration.

class pirt.BaseRegistration(*images)

Inherits from pirt.AbstractRegistration.

An abstract registration class that provides common functionality shared by almost all registration algorithms.

This class maintains an image pyramid for each image, implements methods to set the delta deform, and get the deformed image at a specified scale. Further, this class implements the high level aspect of the registration algorithm that iterates through scale space.

Parameters:
mapping : {‘forward’, ‘backward’}

Whether forward or backward mapping is used. Default forward.

combine_deforms : {‘compose’, ‘add’}

How deformations are combined. Default compose. While add is used in some (older) registration algorithms, it is a coarse approximation.

final_scale : scalar

The minimum scale used during the registration process. This is the scale at which the registration ends. Default 1.0. Because calculating differentials suffer from more errors as the scale decreases, the minimum value is limited at 0.5.

scale_levels : integer

The amount of scale levels to use during the registration. Each level represents a factor of two in scale. The default (4) works for most images, but for large images or large deformations a larger value can be used.

scale_sampling : scalar

The amount of iterations for each level (i.e. between each factor two in scale). What values are reasonable depends on the specific algorithm.

smooth_scale : bool

Whether a smooth scale space should be used (default) or the scale is reduced with a factor of two each scale_sampling iterations.
get_deformed_image(i, s=0)

Get the image i at scale s, deformed with its current deform. Mainly intended for the registration algorithms, but can be of interest during development/debugging.

class pirt.GDGRegistration(*images)

Inherits from pirt.BaseRegistration.

Generic Groupwise Diffeomorphic Registration. Abstract class that provides a generic way to perform diffeomorphic groupwise registration.

Parameters:
deform_wise : {‘groupwise’, ‘pairwise’}

Whether all images are deformed simultaneously, or only the first image is deformed. When registering more than 2 images, ‘groupwise’ registration should be used. Default ‘groupwise’.

injective : bool

Whether the injectivity constraint should be used. This value should only be set to False in specific (testing?) situation; the resulting deformations are only guaranteed to be diffeomorphic if injective=True.

frozenEdge : bool

Whether the deformation is set to zero at the edges. If True (default) the resulting deformation fields are fully diffeomorphic; no pixels are mapped from the inside to the outside nor vice versa.

final_grid_sampling : scalar

The grid sampling of the grid at the final level. During the registration process, the B-spine grid sampling scales along with the scale.

grid_sampling_factor : scalar between 0 and 1

To what extent the grid sampling scales with the scale. By making this value lower than 1, the grid is relatively fine at the the higher scales, allowing for more deformations. The default is 0.5. Note that setting this value to 1 when using ‘frozenedge’ can cause the image to be ‘stuck’ at higher scales.

deform_limit : scalar

If injective is True, the deformations at each iteration are constraint by a “magic” limit. By making this limit tighter (relative to the scale), the deformations stay in reasonable bounds. This feature helps a lot for convergence. Default value is 1.

Special classes

class pirt.NullRegistration(*images)

Inherits from pirt.AbstractRegistration.

A registration algorithm that does nothing. This can be usefull to test the result if no registration would be applied.

Parameters:
None

Demons registration

The demon’s algorithm is a simple yet often effective algorithm. We’ve improved upon the algorithm by making it diffeomorphic, greatly improving the realism of the produced deformations.

class pirt.OriginalDemonsRegistration(*images)

Inherits from pirt.BaseRegistration.

The original version of the Demons algorithm. Uses Gaussian diffusion to regularize the deformation field. This is the implementation as proposed by He Wang et al. in 2005 “Validation of an accelerated ‘demons’ algorithm for deformable image registration in radiation therapy”

See also pirt.DiffeomorphicDemonsRegistration.

The speed_factor and noise_factor parameters are specific to this algorithm. Other important parameters are also listed below.

Parameters:
speed_factor : scalar

The relative force of the transform. This one of the most important parameters to tune. Default 3.0.

noise_factor : scalar

The noise factor. Default 2.5.

final_scale : scalar

The minimum scale used during the registration process. This is the scale at which the registration ends. Default 1.0. Because calculating differentials suffer from more errors as the scale decreases, the minimum value is limited at 0.5.

scale_levels : integer

The amount of scale levels to use during the registration. Each level represents a factor of two in scale. The default (4) works for most images, but for large images or large deformations a larger value can be used.

scale_sampling : scalar

The amount of iterations for each level (i.e. between each factor two in scale). Values between 20 and 30 are reasonable in most situations. Default 25. Higher values yield better results in general. The speed of the algorithm scales linearly with this value.
class pirt.DiffeomorphicDemonsRegistration(*images)

Inherits from pirt.GDGRegistration.

A variant of the Demons algorithm that is diffeomorphic. Based on the generice diffeomorphic groupwise registration (GDGRegistration) method .

See also pirt.OriginalDemonsRegistration.

The speed_factor parameter is specific to this algorithm. The noise_factor works best set at 1.0, effectively disabling its use; it is made redundant by the B-spline based regularization. Other important parameters are also listed below.

Parameters:
speed_factor : scalar

The relative force of the transform. This one of the most important parameters to tune. Default 3.0.

mapping : {‘forward’, ‘backward’}

Whether forward or backward mapping is used. Default forward.

final_scale : scalar

The minimum scale used during the registration process. This is the scale at which the registration ends. Default 1.0. Because calculating differentials suffer from more errors as the scale decreases, the minimum value is limited at 0.5.

scale_levels : integer

The amount of scale levels to use during the registration. Each level represents a factor of two in scale. The default (4) works for most images, but for large images or large deformations a larger value can be used.

scale_sampling : scalar

The amount of iterations for each level (i.e. between each factor two in scale). Values between 20 and 30 are reasonable in most situations. Default 25. Higher values yield better results in general. The speed of the algorithm scales linearly with this value.

final_grid_sampling : scalar

The grid sampling of the grid at the final level. During the registration process, the B-spine grid sampling scales along with the scale. This parameter is usually best coupled to final_scale. (When increasing final scale, this value should often be increased accordingly.)

grid_sampling_factor : scalar between 0 and 1

To what extent the grid sampling scales with the scale. By making this value lower than 1, the grid is relatively fine at the the higher scales, allowing for more deformations. The default is 0.5. Note that setting this value to 1 when using ‘frozenedge’ can cause the image to be ‘stuck’ at higher scales.

Gravity registration

class pirt.GravityRegistration(*images)

Inherits from pirt.GDGRegistration

A registration algorithm based on attraction between masses in both images, which is robust for large differences between the images.

The most important parameters to tune the algorithm with are scale_sampling, speed_factor and final_grid_sampling.

The speed_factor and mass_transforms parameters are specific to this algorithm. Other important parameters are also listed below.

Parameters:
speed_factor : scalar

The relative force of the transform. This one of the most important parameters to tune. Typical values are between 1 and 5. Default 1.

mass_transforms : int or tuple of ints

How the image is transformed to obtain the mass image. The number refers to the order of differentiation; 1 and 2 are gradient magnitude and Laplacian respectively. 0 only performs normalization to subtract the background. Can be specified for all images or for each image individually. Default 1.

mapping : {‘forward’, ‘backward’}

Whether forward or backward mapping is used. Default forward.

final_scale : scalar

The minimum scale used during the registration process. This is the scale at which the registration ends. Default 1.0. Because calculating differentials suffer from more errors as the scale decreases, the minimum value is limited at 0.5.

scale_levels : integer

The amount of scale levels to use during the registration. Each level represents a factor of two in scale. The default (4) works for most images, but for large images or large deformations a larger value can be used.

scale_sampling : scalar

The amount of iterations for each level (i.e. between each factor two in scale). For the coarse implementation, this is the amount of iterations performed before moving to the next scale (which is always a factor of two smaller). Values between 10 and 20 are reasonable in most situations. Default 15. Higher values yield better results in general. The speed of the algorithm scales linearly with this value.

final_grid_sampling : scalar

The grid sampling of the grid at the final level. During the registration process, the B-spine grid sampling scales along with the scale. This parameter is usually best coupled to final_scale. (When increasing final scale, this value should often be increased accordingly.)

grid_sampling_factor : scalar between 0 and 1

To what extent the grid sampling scales with the scale. By making this value lower than 1, the grid is relatively fine at the the higher scales, allowing for more deformations. The default is 0.5. Note that setting this value to 1 when using ‘frozenedge’ can cause the image to be ‘stuck’ at higher scales.

Elastix registration

class pirt.ElastixRegistration(im1, im2)

Inherits from pirt.AbstractRegistration.

Registration class for registration using the Elastix toolkit. [http://elastix.isi.uu.nl/]

This class performs a bspline transformation by default. See also the convenience subclasses.

The params property this class returns a struct with a few common Elastix parameters. the params2 property contains another set of more advanced parameters. Note that any parameter known to elastix can be added to the parameter structures, which enables tuning the registration in great detail. Also note that two parameter structs can be combined by adding them.

Because the parameters directly represent the parameters for the Elastix toolkit, their names do not follow the style of most other registration objects in this package. Here we lists some of the common parameters, for more details we refer to the elastix manual.

Parameters:
FinalGridSpacingInPhysicalUnits : int

When using the BSplineTransform, the final spacing of the grid. This controls the smoothness of the final deformation.

NumberOfResolutions : int

Most registration algorithms adopt a multiresolution approach to direct the solution towards a global optimum and to speed up the process. This parameter specifies the number of scales to apply the registration at. (default 4)

MaximumNumberOfIterations : int

Maximum number of iterations in each resolution level. 200-2000 works usually fine for nonrigid registration. The more, the better, but the longer computation time. This is an important parameter! (default 500)
get_elastix_deformed_image()

Get the deformed input image found as Elastix created it. This should be the same (except for small interpolation errors) to the image obtained using reg.get_deformed_image(0).

class pirt.ElastixRegistration_rigid(*args)

Registration class for registration using the Elastix toolkit. [http://elastix.isi.uu.nl/]

This class performs a rigid transformation by default. See pirt.ElastixRegistration for more details.

Parameters:
AutomaticScalesEstimation : bool

When using a rigid or affine transform. Scales the affine matrix elements compared to the translations, to make sure they are in the same range. In general, it’s best to use automatic scales estimation.

AutomaticTransformInitialization : bool

When using a rigid or affine transform. Automatically guess an initial translation by aligning the geometric centers of the fixed and moving.

NumberOfResolutions : int

Most registration algorithms adopt a multiresolution approach to direct the solution towards a global optimum and to speed up the process. This parameter specifies the number of scales to apply the registration at. (default 4)

MaximumNumberOfIterations : int

Maximum number of iterations in each resolution level. 200-2000 works usually fine for nonrigid registration. The more, the better, but the longer computation time. This is an important parameter! (default 500)
class pirt.ElastixRegistration_affine(*args)

Registration class for registration using the Elastix toolkit. [http://elastix.isi.uu.nl/]

This class performs an affine transformation by default. See pirt.ElastixRegistration for more details.

Parameters:
AutomaticScalesEstimation : bool

When using a rigid or affine transform. Scales the affine matrix elements compared to the translations, to make sure they are in the same range. In general, it’s best to use automatic scales estimation.

AutomaticTransformInitialization : bool

When using a rigid or affine transform. Automatically guess an initial translation by aligning the geometric centers of the fixed and moving.

NumberOfResolutions : int

Most registration algorithms adopt a multiresolution approach to direct the solution towards a global optimum and to speed up the process. This parameter specifies the number of scales to apply the registration at. (default 4)

MaximumNumberOfIterations : int

Maximum number of iterations in each resolution level. 200-2000 works usually fine for nonrigid registration. The more, the better, but the longer computation time. This is an important parameter! (default 500)
class pirt.ElastixGroupwiseRegistration(*images)

Inherits from pirt.ElastixRegistration.

Registration class for registration using the Elastix toolkit. [http://elastix.isi.uu.nl/]

This variant uses the groupwise registration approach as proposed by Metz et al. “Nonrigid registration of dynamic medical imaging data using nD+t B-splines and a groupwise optimization approach”

The params property this class returns a struct with a few common Elastix parameters. the params2 property contains another set of more advanced parameters. Note that any parameter known to elastix can be added to the parameter structures, which enables tuning the registration in great detail. Also note that two parameter structs can be combined by adding them.

Because the parameters directly represent the parameters for the Elastix toolkit, their names do not follow the style of most other registration objects in this package.

Parameters:
FinalGridSpacingInPhysicalUnits : int

When using the BSplineTransform, the final spacing of the grid. This controls the smoothness of the final deformation.

NumberOfResolutions : int

Most registration algorithms adopt a multiresolution approach to direct the solution towards a global optimum and to speed up the process. This parameter specifies the number of scales to apply the registration at. (default 4)

MaximumNumberOfIterations : int

Maximum number of iterations in each resolution level. 200-2000 works usually fine for nonrigid registration. The more, the better, but the longer computation time. This is an important parameter! (default 500)