BatchFilter#

class zrad.batch.filtering.BatchFilter(input_directory: str | Path, output_directory: str | Path, input_data_type: str, modality: str, filter_type: str, filter_dimension: str, padding_type: str, number_of_threads: int = 1, patient_folders: Sequence[str] | None = None, start_folder: str | int | None = None, stop_folder: str | int | None = None, nifti_image_name: str | None = None, mean_support: int | str | None = None, log_sigma: float | str | None = None, log_cutoff: float | str | None = None, laws_response_map: str | None = None, laws_rotation_invariance: bool | str = False, laws_pooling: str | None = None, laws_energy_map: bool | str = False, laws_distance: int | str | None = None, wavelet_response_map: str | None = None, wavelet_type: str | None = None, wavelet_decomposition_level: int | str | None = None, wavelet_rotation_invariance: bool | str = False, gabor_res_mm: float | str | None = None, gabor_sigma_mm: float | str | None = None, gabor_lambda_mm: float | str | None = None, gabor_gamma: float | str | None = None, gabor_theta: float | str | None = None, gabor_rotation_invariance: bool | str = False, gabor_orthogonal_planes: bool | str = False, riesz_order: Sequence[int] | str | None = None, structure_tensor_sigma_mm: float | str | None = None, parallel_backend: str = 'processes')[source]#

Run one image filter over many case folders and write NIfTI outputs.

BatchFilter is the batch counterpart to the lower-level filtering classes. It discovers case folders, loads one image per case, applies the configured filter, and writes one filtered NIfTI image per processed case. The API is save-to-disk only.

Parameters:

  • input_directory (str or pathlib.Path) – Directory containing one subfolder per case.

  • output_directory (str or pathlib.Path) – Directory where filtered case folders are written.

  • input_data_type ({"dicom", "nifti"}) – Input format. Values are normalized to lower-case during validation.

  • modality ({"CT", "MRI", "PET", "MG", "US", "RTDOSE"}) – Image modality used by the image reader.

  • filter_type ({"Mean", "Laplacian of Gaussian", "Riesz-transformed LoG", "Laws Kernels", "Gabor", "Wavelets", "Simoncelli"}) – Filter family to apply.

  • filter_dimension ({"2D", "3D"}) – Apply the filter slice-wise in 2D or volumetrically in 3D.

  • padding_type (str) – Boundary handling mode passed to the selected filter.

  • number_of_threads (int, optional) – Number of cases to process in parallel. The default is 1.

  • patient_folders (sequence of str or str, optional) – Explicit case folders to process. Comma-separated strings are accepted.

  • start_folder (str or int, optional) – Inclusive numeric folder range. Both values must be provided together.

  • stop_folder (str or int, optional) – Inclusive numeric folder range. Both values must be provided together.

  • nifti_image_name (str, optional) – Image file name or stem used for NIfTI input.

  • mean_support (int or str, optional) – Mean-filter kernel side length in voxels. Required for Mean filtering.

  • log_sigma (float or str, optional) – Gaussian standard deviation in millimetres. Required for LoG and Riesz-transformed LoG filtering.

  • log_cutoff (float or str, optional) – LoG kernel truncation radius in multiples of log_sigma.

  • laws_response_map (str, optional) – Laws kernel combination, such as "L5E5" in 2D or "L5E5S5" in 3D.

  • laws_rotation_invariance (bool or str, default=False) – Combine Laws responses over axis permutations and flips. GUI-style "Enable" and "Disable" values are also accepted.

  • laws_pooling ({"avg", "max"}, optional) – Pooling rule for rotation-invariant Laws responses. Required for Laws batch configuration, including when rotation invariance is disabled.

  • laws_energy_map (bool or str, default=False) – Return a local mean absolute Laws response. Accepts booleans or GUI-style "Enable" and "Disable" values.

  • laws_distance (int or str, optional) – Energy-map neighbourhood radius in voxels. A positive value is required for Laws batch configuration, including when energy maps are disabled.

  • wavelet_response_map (str, optional) – Separable-wavelet low/high-pass combination, such as "LH" in 2D or "LLH" in 3D.

  • wavelet_type ({"db2", "db3", "coif1", "haar"}, optional) – Wavelet family for separable filtering.

  • wavelet_decomposition_level (int or str, optional) – Scale level, starting at 1. Required for both separable wavelets (levels 1 or 2) and Simoncelli filtering (any supported positive level).

  • wavelet_rotation_invariance (bool or str, default=False) – Average separable-wavelet responses over rotations. Accepts booleans or GUI-style "Enable" and "Disable" values.

  • gabor_res_mm (float or str, optional) – Gabor voxel spacing in millimetres per pixel, used to convert physical scales to kernel coordinates.

  • gabor_sigma_mm (float or str, optional) – Gabor Gaussian envelope standard deviation in millimetres.

  • gabor_lambda_mm (float or str, optional) – Gabor sinusoidal wavelength in millimetres.

  • gabor_gamma (float or str, optional) – Gabor kernel aspect ratio.

  • gabor_theta (float or str, optional) – Gabor orientation angle in radians, or angular step when rotation invariance is enabled. All five numeric Gabor parameters are required when selecting Gabor filtering.

  • gabor_rotation_invariance (bool or str, default=False) – Average Gabor responses over orientations. Accepts booleans or GUI-style "Enable" and "Disable" values.

  • gabor_orthogonal_planes (bool or str, default=False) – Average Gabor responses across the three orthogonal slice planes. Accepts booleans or GUI-style "Enable" and "Disable" values.

  • riesz_order (sequence of int or str, optional) – Non-negative Riesz multi-index in physical (x, y) or (x, y, z) order. Required with positive total order for Riesz-transformed LoG; optional for Simoncelli, where omission or all zeros selects the isotropic response. Comma-separated strings are accepted.

  • structure_tensor_sigma_mm (float or str, optional) – Positive scale in millimetres for local alignment of pure second-order 3D Riesz-transformed LoG responses, such as (2, 0, 0).

  • parallel_backend ({"processes", "threads"}, optional) – Joblib backend preference used when number_of_threads is greater than one. The default is "processes".

