Filtering (pymia.filtering package)

The filtering package provides basic image filter and manipulation functions.

All filters in the pymia.filtering package implement the pymia.filtering.filter.Filter interface, and can be used to set up a pipeline with the pymia.filtering.filter.FilterPipeline. Refer to Filter pipelines for a code example.

Filter pipeline (pymia.filtering.filter module)

This module provides classes to set up a filtering pipeline.

class pymia.filtering.filter.Filter[source]

Bases: abc.ABC

Filter base class.

abstract execute(image: SimpleITK.SimpleITK.Image, params: Optional[pymia.filtering.filter.FilterParams] = None) → SimpleITK.SimpleITK.Image[source]

Executes a filter on an image.

Parameters

  • image (sitk.Image) – The image to filter.

  • params (FilterParams) – The filter parameters.

Returns

The filtered image.

Return type

sitk.Image

class pymia.filtering.filter.FilterParams[source]

Bases: abc.ABC

Represents a filter parameters interface.

class pymia.filtering.filter.FilterPipeline(filters: Optional[List[pymia.filtering.filter.Filter]] = None)[source]

Bases: object

Represents a filter pipeline, which sequentially executes filters (Filter) on an image.

Parameters

filters (list of Filter) – The filters of the pipeline.

add_filter(filter_: pymia.filtering.filter.Filter, params: Optional[pymia.filtering.filter.FilterParams] = None)[source]

Adds a filter to the pipeline.

Parameters
execute(image: SimpleITK.SimpleITK.Image) → SimpleITK.SimpleITK.Image[source]

Executes the filter pipeline on an image.

Parameters

image (sitk.Image) – The image to filter.

Returns

The filtered image.

Return type

sitk.Image

set_param(params: pymia.filtering.filter.FilterParams, filter_index: int)[source]

Sets an image-specific parameter for a filter.

Use this function to update the parameters of a filter to be specific to the image to be filtered.

Parameters

  • params (FilterParams) – The parameter(s).

  • filter_index (int) – The filter’s index the parameters belong to.

Miscellaneous (pymia.filtering.misc module)

The misc (miscellaneous) module provides filters, which don’t have a classical purpose.

class pymia.filtering.misc.CmdlineExecutor(executable_path: str)[source]

Bases: pymia.filtering.filter.Filter

Represents a command line executable.

Use this filter to execute for instance a C++ command line program, which loads and image, processes, and saves it.

Parameters

executable_path (str) – The path to the executable to run.

execute(image: SimpleITK.SimpleITK.Image, params: Optional[pymia.filtering.misc.CmdlineExecutorParams] = None) → SimpleITK.SimpleITK.Image[source]

Executes a command line program.

Parameters

  • image (sitk.Image) – The image to filter.

  • params (CmdlineExecutorParams) – The execution specific command line parameters.

Returns

The filtered image.

Return type

sitk.Image

class pymia.filtering.misc.CmdlineExecutorParams(arguments: List[str])[source]

Bases: pymia.filtering.filter.FilterParams

Command line executor filter parameters used by the CmdlineExecutor filter.

Parameters

arguments (List[str]) – Additional arguments for the command line execution.

class pymia.filtering.misc.Relabel(label_changes: Dict[int, Union[int, tuple]])[source]

Bases: pymia.filtering.filter.Filter

Represents a relabel filter.

Parameters

label_changes (Dict[int, Union[int, tuple]]) – Label change rule where the key is the new label and the value the existing (can be multiple) label.

execute(image: SimpleITK.SimpleITK.Image, params: Optional[pymia.filtering.filter.FilterParams] = None) → SimpleITK.SimpleITK.Image[source]

Executes the relabeling of the label image.

Parameters

  • image (sitk.Image) – The image to filter.

  • params (FilterParams) – The filter parameters (unused).

Returns

The filtered image.

Return type

sitk.Image

class pymia.filtering.misc.SizeCorrection(two_sided: bool = True, pad_constant: float = 0.0)[source]

Bases: pymia.filtering.filter.Filter

Represents a filter to correct the shape/size by padding or cropping.

Parameters

  • two_sided (bool) – Indicates whether the cropping and padding should be applied on one or both side(s) of the dimension.

  • pad_constant (float) – The constant value used for padding.

