Registration Module#

Module: pyradise.process.registration

General#

The registration module provides functionality for inter-subject and intra-subject registration of subject images.

Class Overview#

The following classes are provided by the registration module:

Class	Description
`IntraSubjectRegistrationFilterParams`	Parameterization class for the `IntraSubjectRegistrationFilter`.
`IntraSubjectRegistrationFilter`	Filter for intra-subject registration.
`InterSubjectRegistrationFilterParams`	Parameterization class for the `InterSubjectRegistrationFilter`.
`InterSubjectRegistrationFilter`	Filter for inter-subject registration.
`RegistrationType`	Enum class for registration types.

Details#

class IntraSubjectRegistrationFilterParams(reference_modality, registration_type=RegistrationType.RIGID, number_of_histogram_bins=200, learning_rate=1.0, step_size=0.001, number_of_iterations=1500, relaxation_factor=0.5, shrink_factors=(2, 2, 1), smoothing_sigmas=(2, 1, 0), sampling_percentage=0.2, deterministic=True)[source]#

Bases: FilterParams

A filter parameter class for the IntraSubjectRegistrationFilter class.

Parameters:

reference_modality (Union[Modality, str]) – The reference modality.
registration_type (RegistrationType) – The type of registration (default: RegistrationType.RIGID).
number_of_histogram_bins (int) – The number of histogram bins for registration (default: 200).
learning_rate (float) – The learning rate of the optimizer (default: 1.0).
step_size (float) – The step size of the optimizer (default: 0.001).
number_of_iterations (int) – The maximal number of optimization iterations (default: 1500).
relaxation_factor (float) – The relaxation factor (default: 0.5).
shrink_factors (Tuple[int, ...) – The shrink factors for the image pyramid (default: (2, 2, 1))).
smoothing_sigmas (Tuple[float, ...]) – The smoothing sigmas (default: (2, 1, 0))).
sampling_percentage (float) – The sampling percentage of the voxels to incorporate into the optimization (default: 0.2).
deterministic (bool) – Deterministic processing with a fixed seed and a single thread (default: True).

class IntraSubjectRegistrationFilter(warning_on_non_invertible=False)[source]#

Bases: Filter

An invertible intra-subject registration filter class which registers all IntensityImage instances to a reference IntensityImage instance.

Important

This filter assumes that the SegmentationImage instances are already registered to the reference IntensityImage instance. No transformation will be applied to the SegmentationImage instances.

Warning

The inverse registration procedure may not yield the expected results if successive Filter s are applied to the same Image instances. Thus, it’s recommended to use the invertibility feature with appropriate caution.

static is_invertible()[source]#

Return whether the filter is invertible or not.

Returns:: True because the registration filter is invertible.
Return type:: bool

execute(subject, params)[source]#

Execute the intra-subject registration procedure.

Parameters:

subject (Subject) – The Subject instance to be processed.
params (IntraSubjectRegistrationFilterParams) – The filter parameters.

Returns:

The Subject instance with registered IntensityImage instances.

Return type:

Subject

execute_inverse(subject, transform_info, target_image=None)[source]#

Execute the inverse of the intra-subject registration procedure.

Parameters:

subject (Subject) – The Subject instance to be processed.
transform_info (TransformInfo) – The transform information.
target_image (Optional[Union[SegmentationImage, IntensityImage]]) – The target image to which the inverse transformation should be applied. If None, the inverse transformation is applied to all images (default: None).

Returns:

The Subject instance with unregistered IntensityImage instances.

Return type:

Subject

class InterSubjectRegistrationFilterParams(reference_subject, reference_modality, subject_modality=None, registration_type=RegistrationType.RIGID, number_of_histogram_bins=200, learning_rate=1.0, step_size=0.001, number_of_iterations=1500, relaxation_factor=0.5, shrink_factors=(2, 2, 1), smoothing_sigmas=(2, 1, 0), sampling_percentage=0.2, deterministic=True)[source]#

Bases: FilterParams

A filter parameter class for the InterSubjectRegistrationFilter class.

Parameters:

reference_subject (Subject) – The reference subject to which the subject will be registered.
reference_modality (Union[Modality, str]) – The modality of the reference image (fixed image) to be used for registration.
subject_modality (Optional[Union[Modality, str]]) – The modality of the subject image (moving image) to be used for registration. If None, the same modality as the reference image will be used (default: None).
registration_type (RegistrationType) – The type of registration (default: RegistrationType.RIGID).
number_of_histogram_bins (int) – The number of histogram bins for registration (default: 200).
learning_rate (float) – The learning rate of the optimizer (default: 1.0).
step_size (float) – The step size of the optimizer (default: 0.001).
number_of_iterations (int) – The maximal number of optimization iterations (default: 1500).
relaxation_factor (float) – The relaxation factor (default: 0.5).
shrink_factors (Tuple[int, ...) – The shrink factors for the image pyramid (default: (2, 2, 1))).
smoothing_sigmas (Tuple[float, ...]) – The smoothing sigmas (default: (2, 1, 0))).
sampling_percentage (float) – The sampling percentage of the voxels to incorporate into the optimization (default: 0.2).
deterministic (bool) – Deterministic processing with a fixed seed and a single thread (default: True).

