Intensity Module#

Module: pyradise.process.intensity

General#

The intensity module provides intensity-modifying filters, such as a ZScoreNormFilter. Furthermore, the intensity module provides separate intensity filter base classes (i.e., IntensityFilter and IntensityLoopFilter) to simplify implementation of new intensity-modifying filters and to facilitate the user-driven implementation.

Class Overview#

The following classes are provided by the intensity module:

Class

Description

IntensityFilterParams

Parameterization base class for the IntensityFilter base class.

IntensityFilter

Simplified base class for intensity filters.

IntensityLoopFilterParams

Parameterization base class for the IntensityLoopFilter base class.

IntensityLoopFilter

Simplified base class for intensity filters that process the images via looping over a predefined axis.

ZScoreNormFilterParams

Parameterization class for the ZScoreNormFilter.

ZScoreNormFilter

Filter for z-score normalization of IntensityImage instances.

ZeroOneNormFilterParams

Parameterization class for the ZeroOneNormFilter.

ZeroOneNormFilter

Filter for zero-one (1-0) normalization of IntensityImage instances.

RescaleIntensityFilterParams

Parameterization class for the RescaleIntensityFilter.

RescaleIntensityFilter

Filter to rescale intensity values of IntensityImage instances.

ClipIntensityFilterParams

Parameterization class for the ClipIntensityFilter.

ClipIntensityFilter

Filter to limit intensity values of IntensityImage instances to defined limits.

GaussianFilterParams

Parameterization class for the GaussianFilter.

GaussianFilter

Filter for Gaussian blurring of IntensityImage instances.

MedianFilterParams

Parameterization class for the MedianFilter.

MedianFilter

Filter for median blurring of IntensityImage instances.

LaplacianFilterParams

Parameterization class for the LaplacianFilter.

LaplacianFilter

Filter for Laplacian sharpening of IntensityImage instances.

Details#

class IntensityFilterParams(modalities=None)[source]#

Bases: FilterParams

A filter parameter class for the IntensityFilter base class. In addition to the FilterParams class, this class also provides a modalities parameter to specify the images to be processed by the filters.

Parameters:

modalities (Optional[Tuple[Union[Modality, str], ...]]) – The modalities associated with the corresponding IntensityImage instances that should be processed. If None is provided, all IntensityImage instances will be processed (default: None).

class IntensityFilter(warning_on_non_invertible=False)[source]#

Bases: Filter

An abstract filter base class for intensity modifying filters which process the whole image content. In contrast to the Filter base class, this class provides two additional abstract methods ( i.e. _process_image() and _process_image_inverse()) for processing the image content as whole. Thus, this base class is intended to be used for intensity modifying filters which process the whole image content at once.

Note

The selection of the IntensityImage instances to be processed is specified by the IntensityFilterParams instance. If the modalities parameter is set to None, all IntensityImage instances will be processed. Otherwise, only the IntensityImage instances with the specified modalities will be processed. If the user wants to implement its own intensity modifying filter, the user do not need to implement the selection of the images to be processed. The selection mechanism is already provided in the implemented execute() and execute_inverse() methods.

Example

An example implementation of an intensity clippling filter:

>>> class ClipFilterParams(IntensityFilterParams):
>>>     def __init__(self,
>>>                  min_out: float,
>>>                  max_out: float,
>>>                  modalities: Optional[Tuple[Union[Modality, str], ...]] = None
>>>                  ) -> None:
>>>         super().__init__(modalities)
>>>
>>>         if min_out == max_out:
>>>             raise ValueError('The min and max output intensity '
>>>                              'values must not be equal because '
>>>                              'the resulting image '
>>>                              'will have constant intensity.')
>>>
>>>         if min_out > max_out:
>>>             min_out, max_out = max_out, min_out
>>>
>>>         self.min_value: float = min_out
>>>         self.max_value: float = max_out
>>>
>>>
>>> class ClipFilter(IntensityFilter):
>>>
>>>     @staticmethod
>>>     def is_invertible() -> bool:
>>>         # return False because the clipping is not invertible
>>>         return False
>>>
>>>     def _process_image(self,
>>>                        image: IntensityImage,
>>>                        params: ClipFilterParams
>>>                        ) -> IntensityImage:
>>>         # get the image data
>>>         sitk_image = image.get_image_data()
>>>
>>>         # apply the clipping
>>>         clipped_image_sitk = sitk.Clamp(sitk_image,
>>>                                         sitk_image.GetPixelIDValue(),
>>>                                         params.min_value,
>>>                                         params.max_value)
>>>
>>>         # add the clipped SimpleITK image to the image
>>>         image.set_image_data(clipped_image_sitk)
>>>
>>>         # track the necessary information
>>>         self._register_tracked_data(image, sitk_image,
>>>                                     clipped_image_sitk, params)
>>>
>>>         return image
>>>
>>>     def _process_image_inverse(self,
>>>                                image: IntensityImage,
>>>                                transform_info: TransformInfo
>>>                                ) -> IntensityImage:
>>>         # return the original image because the clipping
>>>         # is not invertible
>>>         return image
>>>
>>>     def execute(self,
>>>                 subject: Subject,
>>>                 params: ClipFilterParams
>>>                 ) -> Subject:
>>>         # implement exclusively due to type adaptation for params
>>>         return super().execute(subject, params)
execute(subject, params)[source]#