execute(image: SimpleITK.SimpleITK.Image, params: Optional[pymia.filtering.misc.SizeCorrectionParams] = None) → SimpleITK.SimpleITK.Image[source]

Executes the shape/size correction by padding or cropping.

Parameters

  • image (sitk.Image) – The image to filter.

  • params (SizeCorrectionParams) – The filter parameters containing the reference (target) shape.

Returns

The filtered image.

Return type

sitk.Image

class pymia.filtering.misc.SizeCorrectionParams(reference_shape: tuple)[source]

Bases: pymia.filtering.filter.FilterParams

Represents size (shape) correction filter parameters used by the SizeCorrection filter.

Parameters

reference_shape (tuple) – The reference or target shape.

Post-processing (pymia.filtering.postprocessing module)

The post-processing module provides filters for image post-processing.

class pymia.filtering.postprocessing.BinaryThreshold(threshold: float)[source]

Bases: pymia.filtering.filter.Filter

Represents a binary threshold image filter.

Parameters

threshold (float) – The threshold value.

execute(image: SimpleITK.SimpleITK.Image, params: Optional[pymia.filtering.filter.FilterParams] = None) → SimpleITK.SimpleITK.Image[source]

Executes the binary threshold filter on an image.

Parameters

  • image (sitk.Image) – The image to filter.

  • params (FilterParams) – The filter parameters (unused).

Returns

The filtered image.

Return type

sitk.Image

class pymia.filtering.postprocessing.LargestNConnectedComponents(number_of_components: int = 1, consecutive_component_labels: bool = False)[source]

Bases: pymia.filtering.filter.Filter

Represents a largest N connected components filter.

Extracts the largest N connected components from a label image. By default the N components will all have the value 1 in the output image. Use the consecutive_component_labels option such that the largest has value 1, the second largest has value 2, etc. Background is always assumed to be 0.

Parameters

  • number_of_components (int) – The number of largest components to extract.

  • consecutive_component_labels (bool) – The largest component has value 1, the second largest has value 2, ect. if set to True; otherwise, all components will have value 1.

execute(image: SimpleITK.SimpleITK.Image, params: Optional[pymia.filtering.filter.FilterParams] = None) → SimpleITK.SimpleITK.Image[source]

Executes the largest N connected components filter on an image.

Parameters

  • image (sitk.Image) – The image to filter.

  • params (FilterParams) – The filter parameters (unused).

Returns

The filtered image.

Return type

sitk.Image

Pre-processing (pymia.filtering.preprocessing module)

The pre-processing module provides filters for image pre-processing.

class pymia.filtering.preprocessing.BiasFieldCorrector(convergence_threshold: float = 0.001, max_iterations: List[int] = (50, 50, 50, 50), fullwidth_at_halfmax: float = 0.15, filter_noise: float = 0.01, histogram_bins: int = 200, control_points: List[int] = (4, 4, 4), spline_order: int = 3)[source]

Bases: pymia.filtering.filter.Filter

Represents a bias field correction filter.

Parameters

  • convergence_threshold (float) – The threshold to stop the optimizer.

  • max_iterations (List[int]) – The maximum number of optimizer iterations at each level.

  • fullwidth_at_halfmax (float) – The full width at half maximum.

  • filter_noise (float) – Wiener filter noise.

  • histogram_bins (int) – Number of histogram bins.

  • control_points (List[int]) – The number of spline control points.

  • spline_order (int) – The spline order.

execute(image: SimpleITK.SimpleITK.Image, params: Optional[pymia.filtering.preprocessing.BiasFieldCorrectorParams] = None) → SimpleITK.SimpleITK.Image[source]

Executes a bias field correction on an image.

Parameters

  • image (sitk.Image) – The image to filter.

  • params (BiasFieldCorrectorParams) – The bias field correction filter parameters.

Returns

The bias field corrected image.

Return type

sitk.Image

class pymia.filtering.preprocessing.BiasFieldCorrectorParams(mask: SimpleITK.SimpleITK.Image)[source]

Bases: pymia.filtering.filter.FilterParams

Bias field correction filter parameters used by the BiasFieldCorrector filter.

Parameters

mask (sitk.Image) – A mask image (0=background; 1=mask).

Examples

To generate a default mask use Otsu’s thresholding:

>>> sitk.OtsuThreshold(image, 0, 1, 200)
class pymia.filtering.preprocessing.GradientAnisotropicDiffusion(time_step: float = 0.125, conductance: int = 3, conductance_scaling_update_interval: int = 1, no_iterations: int = 5)[source]

Bases: pymia.filtering.filter.Filter

Represents a gradient anisotropic diffusion filter.

Parameters

  • time_step (float) – The time step.

  • conductance (int) – The conductance (the higher the smoother the edges).

  • conductance_scaling_update_interval – TODO

  • no_iterations (int) – Number of iterations.

execute(image: SimpleITK.SimpleITK.Image, params: Optional[pymia.filtering.filter.FilterParams] = None) → SimpleITK.SimpleITK.Image[source]

Executes a gradient anisotropic diffusion on an image.

Parameters

  • image (sitk.Image) – The image to filter.

  • params (FilterParams) – The parameters (unused).

Returns

The smoothed image.

Return type

sitk.Image

class pymia.filtering.preprocessing.HistogramMatcher(histogram_levels: int = 256, match_points: int = 1, threshold_mean_intensity: bool = True)[source]

Bases: pymia.filtering.filter.Filter

Represents a histogram matching filter.

Parameters

  • histogram_levels (int) – Number of histogram levels.

  • match_points (int) – Number of match points.

  • threshold_mean_intensity (bool) – Threshold at mean intensity.

execute(image: SimpleITK.SimpleITK.Image, params: Optional[pymia.filtering.preprocessing.HistogramMatcherParams] = None) → SimpleITK.SimpleITK.Image[source]

Matches the image intensity histogram to a reference.

Parameters
Returns

The filtered image.

Return type

sitk.Image

class pymia.filtering.preprocessing.HistogramMatcherParams(reference_image: SimpleITK.SimpleITK.Image)[source]

Bases: pymia.filtering.filter.FilterParams

Histogram matching filter parameters used by the HistogramMatcher filter.

Parameters

reference_image (sitk.Image) – Reference image for the matching.

class pymia.filtering.preprocessing.NormalizeZScore[source]

Bases: pymia.filtering.filter.Filter

Represents a z-score normalization filter.

Filter base class.

execute(image: SimpleITK.SimpleITK.Image, params: Optional[pymia.filtering.filter.FilterParams] = None) → SimpleITK.SimpleITK.Image[source]

Executes a z-score normalization on an image.

Parameters

  • image (sitk.Image) – The image to filter.

  • params (FilterParams) – The parameters (unused).

Returns

The normalized image.

Return type

sitk.Image

class pymia.filtering.preprocessing.RescaleIntensity(min_intensity: float, max_intensity: float)[source]

Bases: pymia.filtering.filter.Filter

Represents a rescale intensity filter.

Parameters

  • min_intensity (float) – The min intensity value.

  • max_intensity (float) – The max intensity value.

execute(image: SimpleITK.SimpleITK.Image, params: Optional[pymia.filtering.filter.FilterParams] = None) → SimpleITK.SimpleITK.Image[source]

Executes an intensity rescaling on an image.

Parameters

  • image (sitk.Image) – The image to filter.

  • params (FilterParams) – The parameters (unused).

Returns

The intensity rescaled image.

Return type

sitk.Image

Registration (pymia.filtering.registration module)

The registration module provides classes for image registration.

See also

class pymia.filtering.registration.MultiModalRegistration(registration_type: pymia.filtering.registration.RegistrationType = RegistrationType.RIGID, number_of_histogram_bins: int = 200, learning_rate: float = 1.0, step_size: float = 0.001, number_of_iterations: int = 200, relaxation_factor: float = 0.5, shrink_factors: List[int] = (2, 1, 1), smoothing_sigmas: List[float] = (2, 1, 0), sampling_percentage: float = 0.2, sampling_seed: int = 0, resampling_interpolator=3)[source]

Bases: pymia.filtering.filter.Filter

Represents a multi-modal image registration filter.

The filter estimates a 3-dimensional rigid or affine transformation between images of different modalities using - Mutual information similarity metric - Linear interpolation - Gradient descent optimization