Notes

validate() normalizes public attributes in place. After validation, directories are Path objects, input_data_type is lower-case, modality is upper-case, and numeric filter settings are converted to numeric Python values.

Methods

get_output_filename()

Return the GUI-compatible output file name for the configured filter.

plan()

Return the case folders selected for filtering.

run([progress_callback])

Run filtering and write filtered NIfTI images.

validate()

Validate and normalize filtering configuration.
BatchFilter.get_output_filename() → str[source]#

Return the GUI-compatible output file name for the configured filter.

Returns:

filename – File name ending in .nii.gz.

Return type:

str

Raises:

InvalidInputParametersError – If filter_type is not supported.

BatchFilter.plan() → list[str][source]#

Return the case folders selected for filtering.

Returns:

folders – Deterministically ordered case folder names selected by patient_folders or the numeric start_folder / stop_folder range. If neither option is set, all non-hidden subfolders are returned.

Return type:

list of str

Raises:

InvalidInputParametersError – If validation fails before folder selection.

BatchFilter.run(progress_callback: Callable[[int], None] | None = None) → BatchResult[source]#

Run filtering and write filtered NIfTI images.

Parameters:

progress_callback (callable, optional) – Function called as progress_callback(step_count) after cases complete. step_count may be greater than one during parallel execution.

Returns:

result – Aggregate result with one FilteringCaseResult per selected case.

Return type:

BatchResult

Notes

Case-level failures are recorded in the returned result and do not stop the batch.

BatchFilter.validate() → None[source]#

Validate and normalize filtering configuration.

Raises:

InvalidInputParametersError – If the input directory, data type, modality, folder selection, threading, backend, filter type, or filter-specific settings are invalid.