ImagesHelper Module¶

Provides helper functions for image processing, manipulation, and analysis.

HMB.ImagesHelper.ReadImage(path, newSize=(256, 256))[source]¶

Read and preprocess an image from a given path.

Parameters:

path (str) – The file path to the image.
newSize (tuple) – The desired size to resize the image to (default is (256, 256)).

Returns:

The preprocessed image as a NumPy array.

Return type:

numpy.ndarray

HMB.ImagesHelper.ReadMask(path, newSize=(256, 256))[source]¶

Read and preprocess a mask from a given path.

Parameters:

path (str) – The file path to the mask.
newSize (tuple) – The desired size to resize the mask to (default is (256, 256)).

Returns:

The preprocessed mask as a NumPy array.

Return type:

numpy.ndarray

HMB.ImagesHelper.ReadVolume(caseImgPaths, caseSegPaths, raiseErrors=True)[source]¶

Read and preprocess a 3D volume from a set of 2D slices and their corresponding segmentation masks.

Parameters:

caseImgPaths (list) – List of paths to the 2D slices of the volume.
caseSegPaths (list) – List of paths to the segmentation masks of the slices.

Returns:

A 3D NumPy array representing the preprocessed volume.

Return type:

numpy.ndarray

Raises:

FileNotFoundError – If any of the image or segmentation files are not found.
ValueError – If a cropped image is empty and raiseErrors is set to True.

HMB.ImagesHelper.ReadVolumeSpecificClasses(caseImgPaths, caseSegPaths, specificClasses=[])[source]¶

Read and preprocess a 3D volume from a set of 2D slices and their corresponding segmentation masks.

Parameters:

caseImgPaths (list) – List of file paths to medical image slices in BMP format.
caseSegPaths (list) – List of file paths to segmentation masks matching the slices.
specificClasses (list) – List of specific classes to include in the segmentation. If empty, all classes are included.

Returns:

3D array of preprocessed and aligned medical imaging data.

Return type:

numpy.ndarray

Raises:

FileNotFoundError – If any of the image or segmentation files are not found.
ValueError – If no slices were successfully processed.

HMB.ImagesHelper.ExtractMultipleObjectsFromROI(caseImg, caseSeg, targetSize=(256, 256), cntAreaThreshold=0, sortByX=True)[source]¶

Extracts multiple objects from a region of interest (ROI) in a medical image.

Parameters:

caseImg (numpy.ndarray) – The input medical image.
caseSeg (numpy.ndarray) – The segmentation mask indicating regions of interest.
targetSize (tuple) – The target size for resizing images.
cntAreaThreshold (int) – Minimum contour area to consider for extraction.
sortByX (bool) – Whether to sort extracted regions by their x-coordinate.

Returns:

A list of extracted regions from the image.

Return type:

list

Raises:

ValueError – If the segmentation mask is completely black/empty.

HMB.ImagesHelper.GetEmptyPercentage(img, shape=(256, 256), inverse=False)[source]¶

Calculate the percentage of empty (black or white) regions in an image.

The implementation binarizes the image (Otsu) and computes:

\[\mathrm{empty\_ratio}(I) = \frac{\#\{p:\; B(p) = 255\}}{H \times W} \times 100\%\]

where \(B\) is the binarized image and \(H, W\) are the height and width used for the area calculation.

Parameters:

img (numpy.ndarray) – Input RGB image.
shape (tuple) – Desired shape for calculating the percentage.
inverse (bool) – If True, calculates the percentage of non-empty regions instead.

Returns:

Ratio of empty regions to the total area.

Return type:

float

HMB.ImagesHelper.GetEmptyPercentageHistogram(img, shape=(256, 256), inverse=False, thresholdLow=10, thresholdHigh=245)[source]¶

Calculate the percentage of empty (black or white) regions in an image using histogram analysis.

The method counts near-black and near-white bins and reports their fraction:

\[\mathrm{ratio} = \frac{\sum_{i \in \mathrm{black\_bins}} H(i) + \sum_{i \in \mathrm{white\_bins}} H(i)}{H \times W} \times 100\%\]

where \(H(i)\) is the histogram count for bin \(i\) and \(H, W\) are the image dimensions.

Parameters:

img (numpy.ndarray) – Input RGB image.
shape (tuple) – Desired shape for calculating the percentage.
inverse (bool) – If True, calculates the percentage of non-empty regions instead.
thresholdLow (int) – Threshold for detecting dark regions (default: 10).
thresholdHigh (int) – Threshold for detecting bright regions (default: 245).

Returns:

Ratio of empty regions to the total area.

Return type:

float

HMB.ImagesHelper.ExtractLargestContour(img)[source]¶

Extract the largest contour from an image and create a mask.

Parameters:: img (numpy.ndarray) – Input RGB image.
Returns:: Masked image, contour, mask, and visualization.
Return type:: tuple

HMB.ImagesHelper.MatchTwoImagesViaSIFT(img1, img2, shape=(1024, 1024), tolerance=0.5)[source]¶

Match two images using SIFT (Scale-Invariant Feature Transform) feature detection. This function detects keypoints and computes descriptors for both images, then matches them using a brute-force matcher with a ratio test to filter good matches. The function returns the aligned images, matches, homography matrix, and output shape. This is useful for aligning images that may have different perspectives or scales.

\[\begin{split}H = \begin{bmatrix} h_{11} & h_{12} & h_{13} \\ h_{21} & h_{22} & h_{23} \\ h_{31} & h_{32} & h_{33} \end{bmatrix}\end{split}\]

where:

\(H\) is the homography matrix.
\(h_{ij}\) are the elements of the homography matrix.

Parameters:

img1 (numpy.ndarray) – First input RGB image.
img2 (numpy.ndarray) – Second input RGB image.
shape (tuple) – Desired output shape for the aligned images.
tolerance (float) – Ratio threshold for filtering good matches.

Returns:

Aligned images, matches, homography matrix, and output shape.

Return type:

tuple

HMB.ImagesHelper.MatchTwoImagesViaORB(img1, img2, shape=(1024, 1024), maxNumFeatures=5000, maxGoodMatches=50)[source]¶

Match two images using ORB (Oriented FAST and Rotated BRIEF) feature detection. This function detects keypoints and computes descriptors for both images using ORB, then matches them using a brute-force matcher. The function filters the matches to retain the best ones and computes a homography matrix to align the images. The function returns the aligned images, matches, homography matrix, and output shape.

\[\begin{split}H = \begin{bmatrix} h_{11} & h_{12} & h_{13} \\ h_{21} & h_{22} & h_{23} \\ h_{31} & h_{32} & h_{33} \end{bmatrix}\end{split}\]

where:

\(H\) is the homography matrix.
\(h_{ij}\) are the elements of the homography matrix.

Parameters:

img1 (numpy.ndarray) – First input RGB image.
img2 (numpy.ndarray) – Second input RGB image.
shape (tuple) – Desired output shape for the aligned images.
maxNumFeatures (int) – Maximum number of features to detect.
maxGoodMatches (int) – Maximum number of good matches to use.

Returns:

Aligned images, matches, homography matrix, and output shape.

Return type:

tuple

HMB.ImagesHelper.FreeFormDeformationImproved(imagePath1, imagePath2, gridSize=[10, 10], numberOfHistogramBins=50, samplingPercentage=0.1, learningRate=0.01, numberOfIterations=500, convergenceMinimumValue=1e-06, convergenceWindowSize=10)[source]¶

Perform Free Form Deformation (FFD) using B-spline transformation to align two images.

Parameters:

imagePath1 (str) – Path to the source image.
imagePath2 (str) – Path to the target image.
gridSize (list) – Grid size for the B-spline transform (default is [10, 10]).
numberOfHistogramBins (int) – Number of histogram bins for the metric (default is 50).
samplingPercentage (float) – Percentage of pixels to sample for the metric (default is 0.1).
learningRate (float) – Learning rate for the optimizer (default is 0.01).
numberOfIterations (int) – Maximum number of iterations for the optimizer (default is 500).
convergenceMinimumValue (float) – Convergence threshold for the optimizer (default is 1e-6).
convergenceWindowSize (int) – Window size for convergence determination (default is 10).

Returns:

A tuple containing the original source image, target image, and deformed image.

Return type:

tuple

HMB.ImagesHelper.IgnoreICCFile(imgPath)[source]¶

Reads an image file and ignores ICC profile information. This is useful for ensuring consistent color representation across different platforms.

Parameters:: imgPath (str) – Path to the image file.

HMB.ImagesHelper.CheckIfPNGImageIsNotTruncated(imgPath)[source]¶

Check if a PNG image is not truncated by reading its header. This is useful for validating the integrity of PNG files. Returns True if the image is a valid PNG, False otherwise. If the file cannot be read, it returns False and prints an error message.

Parameters:: imgPath (str) – Path to the PNG image file.
Returns:: True if the image is a valid PNG, False otherwise.
Return type:: bool

HMB.ImagesHelper.FixTruncatedPNGImage(imgPath)[source]¶

Fix a truncated PNG image by appending a valid PNG end chunk. This is useful for recovering partially downloaded or corrupted PNG files.

Parameters:: imgPath (str) – Path to the PNG image file to be fixed.

HMB.ImagesHelper.LoadDicom(filePath, useVOILUT=True)[source]¶

Load a DICOM file and extract its pixel array.

Parameters:: filePath (str) – Path to the DICOM file.
Returns:: The pixel data extracted from the DICOM file.
Return type:: numpy.ndarray

HMB.ImagesHelper.MinMaxNormalization(image, mapToUint8=True)[source]¶

Normalize an image using min-max normalization. The pixel values are scaled to the range [0, 255] if mapToUint8 is True, otherwise they are scaled to the range [0, 1].

The normalization performed is:

\[x' = \frac{x - \min(x)}{\max(x) - \min(x)}\]

and optionally

\[x'' = 255 \times x'\]

Parameters:

image (numpy.ndarray) – Input image.
mapToUint8 (bool) – If True, the output image will be converted to uint8.

Returns:

The normalized image. If mapToUint8 is True, the output will be of type uint8.

Return type:

numpy.ndarray

HMB.ImagesHelper.CalculateCDF(image)[source]¶

Calculate the cumulative distribution function (CDF) of an image.

Let \(H(i)\) be the histogram counts for intensity bin \(i\). The CDF is

\[CDF(k) = \sum_{i=0}^k H(i)\]

and the normalized CDF is \(CDF(k) / CDF(\max)\).

Parameters:

image (numpy.ndarray) – Input image.

Returns:

A tuple containing:

cdfNormalized (numpy.ndarray): The normalized CDF of the image.
bins (numpy.ndarray): The bin values as integers.

Return type:

tuple

HMB.ImagesHelper.CalculateAverageCDFs(sourceFolder, applyThresholding=False, applyNormalization=False, isDicom=True, specialIndex=None)[source]¶

Calculate the average cumulative distribution functions (CDFs) for a set of images in a folder.

Parameters:

sourceFolder (str) – Path to the folder containing the images.
applyThresholding (bool) – Whether to apply thresholding to the images.
applyNormalization (bool) – Whether to normalize the images.
isDicom (bool) – Whether the images are DICOM files.
specialIndex (list or None) – List of indices to process, or None to process all.

Returns:

A tuple containing:

avgCDFs (numpy.ndarray): The average CDFs across all images.
counts (numpy.ndarray): The counts of occurrences for each bin.
maxBins (int): The maximum number of bins used.

Return type:

tuple

HMB.ImagesHelper.PriorInformationTrainingGeneric(image, mask, startingRadius=5, stepRadius=5, maxValue=255)[source]¶

Generate histograms for included and non-included regions at multiple radii for prior information training.

Parameters:

image (numpy.ndarray) – Grayscale image.
mask (numpy.ndarray) – Mask of the included region.
startingRadius (int) – Starting radius for drawing circles.
stepRadius (int) – Step size for increasing the radius.
maxValue (int) – Maximum intensity value.

Returns:

List of dictionaries containing histograms and related information for each radius.

Return type:

list

HMB.ImagesHelper.PriorInformationTestingGeneric(image, histogramsDict, startingSigma=1, stepSigma=1, position=0)[source]¶

Generate probability maps for included and non-included regions using prior histograms.

Parameters:

image (numpy.ndarray) – Grayscale image.
histogramsDict (dict) – Dictionary of histograms for different radii.
startingSigma (int) – Initial sigma for intensity range.
stepSigma (int) – Step size for increasing sigma.
position (int) – Progress bar position for tqdm.

Returns:

A tuple containing:

sumIncludedMaps (numpy.ndarray): The summed included probability map.
sumNonIncludedMaps (numpy.ndarray): The summed non-included probability map.

Return type:

tuple

HMB.ImagesHelper.PriorInformationGeneric(image, mask, startingRadius=10, stepRadius=10, startingSigma=1, stepSigma=1)[source]¶

Generate lists of probability maps for included and non-included regions at multiple radii.

Parameters:

image (numpy.ndarray) – Grayscale image.
mask (numpy.ndarray) – Mask of the included region.
startingRadius (int) – Starting radius for drawing circles.
stepRadius (int) – Step size for increasing the radius.
startingSigma (int) – Initial sigma for intensity range.
stepSigma (int) – Step size for increasing sigma.

Returns:

A tuple containing:

listOfIncludedMaps (list): List of included probability maps.
listOfNonIncludedMaps (list): List of non-included probability maps.

Return type:

tuple

HMB.ImagesHelper.ReadRGBA(imgPath)[source]¶

Read an image from a file and convert it to RGBA format.

Parameters:: imgPath (str) – Path to the image file.
Returns:: The image in RGBA format.
Return type:: numpy.ndarray

HMB.ImagesHelper.SaveFigureRGBA(fig, savePath, dpi=720)[source]¶

Save a Matplotlib figure as a PNG image with RGBA format.

Parameters:

fig (matplotlib.figure.Figure) – The Matplotlib figure to save.
savePath (str) – Path to save the PNG image.
dpi (int) – Dots per inch for the saved image.

HMB.ImagesHelper.ComputeAndPlotDeformationFieldViaFarneback(img1, img2, step=10, pyrScale=0.5, levels=3, winsize=15, iterations=3, polyN=5, polySigma=1.2, flags=0, backgroundAlpha=0.7, density=1.5, addGradientBar=False, sourceTitle='Source Image', targetTitle='Target Image', optFlowTitle='Deformation Field via Farneback Optical Flow', showPlot=True, savePlotPath=None, cmap=<matplotlib.colors.ListedColormap object>, fontSize=12, returnFigure=False)[source]¶

Compute a dense deformation field between two images using Farneback optical flow and display a stream plot of the displacement vectors over the source image.

The computed dense optical flow field flow has two channels per-pixel:

\[flow(x,y) = [u(x,y), v(x,y)]\]

where \(u\) and \(v\) are horizontal and vertical displacement components. The displacement magnitude is

\[\mathrm{mag}(x,y) = \sqrt{u(x,y)^2 + v(x,y)^2}.\]

Parameters:

img1 (numpy.ndarray) – Source image as a NumPy array.
img2 (numpy.ndarray) – Target image as a NumPy array.
step (int) – Subsampling step for plotting vectors to improve readability.
pyrScale (float) – Pyramid scale parameter for Farneback optical flow.
levels (int) – Number of pyramid levels for Farneback optical flow.
winsize (int) – Window size for Farneback optical flow.
iterations (int) – Number of iterations for Farneback optical flow.
polyN (int) – Size of the pixel neighborhood for polynomial expansion in Farneback optical flow.
polySigma (float) – Standard deviation of the Gaussian used to smooth derivatives in Farneback optical flow.
flags (int) – Flags for Farneback optical flow computation.
backgroundAlpha (float) – Alpha blending for the background image in the plot.
density (float) – Density parameter passed to plt.streamplot for vector density.
addGradientBar (bool) – If True, adds a gradient color bar to the plot.
sourceTitle (str) – Title for the source image subplot.
targetTitle (str) – Title for the target image subplot.
optFlowTitle (str) – Title of the optical flow plot.
showPlot (bool) – If True, displays the plot.
savePlotPath (str or None) – If provided, saves the plot to the specified path.
cmap (matplotlib.colors.Colormap) – Colormap for the plot.
fontSize (int) – Font size for plot labels.
returnFigure (bool) – If True, returns the figure object.

Returns:

Deformation field (H x W x 2) where channels are horizontal and vertical displacements.

Return type:

numpy.ndarray

HMB.ImagesHelper.OverlayHeatmapOnImage(origPIL, heatmap, alpha=0.4, cmap=<matplotlib.colors.LinearSegmentedColormap object>)[source]¶

Overlay heatmap (2D array) over a PIL Image and return a PIL Image.

Parameters:

origPIL (PIL.Image) – original RGB image.
heatmap (numpy.ndarray) – heatmap 2D array.
alpha (float) – overlay alpha.
cmap (matplotlib.colors.Colormap) – colormap to map heatmap values to colors.

Returns.: overlayPIL (PIL.Image): image with heatmap overlay.

HMB.ImagesHelper.AddGaussianNoise(img, sigma=10.0, seed=None)[source]¶

Add additive Gaussian noise to an image. sigma is the standard deviation of the noise (e.g., 10.0). Deterministic when seed is provided.

The model is:

\[I_{noisy} = I + \mathcal{N}(0, \sigma^2)\]

applied per-pixel and per-channel.

Parameters:

img (PIL.Image) – Input image.
sigma (float) – Standard deviation of the Gaussian noise.
seed (int or None) – Seed for random number generator for reproducibility.

Returns:

Noisy image.

Return type:

PIL.Image

HMB.ImagesHelper.ApplyJPEGCompression(img, quality=75)[source]¶

Apply JPEG compression artifact simulation at given quality level. Quality ranges from 1 (worst) to 95 (best).

Parameters:

img (PIL.Image) – Input image.
quality (int) – JPEG quality level (1 to 95).

Returns:

Compressed image.

Return type:

PIL.Image

HMB.ImagesHelper.AddSpeckleNoise(img, var=0.01, seed=None)[source]¶

Apply multiplicative speckle noise. var is the variance (e.g., 0.01). Deterministic when seed provided.

The model is multiplicative noise:

\[I_{noisy} = I \times (1 + N), \quad N \sim \mathcal{N}(0, \mathrm{var})\]

Parameters:

img (PIL.Image) – Input image.
var (float) – Variance of the speckle noise.
seed (int or None) – Seed for random number generator for reproducibility.

Returns:

Noisy image.

Return type:

PIL.Image

HMB.ImagesHelper.AddSaltPepperNoise(img, amount=0.05, saltVsPepper=0.5, seed=None)[source]¶

Apply salt & pepper noise. amount is fraction of pixels to alter (0..1). saltVsPepper is fraction of salt vs pepper (0..1). Deterministic when seed provided.

Fractional model:

\[\begin{split}\mathrm{salt} = \mathrm{round}(amount \times saltVsPepper \times H \times W)\\ \mathrm{pepper} = \mathrm{round}(amount \times (1 - saltVsPepper) \times H \times W)\end{split}\]

where \(H,W\) are image height and width.

Parameters:

img (PIL.Image) – Input image.
amount (float) – Fraction of pixels to alter with noise.
saltVsPepper (float) – Fraction of salt vs pepper noise.
seed (int or None) – Seed for random number generator for reproducibility.

Returns:

Noisy image.

Return type:

PIL.Image

HMB.ImagesHelper.ChangeBrightness(img, factor=1.2)[source]¶

Adjust image brightness by multiplicative factor.

Parameters:

img (PIL.Image) – Input image.
factor (float) – Brightness adjustment factor.

Returns:

Brightness-adjusted image.

Return type:

PIL.Image

HMB.ImagesHelper.ChangeContrast(img, factor=1.2)[source]¶

Adjust image contrast by multiplicative factor.

Parameters:

img (PIL.Image) – Input image.
factor (float) – Contrast adjustment factor.

Returns:

Contrast-adjusted image.

Return type:

PIL.Image

HMB.ImagesHelper.AddShotNoise(img, scale=1.0, seed=None)[source]¶

Simulate shot (Poisson) noise. Higher scale means more photons and less relative noise.

Model (per-pixel Poisson sampling):

\[C \sim \mathrm{Poisson}(I \times s),\quad I_{noisy} = \frac{C}{s}\]

where \(s\) is the scale factor controlling photon counts.

Parameters:

img (PIL.Image) – Input image.
scale (float) – Scale factor for photon counts.
seed (int or None) – Seed for random number generator for reproducibility.

Returns:

Noisy image.

Return type:

PIL.Image

HMB.ImagesHelper.DownscaleImage(img, level)[source]¶

Downscale image to simulate lossy resolution reduction. Level > 1.0 indicates downscale factor; level between 0 and 1.0 indicates inverse scale (e.g., 0.5 means downscale by 2x).

Parameters:

img (PIL.Image) – Input image.
level (float) – Downscaling severity.

Returns:

Downscaled image.

Return type:

PIL.Image

HMB.ImagesHelper.OccludeImage(img, level)[source]¶

Occlude center of image with black square proportional to level. Level is fraction of image area to occlude (0.0 to 0.9).

Parameters:

img (PIL.Image) – Input image.
level (float) – Fraction of image area to occlude.

Returns:

Occluded image.

Return type:

PIL.Image

HMB.ImagesHelper.ColorJitter(img, level)[source]¶

Apply deterministic color jitter based on level. Level controls brightness, contrast, and saturation.

Parameters:

img (PIL.Image) – Input image.
level (float) – Jitter severity.

Returns:

Jittered image.

Return type:

PIL.Image

HMB.ImagesHelper.FogImage(img, level)[source]¶

Simulate fog by blending image with white translucent layer. Level controls fog density.

Parameters:

img (PIL.Image) – Input image.
level (float) – Fog density level.

Returns:

Foggy image.

Return type:

PIL.Image

HMB.ImagesHelper.PixelateImage(img, level)[source]¶

Pixelate image by downscaling and upscaling with nearest neighbor. Level controls pixelation block size.

Parameters:

img (PIL.Image) – Input image.
level (float) – Pixelation severity.

Returns:

Pixelated image.

Return type:

PIL.Image

HMB.ImagesHelper.SaturateImage(img, level)[source]¶

Adjust image saturation by multiplicative factor. Level controls saturation change.

Parameters:

img (PIL.Image) – Input image.
level (float) – Saturation adjustment level.

Returns:

Saturation-adjusted image.

Return type:

PIL.Image

HMB.ImagesHelper.ClusteringImageKMeans(sample, kmeans, noChannels=4)[source]¶

Use a pre-fitted KMeans model to cluster an image.

Parameters:

sample (numpy.ndarray) – Input image to be clustered.
kmeans (KMeans) – Pre-fitted KMeans model.
noChannels (int) – Number of channels in the image. Default is 4.

Returns:

Grayscale image where each pixel value corresponds to its cluster label.

Return type:

numpy.ndarray

HMB.ImagesHelper.FitGlobalKMeans(heDeformedFolderPath, targetSize=(256, 256), numClusters=3, noChannels=4, sampleSize=None, modelPath='Global_KMeans_Model.p', nInit=10, batchSize=1000, randomState=42, verbose=False)[source]¶

Fit a global KMeans model on all image pixels and save it.

Parameters:

heDeformedFolderPath (str) – Path to the folder containing deformed HE images.
targetSize (tuple) – Target size to resize images for fitting. Default is (256, 256).
numClusters (int) – Number of clusters for KMeans. Default is 3.
noChannels (int) – Number of channels in the images. Default is 4.
sampleSize (int or None) – Number of pixels to sample from each image. If None, use all pixels. Default is None.
modelPath (str) – Path to save the fitted KMeans model. Default is “Global_KMeans_Model.p”.
nInit (int) – Number of time the k-means algorithm will be run with different centroid seeds. Default is 10.
batchSize (int) – Size of the mini-batches for MiniBatchKMeans. Default is 1000.
randomState (int) – Random seed for reproducibility. Default is 42.

Returns:

Fitted KMeans model.

Return type:

sklearn.cluster.KMeans

class HMB.ImagesHelper.MultiChannelFeatureExtractor(featureConfig=None)[source]¶

Bases: object

Class for extracting various image features such as HOG, K-Means clustering, Sobel edges, and Local Binary Patterns (LBP). The class allows configuration of feature extraction parameters and provides methods to compute each feature layer from an input RGB image.

Parameters:: featureConfig (dict, optional) – A dictionary containing configuration parameters for feature extraction. If None, default parameters will be used.

Features:

HOG (Histogram of Oriented Gradients): Extracts gradient orientation histograms from the image.
K-Means Clustering: Segments the image into clusters based on color similarity.
Sobel Edge Detection: Computes edge magnitude using the Sobel operator.
Local Binary Patterns (LBP): Captures texture information by comparing pixel intensities.
Hematoxylin Stain Separation (HED): Separates stains using the Hematoxylin-Eosin-DAB color space conversion matrix.
Hematoxylin Stain: Extracts the Hematoxylin channel using color deconvolution.
Gabor Filter: Extracts frequency and orientation information from the image.
Canny Edge Detection: Detects edges using the Canny algorithm.
Local Entropy: Measures the randomness or complexity of pixel intensities in local regions.
Difference of Gaussians (DoG): Enhances edges by subtracting two Gaussian blurred versions of the image.
Multi-Orientation Gabor Filter: Applies Gabor filters at multiple orientations to capture texture information.
Eosin Stain: Extracts the Eosin channel using color deconvolution.
Laplacian Edge and Blob Detection: Computes the Laplacian of the image to detect edges and blobs.
Frangi Vesselness: Enhances vessel-like and tube-like structures using the Frangi filter.
Sato Tube-like Structure: Enhances tube-like structures using the Sato filter.
Local Variance: Computes the variance of pixel intensities in local neighborhoods.
Hue: Extracts the Hue channel from the HSV color space.
Saturation: Extracts the Saturation channel from the HSV color space.
Lightness: Extracts the Lightness channel from the CIELAB color space.
Green-Red (A Channel): Extracts the Green-Red channel from the CIELAB color space.
Blue-Yellow (B Channel): Extracts the Blue-Yellow channel from the CIELAB color space.

Examples

from skimage.io import imread
from HMB.ImagesHelper import MultiChannelFeatureExtractor

# Define the file path for the input histopathology image.
imgPath = r"path/to/your/input/image.png"
# Define the output file paths for the multi-channel TIFF and visualization PNG.
outputPath = r"path/to/your/output/image.tiff"
visualizationPath = r"path/to/your/output/image.png"
# Instantiate the feature extractor class.
extractorInstance = MultiChannelFeatureExtractor()
# Load the test image from the specified file path.
loadedImage = extractorInstance.LoadImageFromPath(imgPath)
# Define the optimal three-channel feature list for breast cancer histopathology.
optimalFeatureList = ["Frangi", "MultiGabor", "LocalVariance"]
# Generate the custom multi-channel image using the recommended optimal feature list.
optimalStackedImage = extractorInstance.GenerateCustomFeatureImage(loadedImage, optimalFeatureList)
# Save the full three-channel data as a scientific TIFF file.
extractorInstance.SaveMultiChannelImage(optimalStackedImage, outputPath)
# Save the first three channels as a standard PNG for visual inspection.
extractorInstance.SaveVisualizationImage(optimalStackedImage, visualizationPath)
# Extract and visualize the specific feature layers from the loaded image.
featureLayerDict = extractorInstance.ExtractSpecificFeatureLayers(loadedImage, optimalFeatureList)
extractorInstance.PlotFeatureLayers(loadedImage, featureLayerDict)

# Read the saved TIFF file to verify the integrity of the saved data.
loadedTiffImage = tifffile.imread(outputPath)
# Print the shape of the loaded TIFF image to confirm it matches the expected dimensions.
print("The shape of the loaded TIFF image is:", loadedTiffImage.shape)

Initialize the MultiChannelFeatureExtractor with optional feature configuration.

Parameters:: featureConfig (dict, optional) – A dictionary containing configuration parameters for feature extraction. If None, default parameters will be used.

Feature configuration parameters include:

“PixelsPerCell”: Tuple[int, int], default (8, 8). # Default value for HOG feature extraction.
“CellsPerBlock”: Tuple[int, int], default (3, 3). # Default value for HOG feature extraction.
“Orientations”: int, default 9. # Default value for HOG feature extraction.
“KMeansClusters”: int, default 5. # Default number of clusters for K-Means clustering.
“LbpRadius”: int, default 3. # Default radius for Local Binary Patterns (LBP) feature extraction.
“LbpPoints”: int, default 24. # Default number of points for Local Binary Patterns (LBP) feature extraction.
“GaborFrequency”: float, default 0.1. # Default frequency for Gabor filter feature extraction.
“GaborTheta”: float, default 0.0. # Default orientation for Gabor filter feature extraction.
“CannySigma”: float, default 1.0. # Default sigma value for Canny edge detection.
“EntropyRadius”: int, default 5. # Default radius for local entropy feature extraction.
“DoGLowSigma”: float, default 1. # Default low sigma value for Difference of Gaussians (DoG) feature extraction.
“DoGHighSigma”: float, default 3. # Default high sigma value for Difference of Gaussians (DoG) feature extraction.
“GaborThetaList”: List[float], default [0.0, 0.785, 1.57, 2.355]. # Default list of orientations for multi-orientation Gabor filter feature extraction.
“LocalVarianceSize”: int, default 15. # Default size for local variance feature extraction.

__init__(featureConfig=None)[source]¶

Initialize the MultiChannelFeatureExtractor with optional feature configuration.

Parameters:: featureConfig (dict, optional) – A dictionary containing configuration parameters for feature extraction. If None, default parameters will be used.

Feature configuration parameters include:

“PixelsPerCell”: Tuple[int, int], default (8, 8). # Default value for HOG feature extraction.
“CellsPerBlock”: Tuple[int, int], default (3, 3). # Default value for HOG feature extraction.
“Orientations”: int, default 9. # Default value for HOG feature extraction.
“KMeansClusters”: int, default 5. # Default number of clusters for K-Means clustering.
“LbpRadius”: int, default 3. # Default radius for Local Binary Patterns (LBP) feature extraction.
“LbpPoints”: int, default 24. # Default number of points for Local Binary Patterns (LBP) feature extraction.
“GaborFrequency”: float, default 0.1. # Default frequency for Gabor filter feature extraction.
“GaborTheta”: float, default 0.0. # Default orientation for Gabor filter feature extraction.
“CannySigma”: float, default 1.0. # Default sigma value for Canny edge detection.
“EntropyRadius”: int, default 5. # Default radius for local entropy feature extraction.
“DoGLowSigma”: float, default 1. # Default low sigma value for Difference of Gaussians (DoG) feature extraction.
“DoGHighSigma”: float, default 3. # Default high sigma value for Difference of Gaussians (DoG) feature extraction.
“GaborThetaList”: List[float], default [0.0, 0.785, 1.57, 2.355]. # Default list of orientations for multi-orientation Gabor filter feature extraction.
“LocalVarianceSize”: int, default 15. # Default size for local variance feature extraction.

LoadImageFromPath(inputImagePath)[source]¶

Load an RGB image from the specified file path and return it as a NumPy array.

Parameters:: inputImagePath (str) – The file path to the input RGB image.
Returns:: The loaded RGB image as a NumPy array.
Return type:: numpy.ndarray

ComputeHogLayer(inputRgbImage)[source]¶

Compute the Histogram of Oriented Gradients (HOG) layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized HOG feature layer.
Return type:: numpy.ndarray

FitClusteringModel(referenceImage)[source]¶

Fit the K-Means clustering model on a reference image to establish consistent cluster centers for the dataset.

Parameters:: referenceImage (numpy.ndarray or str) – The reference RGB image array or file path to the image.

ComputeClusteringLayer(inputRgbImage)[source]¶

Compute the K-Means clustering layer from the input RGB image using the fitted model.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized clustering feature layer.
Return type:: numpy.ndarray

ComputeEdgeLayer(inputRgbImage)[source]¶

Compute the Sobel edge detection layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized Sobel edge feature layer.
Return type:: numpy.ndarray

ComputeTextureLayer(inputRgbImage)[source]¶

Compute the Local Binary Patterns (LBP) texture layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized LBP texture feature layer.
Return type:: numpy.ndarray

ComputeStainLayer(inputRgbImage)[source]¶

Compute the Hematoxylin stain separation layer using the HED color space. Suitable with Hematoxylin-Eosin-DAB stained images in digital pathology.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized stain separation feature layer.
Return type:: numpy.ndarray

ComputeHematoxylinLayer(inputRgbImage)[source]¶

Compute the Hematoxylin stain layer using color deconvolution. Suitable with Hematoxylin-Eosin-DAB stained images in digital pathology.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized Hematoxylin feature layer.
Return type:: numpy.ndarray

ComputeGaborLayer(inputRgbImage)[source]¶

Compute the Gabor filter texture layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized Gabor filter feature layer.
Return type:: numpy.ndarray

ComputeCannyLayer(inputRgbImage)[source]¶

Compute the Canny edge detection layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The Canny edge feature layer.
Return type:: numpy.ndarray

ComputeEntropyLayer(inputRgbImage)[source]¶

Compute the local entropy texture layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized local entropy feature layer.
Return type:: numpy.ndarray

ComputeDoGLayer(inputRgbImage)[source]¶

Compute the Difference of Gaussians (DoG) blob detection layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized DoG feature layer.
Return type:: numpy.ndarray

ComputeMultiGaborLayer(inputRgbImage)[source]¶

Compute the multi-orientation Gabor texture layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized multi-orientation Gabor feature layer.
Return type:: numpy.ndarray

ComputeEosinLayer(inputRgbImage)[source]¶

Compute the Eosin stain layer using color deconvolution. Suitable with Hematoxylin-Eosin-DAB stained images in digital pathology.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized Eosin feature layer.
Return type:: numpy.ndarray

ComputeLaplacianLayer(inputRgbImage)[source]¶

Compute the Laplacian edge and blob detection layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized Laplacian feature layer.
Return type:: numpy.ndarray

ComputeFrangiLayer(inputRgbImage)[source]¶

Compute the Frangi vesselness and tube-like structure layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized Frangi feature layer.
Return type:: numpy.ndarray

ComputeSatoLayer(inputRgbImage)[source]¶

Compute the Sato tube-like structure layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized Sato feature layer.
Return type:: numpy.ndarray

ComputeLocalVarianceLayer(inputRgbImage)[source]¶

Compute the local variance texture layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized local variance feature layer.
Return type:: numpy.ndarray

ComputeHueLayer(inputRgbImage)[source]¶

Compute the Hue color space layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized Hue feature layer.
Return type:: numpy.ndarray

ComputeSaturationLayer(inputRgbImage)[source]¶

Compute the Saturation color space layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized Saturation feature layer.
Return type:: numpy.ndarray

ComputeLightnessLayer(inputRgbImage)[source]¶

Compute the Lightness color space layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized Lightness feature layer.
Return type:: numpy.ndarray

ComputeAChannelLayer(inputRgbImage)[source]¶

Compute the Green-Red (A) color space layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized A channel feature layer.
Return type:: numpy.ndarray

ComputeBChannelLayer(inputRgbImage)[source]¶

Compute the Blue-Yellow (B) color space layer from the input RGB image.

Parameters:: inputRgbImage (numpy.ndarray) – The input RGB image array.
Returns:: The normalized B channel feature layer.
Return type:: numpy.ndarray

GenerateCustomFeatureImage(inputRgbImage, featureList)[source]¶

Generate a custom multi-channel image based on a list of requested features.

Parameters:

inputRgbImage (numpy.ndarray) – The input RGB image array.
featureList (list) – A list of feature names to extract and stack.

Feature names can include:

“R”, “G”, “B”: Individual RGB channels.
“Hog”: Histogram of Oriented Gradients.
“Clustering”: K-Means clustering.
“Edge”: Sobel edge detection.
“Texture”: Local Binary Patterns.
“Stain”: Hematoxylin stain separation.
“Hematoxylin”: Hematoxylin stain layer.
“Gabor”: Gabor filter texture.
“Canny”: Canny edge detection.
“Entropy”: Local entropy texture.
“DoG”: Difference of Gaussians blob detection.
“MultiGabor”: Multi-orientation Gabor texture.
“Eosin”: Eosin stain layer.
“Laplacian”: Laplacian edge and blob detection.
“Frangi”: Frangi vesselness and tube-like structure.
“Sato”: Sato tube-like structure.
“LocalVariance”: Local variance texture.
“Hue”: Hue color space.
“Saturation”: Saturation color space.
“Lightness”: Lightness color space.
“AChannel”: Green-Red (A) color space.
“BChannel”: Blue-Yellow (B) color space.

Returns:: The generated custom multi-channel image array.
Return type:: numpy.ndarray

ExtractAllFeatureLayers(inputRgbImage, isDigitalPathologyImage=False)[source]¶

Extract all configured feature layers from the input RGB image.

Parameters:

inputRgbImage (numpy.ndarray) – The input RGB image array.
isDigitalPathologyImage (bool) – Flag indicating if the image is a digital pathology image.

Returns:

A dictionary containing all extracted feature layers.

Return type:

dict

ExtractSpecificFeatureLayers(inputRgbImage, featureList)[source]¶

Extract specific feature layers from the input RGB image based on a provided list of features.

Parameters:

inputRgbImage (numpy.ndarray) – The input RGB image array.
featureList (list) – A list of feature names to extract.

Feature names can include:

“R”, “G”, “B”: Individual RGB channels.
“Hog”: Histogram of Oriented Gradients.
“Clustering”: K-Means clustering.
“Edge”: Sobel edge detection.
“Texture”: Local Binary Patterns.
“Stain”: Hematoxylin stain separation.
“Hematoxylin”: Hematoxylin stain layer.
“Gabor”: Gabor filter texture.
“Canny”: Canny edge detection.
“Entropy”: Local entropy texture.
“DoG”: Difference of Gaussians blob detection.
“MultiGabor”: Multi-orientation Gabor texture.
“Eosin”: Eosin stain layer.
“Laplacian”: Laplacian edge and blob detection.
“Frangi”: Frangi vesselness and tube-like structure.
“Sato”: Sato tube-like structure.
“LocalVariance”: Local variance texture.
“Hue”: Hue color space.
“Saturation”: Saturation color space.
“Lightness”: Lightness color space.
“AChannel”: Green-Red (A) color space.
“BChannel”: Blue-Yellow (B) color space.

Returns:: A dictionary containing the extracted feature layers.
Return type:: dict

StackFeatureLayers(inputRgbImage, featureLayerDict)[source]¶

Stack the original image and the extracted feature layers into a single multi-channel array.

Parameters:

inputRgbImage (numpy.ndarray) – The input RGB image array.
featureLayerDict (dict) – A dictionary containing the extracted feature layers.

Returns:

The final multi-channel stacked image array.

Return type:

numpy.ndarray

PlotFeatureLayers(inputRgbImage, featureLayerDict, gridColumns=3)[source]¶

Plot the original image and all feature layers in a grid layout.

Parameters:

inputRgbImage (numpy.ndarray) – The input RGB image array.
featureLayerDict (dict) – A dictionary containing the extracted feature layers.
gridColumns (int) – The number of columns in the grid layout for plotting.

SaveMultiChannelImage(imageArray, outputFilePath)[source]¶

Save the multi-channel image array to disk as a TIFF file.

Parameters:

imageArray (numpy.ndarray) – The multi-channel image array to save.
outputFilePath (str) – The file path to save the TIFF image.

SaveVisualizationImage(imageArray, visualizationPath)[source]¶

Visualize and save the first three channels of the image array as an RGB image.

Parameters:

imageArray (numpy.ndarray) – The multi-channel image array.
visualizationPath (str) – The file path to save the visualization image.