Parameters

  • registration_type (RegistrationType) – The type of the registration (‘rigid’ or ‘affine’).

  • number_of_histogram_bins (int) – The number of histogram bins.

  • learning_rate (float) – The optimizer’s learning rate.

  • step_size (float) – The optimizer’s step size. Each step in the optimizer is at least this large.

  • number_of_iterations (int) – The maximum number of optimization iterations.

  • relaxation_factor (float) – The relaxation factor to penalize abrupt changes during optimization.

  • shrink_factors (List[int]) – The shrink factors at each shrinking level (from high to low).

  • smoothing_sigmas (List[int]) – The Gaussian sigmas for smoothing at each shrinking level (in physical units).

  • sampling_percentage (float) – Fraction of voxel of the fixed image that will be used for registration (0, 1]. Typical values range from 0.01 (1 %) for low detail images to 0.2 (20 %) for high detail images. The higher the fraction, the higher the computational time.

  • sampling_seed – The seed for reproducible behavior.

  • resampling_interpolator – Interpolation to be applied while resampling the image by the determined transformation.

Examples

The following example shows the usage of the MultiModalRegistration class.

>>> fixed_image = sitk.ReadImage('/path/to/image/fixed.mha')
>>> moving_image = sitk.ReadImage('/path/to/image/moving.mha')
>>> registration = MultiModalRegistration()  # specify parameters to your needs
>>> parameters = MultiModalRegistrationParams(fixed_image)
>>> registered_image = registration.execute(moving_image, parameters)
execute(image: SimpleITK.SimpleITK.Image, params: Optional[pymia.filtering.registration.MultiModalRegistrationParams] = None) → SimpleITK.SimpleITK.Image[source]

Executes a multi-modal rigid registration.

Parameters

  • image (sitk.Image) – The moving image to register.

  • params (MultiModalRegistrationParams) – The parameters, which contain the fixed image.

Returns

The registered image.

Return type

sitk.Image

class pymia.filtering.registration.MultiModalRegistrationParams(fixed_image: SimpleITK.SimpleITK.Image, fixed_image_mask: Optional[SimpleITK.SimpleITK.Image] = None, callbacks: Optional[List[pymia.filtering.registration.RegistrationCallback]] = None)[source]

Bases: pymia.filtering.filter.FilterParams

Represents parameters for the multi-modal rigid registration used by the MultiModalRegistration filter.

Parameters

  • fixed_image (sitk.Image) – The fixed image for the registration.

  • fixed_image_mask (sitk.Image) – A mask for the fixed image to limit the registration.

  • callbacks (t.List[RegistrationCallback]) – Path to the directory where to plot the registration progress if any. Note that this increases the computational time.

class pymia.filtering.registration.PlotOnResolutionChangeCallback(plot_dir: str, file_name_prefix: str = '')[source]

Bases: pymia.filtering.registration.RegistrationCallback

Represents a plotter for registrations.

Saves the moving image on each resolution change and the registration end.

Parameters

  • plot_dir (str) – Path to the directory where to save the plots.

  • file_name_prefix (str) – The file name prefix for the plots.

registration_ended()[source]

Callback for the EndEvent.

registration_iteration_ended()[source]

Callback for the IterationEvent.

registration_resolution_changed()[source]

Callback for the MultiResolutionIterationEvent.

registration_started()[source]

Callback for the StartEvent.

class pymia.filtering.registration.RegistrationCallback[source]

Bases: abc.ABC

Represents the abstract handler for the registration callbacks.

registration_ended()[source]

Callback for the EndEvent.

registration_iteration_ended()[source]

Callback for the IterationEvent.

registration_resolution_changed()[source]

Callback for the MultiResolutionIterationEvent.

registration_started()[source]

Callback for the StartEvent.

set_params(registration_method: SimpleITK.SimpleITK.ImageRegistrationMethod, fixed_image: SimpleITK.SimpleITK.Image, moving_image: SimpleITK.SimpleITK.Image, transform: SimpleITK.SimpleITK.Transform)[source]

Sets the parameters that might be used during the callbacks

Parameters

  • registration_method (sitk.ImageRegistrationMethod) – The registration method.

  • fixed_image (sitk.Image) – The fixed image.

  • moving_image (sitk.Image) – The moving image.

  • transform (sitk.Transform) – The transformation.

class pymia.filtering.registration.RegistrationType(value)[source]

Bases: enum.Enum

Represents the registration transformation type.

AFFINE = 1
BSPLINE = 4
RIGID = 3
SIMILARITY = 2