class InterSubjectRegistrationFilter(warning_on_non_invertible=False)[source]#

Bases: Filter

An invertible inter-subject registration filter class which registers all IntensityImage instances of the provided Subject to a reference IntensityImage instance of another Subject.

Important

This filter assumes that all Image instances of the provided Subject are co-registered such that the SegmentationImage instances do not require special treatment.

Warning

static is_invertible()[source]#

Return whether the filter is invertible.

Returns:: True because the inter-subject registration is invertible.
Return type:: bool

execute(subject, params)[source]#

Executes the inter-subject registration procedure.

Parameters:

subject (Subject) – The Subject instance to be processed.
params (InterSubjectRegistrationFilterParams) – The filter parameters.

Returns:

The Subject instance with all IntensityImage instances registered to the reference subject IntensityImage instance.

Return type:

Subject

execute_inverse(subject, transform_info, target_image=None)[source]#

Execute the inverse of the inter-subject registration procedure.

Parameters:

subject (Subject) – The Subject instance to be processed.
transform_info (TransformInfo) – The transform information.
target_image (Optional[Union[SegmentationImage, IntensityImage]]) – The target image to which the inverse transformation should be applied. If None, the inverse transformation is applied to all images (default: None).

Returns:

The Subject instance with unregistered IntensityImage instances.

Return type:

Subject

class IntraInterSubjectRegistrationFilterParams(reference_subject, reference_modality, subject_inter_modality=None, subject_intra_modalities=None, registration_type=RegistrationType.RIGID, number_of_histogram_bins=200, learning_rate=1.0, step_size=0.001, number_of_iterations=1500, relaxation_factor=0.5, shrink_factors=(2, 2, 1), smoothing_sigmas=(2, 1, 0), sampling_percentage=0.2, deterministic=True)[source]#

Bases: FilterParams

A filter parameter class for the IntraInterSubjectRegistrationFilter class.

Parameters:

reference_subject (Subject) – The reference subject to which the subject will be registered.
reference_modality (Union[Modality, str]) – The modality of the reference image (fixed image) to be used for registration.
subject_inter_modality (Optional[Union[Modality, str]]) – The modality of the subject image (moving image) to be used for the inter-subject registration. None is not an option here (default: None).
subject_intra_modalities (Optional[Tuple[Union[Modality, str], ...]]) – The modalities of the subject images to be registered to the subject_inter_modality. If None, all modalities of the subject will be registered to the subject_inter_modality (default: None).
registration_type (RegistrationType) – The type of registration (default: RegistrationType.RIGID).
number_of_histogram_bins (int) – The number of histogram bins for registration (default: 200).
learning_rate (float) – The learning rate of the optimizer (default: 1.0).
step_size (float) – The step size of the optimizer (default: 0.001).
number_of_iterations (int) – The maximal number of optimization iterations (default: 1500).
relaxation_factor (float) – The relaxation factor (default: 0.5).
shrink_factors (Tuple[int, ...) – The shrink factors for the image pyramid (default: (2, 2, 1))).
smoothing_sigmas (Tuple[float, ...]) – The smoothing sigmas (default: (2, 1, 0))).
sampling_percentage (float) – The sampling percentage of the voxels to incorporate into the optimization (default: 0.2).
resampling_interpolator (int) – The interpolator to use for resampling the image.
deterministic (bool) – Deterministic processing with a fixed seed and a single thread (default: True).

class IntraInterSubjectRegistrationFilter(warning_on_non_invertible=False)[source]#

Bases: Filter

An invertible intra-inter-subject registration filter class - inter-registration of a defined subject sequence to a reference subject (presumably atlas) - intra-registration of subject images to the previously registered subject sequence

Important

This filter assumes that all Image instances of the provided Subject are co-registered such that the SegmentationImage instances do not require special treatment.

Warning

static is_invertible()[source]#

Return whether the filter is invertible.

Returns:: True because the inter-subject registration is invertible.
Return type:: bool

execute(subject, params)[source]#

Executes the inter-subject registration procedure.

Parameters:

subject (Subject) – The Subject instance to be processed.
params (InterSubjectRegistrationFilterParams) – The filter parameters.

Returns:

The Subject instance with all IntensityImage instances registered to the reference subject IntensityImage instance.

Return type:

Subject

execute_inverse(subject, transform_info, target_image=None)[source]#

Execute the inverse of the inter-subject registration procedure.

Parameters:

subject (Subject) – The Subject instance to be processed.
transform_info (TransformInfo) – The transform information.
target_image (Optional[Union[SegmentationImage, IntensityImage]]) – The target image to which the inverse transformation should be applied. If None, the inverse transformation is applied to all images (default: None).

Returns:

The Subject instance with unregistered IntensityImage instances.

Return type:

Subject

class RegistrationType(value)[source]#

Bases: Enum

An enum class representing the different registration transform types.

AFFINE = 1#: Affine registration.

SIMILARITY = 2#: Similarity registration.

RIGID = 3#: Rigid registration.

BSPLINE = 4#: BSpline registration.