Processing¶

Stateless image processing operations.

Filters¶

class medical_image.process.filters.Filters[source]¶

Bases: object

static convolution(image, output, kernel, device=None)[source]¶

Applies a convolution filter to the given image using PyTorch.

Parameters:

image (Image) – Input image object.
output (Image) – Output image object.
kernel (Tensor) – 2D convolution kernel.
device – Device to perform computation on (None = infer from image).

Returns:

The output Image.

Return type:

Image

static gaussian_filter(image, output, sigma, device=None, truncate=4.0)[source]¶

Applies Gaussian filter.

Parameters:

image (Image)
output (Image)
sigma (float)
truncate (float)

Return type:

Image

static median_filter(image, output, size, device=None)[source]¶

Applies a median filter using PyTorch.

Parameters:

image (Image) – Input image.
output (Image) – Output image.
size (int) – Odd kernel size.
device – Device to run computation on (None = infer from image).

Returns:

The output Image.

Return type:

Image

static butterworth_kernel(image, output, D_0=21, W=32, n=3, device=None)[source]¶

Applies a Butterworth band-pass filter in the frequency domain.

Parameters:

image (Image) – Input image.
output (Image) – Output image.
D_0 (float) – Cutoff frequency.
W (float) – Bandwidth.
n (int) – Filter order.
device – Device to run computation on (None = infer from image).

Returns:

The output Image.

Return type:

Image

static difference_of_gaussian(image, output, low_sigma, high_sigma=None, device=None, truncate=4.0)[source]¶

Applies Difference of Gaussian (DoG) filter.

Parameters:

image (Image) – Input image.
output (Image) – Output image.
low_sigma (float) – First Gaussian sigma.
high_sigma (float | None) – Second Gaussian sigma.
device – Device to run computation on (None = infer from image).

Returns:

The output Image.

Return type:

Image

static laplacian_of_gaussian(image, output, sigma, device=None)[source]¶

Applies Laplacian of Gaussian (LoG) filter.

Parameters:

image (Image) – Input image.
output (Image) – Output image.
sigma (float) – Gaussian sigma.
device – Device to run computation on (None = infer from image).

Returns:

The output Image.

Return type:

Image

static gamma_correction(image, output, gamma, device=None)[source]¶

Applies Gamma Correction.

Parameters:

image (Image) – Input image.
output (Image) – Output image.
gamma (float) – Gamma value.
device – Device to run computation on (None = infer from image).

Returns:

The output Image.

Return type:

Image

static contrast_adjust(image, output, contrast, brightness, device=None)[source]¶

Adjusts contrast and brightness.

Parameters:

image (Image) – Input image.
output (Image) – Output image.
contrast (float) – Contrast coefficient.
brightness (float) – Brightness coefficient.
device – Device to run computation on (None = infer from image).

Returns:

The output Image.

Return type:

Image

static gaussian_filter_batch(images, sigma, device=None, truncate=4.0)[source]¶

Apply Gaussian filter to a batch of images.

Parameters:

images (Tensor) – Batched tensor (B, C, H, W).
sigma (float) – Gaussian sigma.
device – Target device.
truncate (float) – Kernel truncation factor.

Returns:

Filtered batch (B, C, H, W).

Return type:

Tensor

Threshold¶

class medical_image.process.threshold.Threshold[source]¶

Bases: object

static otsu_threshold(image, output=None, device=None)[source]¶

Applies Otsu’s thresholding method to a grayscale image using PyTorch.

Parameters:

image (Image) – Input image with pixel_data as torch.Tensor.
output (Image) – Optional output Image object to store the result.
device – Device to perform computation (None = infer from image).

Returns:

The output Image (or a new InMemoryImage if output is None).

Return type:

Image

static sauvola_threshold(image, output=None, window_size=10, k=0.5, r=128, device=None)[source]¶

Applies Sauvola adaptive thresholding to a grayscale image using PyTorch.

Parameters:

image (Image) – Input grayscale image.
output (Image) – Optional Image object for result.
window_size (int) – Odd size of the local window.
k (float) – Scaling factor in threshold formula.
r (int) – Dynamic range of standard deviation.
device – Device for computation (None = infer from image).

Returns:

The output Image (or a new InMemoryImage if output is None).

Return type:

Image

static binarize(image, output, alpha, device=None)[source]¶

Binarizes an image based on local and global variance using PyTorch.

Formula:: binary = local_variance^2 < alpha * global_variance^2

Parameters:

image (Image) – Input grayscale image.
output (Image) – Output Image object for storing result.
alpha (float) – Scaling factor relating local and global variances.
device – Device for computation (None = infer from image).

Returns:

The output Image.

Return type:

Image

MorphologyOperations¶

class medical_image.process.morphology.MorphologyOperations[source]¶

Bases: object

static morphology_closing(image, output, kernel_size=7, device=None)[source]¶

Performs 2D binary closing on a given image using PyTorch.

Closing = Dilation followed by Erosion with the same structuring element.

Parameters:

image (Image) – Input binary image (0/1).
output (Image) – Output Image object to store the result.
kernel_size (int) – Size of the square structuring element.
device – Device for computation (None = infer from image).

Returns:

The output Image.

Return type:

Image

static region_fill(image, output, device=None)[source]¶

Fills holes in a binary image using scipy’s binary_fill_holes.

Runs in O(H*W) instead of the previous unbounded iterative approach.

Parameters:

image (Image) – Input binary image (0/1).
output (Image) – Output Image object to store the filled result.
device – Device for computation (None = infer from image).

Returns:

The output Image.

Return type:

Image

static erosion(image, output, radius=4, device=None)[source]¶

Grayscale erosion using a flat disk SE.

Parameters:

image (Image) – Input Image (2D float).
output (Image) – Output Image to store result.
radius (int) – Disk SE radius.
device – Torch device (None = infer from image).

Returns:

The output Image.

Return type:

Image

static dilation(image, output, radius=4, device=None)[source]¶

Grayscale dilation using a flat disk SE.

Parameters:

image (Image) – Input Image (2D float).
output (Image) – Output Image to store result.
radius (int) – Disk SE radius.
device – Torch device (None = infer from image).

Returns:

The output Image.

Return type:

Image

static white_top_hat(image, output, radius=4, device=None)[source]¶

White Top-Hat transform: TopHat(I) = I - opening(I).

Opening = dilation(erosion(I)). Highlights bright structures smaller than the structuring element (microcalcifications).

Parameters:

image (Image) – Input Image (2D float, e.g. normalized to [0,1]).
output (Image) – Output Image to store result.
radius (int) – Disk SE radius (default 4 -> 9x9, matching MATLAB).
device – Torch device (None = infer from image).

Returns:

The output Image.

Return type:

Image

Metrics¶

class medical_image.process.metrics.Metrics[source]¶

Bases: object

static entropy(image, decimals=4, device=None)[source]¶

Calculates the Shannon entropy of an image using PyTorch.

Parameters:

image (Image) – Input image.
decimals – Number of decimal places to round to.
device – Device to perform computation on (None = infer from image).

Returns:

Shannon entropy of the image.

Return type:

float

static joint_entropy(image1, image2, decimals=4, device=None)[source]¶

Calculates the joint Shannon entropy of two images.

Parameters:

image1 (Image) – First input image.
image2 (Image) – Second input image.
decimals – Decimal precision.
device – Device for computation (None = infer from image).

Returns:

Joint entropy value.

Return type:

float

static mutual_information(image1, image2, decimals=4, device=None)[source]¶

Computes the mutual information between two images.

Parameters:

image1 (Image) – First image.
image2 (Image) – Second image.
decimals – Decimal precision.
device – Device for computation (None = infer from image).

Returns:

Mutual information value.

Return type:

float

static local_variance(image, output, kernel, device=None)[source]¶

Computes the local variance for each sub-region of the image.

Parameters:

image (Image) – Input image.
output (Image) – Image object to store local variance.
kernel (int | tuple) – Window size for local variance.
device – Device for computation (None = infer from image).

Returns:

The output Image.

Return type:

Image

static variance(image, output, device=None)[source]¶

Computes the global variance of an image.

Parameters:

image (Image) – Input image.
output (Image) – Image object to store the variance as a scalar tensor.
device – Device for computation (None = infer from image).

Returns:

The output Image.

Return type:

Image

FrequencyOperations¶

class medical_image.process.frequency.FrequencyOperations[source]¶

Bases: object

static fft(image, output, device=None)[source]¶

Computes the 2-dimensional Fast Fourier Transform (FFT) of an image.

Parameters:

image (Image) – Input image.
output (Image) – Output image to store the complex FFT result.
device – Device to perform computation on (None = infer from image).

Returns:

The output Image.

Return type:

Image

static inverse_fft(image, output, device=None)[source]¶

Computes the inverse 2-dimensional Fast Fourier Transform (IFFT) of an image.

