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

Bases: ABC

Filter base class.

abstract execute(image: Image, params: FilterParams | None = None) → Image

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

Bases: ABC

Represents a filter parameters interface.

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

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_: Filter, params: FilterParams | None = None)

Adds a filter to the pipeline.

Parameters:

• filter (Filter) – A filter.

• params (FilterParams) – The filter parameters.

execute(image: Image) → Image

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: FilterParams, filter_index: int)

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)

Bases: 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: Image, params: CmdlineExecutorParams | None = None) → Image

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])

Bases: 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, int | tuple])

Bases: 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: Image, params: FilterParams | None = None) → Image

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)

Bases: 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: Image, params: SizeCorrectionParams | None = None) → Image

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)

Bases: 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)

Bases: Filter

Represents a binary threshold image filter.

Parameters:

threshold (float) – The threshold value.

execute(image: Image, params: FilterParams | None = None) → Image

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)

Bases: 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: Image, params: FilterParams | None = None) → Image

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)

Bases: 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: Image, params: BiasFieldCorrectorParams | None = None) → Image

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: Image)

Bases: 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)

Bases: 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: Image, params: FilterParams | None = None) → Image

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)

Bases: 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: Image, params: HistogramMatcherParams | None = None) → Image

Matches the image intensity histogram to a reference.

Parameters:

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

• params (HistogramMatcherParams) – The filter parameters.

Returns:

The filtered image.

Return type:

sitk.Image

class pymia.filtering.preprocessing.HistogramMatcherParams(reference_image: Image)

Bases: 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

Bases: Filter

Represents a z-score normalization filter.

Filter base class.

execute(image: Image, params: FilterParams | None = None) → Image

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)

Bases: Filter

Represents a rescale intensity filter.

Parameters:

• min_intensity (float) – The min intensity value.

• max_intensity (float) – The max intensity value.

execute(image: Image, params: FilterParams | None = None) → Image

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

• ITK Registration

• ITK Software Guide Registration

class pymia.filtering.registration.MultiModalRegistration(registration_type: 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=23)

Bases: 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: Image, params: MultiModalRegistrationParams | None = None) → Image

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: Image, fixed_image_mask: Image | None = None, callbacks: List[RegistrationCallback] | None = None)

Bases: 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 = '')

Bases: 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()

Callback for the EndEvent.

registration_iteration_ended()

Callback for the IterationEvent.

registration_resolution_changed()

Callback for the MultiResolutionIterationEvent.

registration_started()

Callback for the StartEvent.

class pymia.filtering.registration.RegistrationCallback

Bases: ABC

Represents the abstract handler for the registration callbacks.

registration_ended()

Callback for the EndEvent.

registration_iteration_ended()

Callback for the IterationEvent.

registration_resolution_changed()

Callback for the MultiResolutionIterationEvent.

registration_started()

Callback for the StartEvent.

set_params(registration_method: ImageRegistrationMethod, fixed_image: Image, moving_image: Image, transform: Transform)

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)

Bases: Enum

Represents the registration transformation type.

AFFINE = 1

BSPLINE = 4

RIGID = 3

SIMILARITY = 2