Execute the intensity modifying procedure.

Parameters:
Returns:

The Subject instance with processed IntensityImage instances.

Return type:

Subject

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

Execute the inverse intensity modifying 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 processed IntensityImage instances.

Return type:

Subject

class IntensityLoopFilterParams(loop_axis, modalities=None)[source]#

Bases: LoopEntryFilterParams

A filter parameter class for the IntensityLoopFilter base class. In addition to the LoopEntryFilterParams class, this class also provides a modalities parameter to specify the images to be processed by the filters.

Parameters:

  • loop_axis (Optional[int]) – The axis along which the data transformation is performed. If None, the transformation is performed on the whole image at once. If a value is given, the transformation is performed by looping over the corresponding image dimension.

  • modalities (Optional[Tuple[Union[Modality, str], ...]]) – The modalities associated with the corresponding IntensityImage instances that should be processed. If None is provided, all IntensityImage instances will be processed (default: None).

class IntensityLoopFilter[source]#

Bases: LoopEntryFilter

An abstract base class for intensity modifying filters that can process the provided image content by looping over a specific axis or by using the whole image extent at once. This base class is intended to be used for implementing flexible intensity modifying filters that can iteratively process subsets of the image content such as for example normalization filters which may be applied slice-wise to the image content.

For the implementation of a new IntensityLoopFilter subclass implement the provided _modify_array() and _modify_array_inverse() methods. Both methods are called iteratively for each loop axis position. The _modify_array() method is called for the forward processing and the _modify_array_inverse() method is called for the inverse processing.

Note

The selection of the IntensityImage instances to be processed is specified by the IntensityLoopFilterParams instance. If the modalities parameter is set to None, all IntensityImage instances will be processed. Otherwise, only the IntensityImage instances with the specified modalities will be processed. If the user wants to implement its own intensity modifying filter, the user do not need to implement the selection of the images to be processed. The selection mechanism is already provided in the implemented execute() and execute_inverse() methods.

execute(subject, params)[source]#

Execute the intensity modifying procedure.

Parameters:
Returns:

The Subject instance with processed IntensityImage instances.

Return type:

Subject

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

Execute the inverse intensity modifying 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 processed IntensityImage instances.

Return type:

Subject

class ZScoreNormFilterParams(loop_axis=None, modalities=None)[source]#

Bases: IntensityLoopFilterParams

A filter parameter class for the ZScoreNormFilter class.

Parameters:

  • loop_axis (Optional[int]) – The axis along which the intensity normalization is performed. If None, the intensity normalization is performed on the whole image extent at once. If a value is given, the intensity normalization is performed by looping over the corresponding image dimension (default: None).

  • modalities (Optional[Tuple[Union[Modality, str], ...]]) – The modalities of the images to be rescaled. If None is provided all images of the provided subject are rescaled (default: None).

class ZScoreNormFilter[source]#

Bases: IntensityLoopFilter

A normalization filter class performing an invertible z-score normalization on all IntensityImage instances of the provided Subject instance.

For the normalization the following formula is applied to the image extent or its subsets:

I_{norm} = \frac{I_{orig} - \mu(I_{orig})}{\sigma(I_{orig})}

For the inverse normalization the following formula is applied to the image extent or its subsets:

I_{orig} = I_{norm} \cdot \sigma(I_{orig}) + \mu(I_{orig})

During the normalization procedure, the intensity mean and standard deviation of the original image or its subsets are tracked such that these values are available for the inverse normalization.

Warning

The inverse normalization 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.

Note

Due to the limited precision of floating point numbers, the inverse normalization may not be exact.

static is_invertible()[source]#

Check if the filter is invertible.

Returns:

True because the z-score normalization procedure is invertible.

Return type:

bool

execute(subject, params)[source]#

Execute the z-score normalization procedure.

Parameters:
Returns:

The Subject instance with z-score normalized IntensityImage instances.

Return type:

Subject

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

Execute the inverse z-score normalization 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 denormalized IntensityImage instances.

Return type:

Subject