Parameters:

image (Image) – Input image in the frequency domain (complex tensor).
output (Image) – Output image to store the inverse FFT result.
device – Device to perform computation on (None = infer from image).

Returns:

The output Image.

Return type:

Image

MammographyPreprocessing¶

class medical_image.process.mammography.MammographyPreprocessing[source]¶

Bases: object

Static preprocessing methods for mammogram images.

static breast_mask(image, output=None, device=None)[source]¶

Extract the breast region from a mammogram background.

Uses Otsu thresholding followed by largest connected component selection to produce a binary mask of the breast area.

Reference:

Nguyen et al. (2025), “A Robust Approach for Breast Cancer Classification from DICOM Images,” ETASR Vol. 15, No. 3.

Algorithm:

Apply Otsu threshold to binarize the image.
Find connected components in the binary image.
Select the largest connected component (breast region).
Return the binary mask.

Parameters:

image (Image) – Input mammogram image.
output (Image) – Optional output Image for the masked result. If None, a new InMemoryImage is created.
device – Computation device (None = infer from image).

Returns:

Image with pixel_data set to the breast mask (uint8, 0/1).

Return type:

Image

static apply_breast_mask(image, output=None, device=None)[source]¶

Mask a mammogram so that only the breast region is retained.

Computes the breast mask via breast_mask() and multiplies it with the original pixel data, setting background pixels to zero.

Parameters:

image (Image) – Input mammogram image.
output (Image) – Optional output Image for the masked image.
device – Computation device (None = infer from image).

Returns:

Image with background pixels zeroed out.

Return type:

Image

static dicom_window(image, output=None, window_center=None, window_width=None, device=None)[source]¶

Apply DICOM Window Center / Window Width (WC/WW) transformation.

Maps pixel intensities from the diagnostic window to [0, 255] using the standard DICOM PS3 formula:

output = clamp((pixel - (WC - WW/2)) / WW, 0, 1) * 255

If window_center or window_width are not provided, they are read from the DICOM header (image.dicom_data). If the header also lacks them, the full dynamic range of the image is used.

Parameters:

image (Image) – Input image (ideally a DicomImage with dicom_data).
output (Image) – Optional output Image.
window_center (float | None) – Explicit window center override.
window_width (float | None) – Explicit window width override.
device – Computation device (None = infer from image).

Returns:

Image with pixel_data in [0, 255] float32.

Return type:

Image

static grail_window(image, output=None, n_scales=3, n_orientations=6, delta=300, k_max=3, device=None)[source]¶

GRAIL algorithm for automatic intensity windowing of mammograms.

Finds optimal lower (a) and upper (b) intensity bounds by maximising a perceptual quality metric based on Gabor-filtered mutual information between the 12-bit original and 8-bit windowed representations.

Reference:

Albiol, Corbi & Albiol (2017), “Automatic intensity windowing of mammographic images based on a perceptual metric,” Medical Physics 44(4).

Algorithm:

Compute Gabor filter bank responses on the original image.
Iteratively optimise b (upper bound) then a (lower bound) by evaluating MI between original and windowed Gabor responses.
Refine the search grid each iteration (delta /= 10).
Apply final IW(i, a, b) to produce [0, 255] output.

Parameters:

image (Image) – Input 12-bit mammogram image.
output (Image) – Optional output Image.
n_scales (int) – Number of Gabor frequency scales (default 3).
n_orientations (int) – Number of Gabor orientations (default 6).
delta (int) – Initial search grid spacing (default 300).
k_max (int) – Maximum optimisation iterations (default 3).
device – Computation device (None = infer from image).

Returns:

Image with pixel_data in [0, 255] float32. The optimal a and b values are stored as output.grail_a and output.grail_b.

Return type:

Image

static normalize_bit_depth(image, output=None, bits_stored=None, target_max=255.0, device=None)[source]¶

Normalize pixel values based on the DICOM BitsStored tag.

Automatically detects the bit depth from the DICOM header instead of hardcoding (e.g. 4095). Maps values from [0, 2^bits - 1] to [0, target_max].

Parameters:

image (Image) – Input image (ideally a DicomImage with dicom_data).
output (Image) – Optional output Image.
bits_stored (int | None) – Explicit bit depth override. If None, read from the DICOM header. Falls back to inferring from the maximum pixel value.
target_max (float) – Upper bound of the output range (default 255.0).
device – Computation device (None = infer from image).

Returns:

Image with pixel_data in [0, target_max] float32.

Return type:

Image