class ZeroOneNormFilterParams(loop_axis=None, modalities=None)[source]#

Bases: IntensityLoopFilterParams

A filter parameter class for the ZeroOneNormFilter class.

Parameters:

  • loop_axis (Optional[int]) – The axis along which the intensity normalization is performed. If None, the intensity normalization is performed on the whole image extent at once. If a value is given, the intensity normalization is performed by looping over the corresponding image dimension (default: None).

  • modalities (Optional[Tuple[Union[Modality, str], ...]]) – The modalities of the images to be rescaled. If None is provided all images of the provided subject are rescaled (default: None).

class ZeroOneNormFilter[source]#

Bases: IntensityLoopFilter

A normalization filter class performing an invertible zero-one (1-0) normalization on all IntensityImage instances of the provided Subject instance.

For the normalization the following formula is applied to the image extent or its subsets:

I_{norm} = \frac{I_{orig} - \min(I_{orig})}{\max(I_{orig}) - \min(I_{orig})}

For the inverse normalization the following formula is applied to the image extent or its subsets:

I_{orig} = I_{norm} \cdot (\max(I_{orig}) - \min(I_{orig})) + \min(I_{orig})

During the normalization procedure, the min and max intensity values of the image or its subsets are tracked to be available for inverse normalization.

Warning

The inverse normalization 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.

Note

Due to the limited precision of floating point numbers, the inverse normalization may not be exact.

static is_invertible()[source]#

Check if the filter is invertible.

Returns:

True because the zero-one normalization procedure is invertible.

Return type:

bool

execute(subject, params)[source]#

Execute the zero-one normalization procedure.

Parameters:
Returns:

The Subject instance with zero-one normalized IntensityImage instances.

Return type:

Subject

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

Execute the inverse zero-one normalization 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 denormalized IntensityImage instances.

Return type:

Subject

class RescaleIntensityFilterParams(min_out, max_out, modalities=None)[source]#

Bases: IntensityFilterParams

A filter parameter class for the RescaleIntensityFilter class.

Parameters:

  • min_out (Optional[float]) – The minimum value of the rescaled image. If None is provided the filter takes the minimum intensity value of the image.

  • max_out (Optional[float]) – The maximum value of the rescaled image. If None is provided the filter takes the maximum intensity value of the image.

  • modalities (Optional[Tuple[Union[Modality, str], ...]]) – The modalities of the images to be rescaled. If None is provided all images of the provided subject are rescaled (default: None).

class RescaleIntensityFilter(warning_on_non_invertible=False)[source]#

Bases: IntensityFilter

A filter class performing an invertible intensity rescaling on all selected IntensityImage instances of the provided Subject instance.

For the rescaling the following formula is applied to the image extent or its subsets:

I_{resc} = \frac{I_{orig} - \min(I_{orig})}{\max(I_{orig}) - \min(I_{orig})} \cdot (max_{out} - min_{out}) + min_{out}

For the inverse rescaling the following formula is applied to the image extent or its subsets:

I_{orig} = \frac{I_{resc} - \min(I_{resc})}{\max(I_{resc}) - \min(I_{resc})} \cdot (\max(I_{orig}) - \min(I_{orig})) + \min(I_{orig})

During the rescaling procedure, the min and max intensity of the original image or its subsets are tracked to be available for inverse rescaling.

Warning

The inverse rescaling 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.

Note

Due to the limited precision of floating point numbers, the inverse normalization may not be exact.

static is_invertible()[source]#

Check if the filter is invertible.

Returns:

True because the rescaling procedure is invertible.

Return type:

bool

execute(subject, params)[source]#

Execute the rescaling procedure.

Parameters:
Returns:

The Subject instance with rescaled IntensityImage entries.

Return type:

Subject

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

Execute the inverse rescaling procedure.

Parameters:

  • subject (Subject) – The Subject instance to be inversely rescaled.

  • 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 inversely rescaled IntensityImage entries.

Return type:

Subject

class ClipIntensityFilterParams(min_out, max_out, modalities=None)[source]#

Bases: IntensityFilterParams

A filter parameter class for the ClipIntensityFilter class.

Parameters:

  • min_out (float) – The minimum intensity value of the processed image.

  • max_out (float) – The maximum intensity value of the processed image.

  • modalities (Optional[Tuple[Union[Modality, str], ...]]) – The modalities of the images to be clipped. If None is provided all images of the provided subject are clipped (default: None).

class ClipIntensityFilter(warning_on_non_invertible=False)[source]#

Bases: IntensityFilter

A filter class performing a clipping of intensity values on all selected IntensityImage instances of the provided Subject instance. The clipping procedure sets the intensity values outside the specified range to the specified minimum and maximum values.

For the clipping procedure the following formula is applied to the image data:

I_{out} = \begin{cases} min_{out} & I_{in} < min_{out} \\ max_{out} & I_{in} > max_{out} \\ I_{in} & min_{out} \leq I_{in} \leq max_{out} \end{cases}

Note

The clipping procedure causes a loss of information which can not be recovered. Thus, the clipping procedure is not invertible.

static is_invertible()[source]#

Check if the filter is invertible.

Returns:

False because the clipping procedure is not invertible.

Return type:

bool

execute(subject, params)[source]#

Execute the clipping procedure.

Parameters:
Returns:

The Subject instance with clipped IntensityImage instances.

Return type:

Subject

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

Return the provided subject without any processing because the clipping procedure is not invertible.

Parameters:

  • subject (Subject) – The Subject instance to be returned.

  • 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 provided Subject instance.

Return type:

Subject

class GaussianFilterParams(variance, kernel_size, modalities=None)[source]#

Bases: IntensityFilterParams

A filter parameter class for the GaussianFilter class.

Parameters:

  • variance (float) – The variance of the Gaussian kernel.

  • kernel_size (int) – The kernel size of the Gaussian kernel.

  • modalities (Optional[Tuple[Union[Modality, str], ...]]) – The modalities of the images to be filtered. If None is provided all images of the provided subject are filtered (default: None).

class GaussianFilter(warning_on_non_invertible=False)[source]#

Bases: IntensityFilter

A filter class performing a Gaussian smoothing on all IntensityImage instances of the provided Subject instance.

Reference:

The implementation is based on the SimpleITK implementation of the SimpleITK DiscreteGaussianImageFilter.

Note

The Gaussian smoothing procedure is not invertible.

is_invertible()[source]#

Check if the filter is invertible.

Returns:

False because the Gaussian filter is not invertible.

Return type:

bool

execute(subject, params)[source]#

Execute the Gaussian filter.

Parameters:
Returns:

The Subject instance with Gaussian filtered IntensityImage instances.

Return type:

Subject

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

Return the provided subject without any processing because the Gaussian filtering procedure is not invertible.

Parameters:

  • subject (Subject) – The Subject instance to be returned.

  • 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 provided Subject instance.

Return type:

Subject

class MedianFilterParams(radius, modalities=None)[source]#

Bases: IntensityFilterParams

A filter parameter class for the MedianFilter class.

Parameters:

  • radius (int) – The radius of the median filter.

  • modalities (Optional[Tuple[Union[Modality, str], ...]]) – The modalities of the images to be filtered. If None is provided all images of the provided subject are filtered (default: None).

class MedianFilter(warning_on_non_invertible=False)[source]#

Bases: IntensityFilter

A filter class performing a median filtering on all IntensityImage instances of the provided Subject instance.

Reference:

The implementation is based on the SimpleITK implementation of the SimpleITK MedianImageFilter.

Note

The median filter is not invertible.

static is_invertible()[source]#

Check if the filter is invertible.

Returns:

False because the median filter is not invertible.

Return type:

bool

execute(subject, params)[source]#

Execute the median filter.

Parameters:
Returns:

The Subject instance with filtered IntensityImage instances.

Return type:

Subject

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

Return the provided subject without any processing because the median filtering procedure is not invertible.

Parameters:

  • subject (Subject) – The Subject instance to be returned.

  • 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 provided Subject instance.

Return type:

Subject

class LaplacianFilterParams(modalities=None)[source]#

Bases: IntensityFilterParams

A filter parameter class for the LaplacianFilter class.

Parameters:

modalities (Optional[Tuple[Union[Modality, str], ...]]) – The modalities of the images to be filtered. If None is provided all images of the provided subject are filtered (default: None).

class LaplacianFilter(warning_on_non_invertible=False)[source]#

Bases: IntensityFilter

A filter class performing a Laplacian sharpening on all IntensityImage instances of the provided Subject instance.

Reference:

The implementation is based on the SimpleITK implementation of the SimpleITK LaplacianSharpeningImageFilter.

Note

The Laplacian filter is not invertible.

static is_invertible()[source]#

Check if the filter is invertible.

Returns:

False because the Laplacian filter is not invertible.

Return type:

bool

execute(subject, params=None)[source]#

Execute the Laplacian sharpening filter.

Parameters:
Returns:

The Subject instance with Laplace filtered IntensityImage instances.

Return type:

Subject

Note

The Laplacian filter does not need any parameters.

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

Return the provided subject without any processing because the Laplace filtering procedure is not invertible.

Parameters:

  • subject (Subject) – The Subject instance to be returned.

  • 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 provided Subject instance.

Return type:

Subject