glasscut.stain_normalizers package

Submodules

glasscut.stain_normalizers.base module

Base classes for stain normalization.

This module provides abstract base classes and mixins for implementing stain normalization strategies in histopathology image processing.

class glasscut.stain_normalizers.base.StainNormalizer[source]

Bases: ABC

Abstract base class for stain normalization strategies.

Stain normalization is a crucial preprocessing step in digital pathology to reduce color variations caused by staining protocols and imaging conditions.

Subclasses must implement the fit and transform methods.

abstractmethod fit(target_image, **kwargs)[source]

Fit the normalizer to a target image.

Parameters:

  • target_image (Image.Image) – Target reference image for normalization.

  • **kwargs – Additional arguments specific to the normalization method.

Return type:

None

abstractmethod transform(image, **kwargs)[source]

Apply stain normalization to an image.

Parameters:

  • image (Image.Image) – Image to normalize.

  • **kwargs – Additional arguments specific to the normalization method.

Returns:

Normalized image.

Return type:

Image.Image

class glasscut.stain_normalizers.base.TransformerStainMatrixMixin[source]

Bases: object

Mixin implementing fit/transform for matrix-based stain normalizers.

This mixin assumes the subclass implements a stain_matrix method that returns a 3×3 stain matrix.

fit(target_image, **kwargs)[source]

Fit stain normalizer using target image.

Parameters:

  • target_image (Image.Image) – Target image for stain normalization. Can be RGB or RGBA.

  • **kwargs – Additional arguments passed to stain_matrix method. Commonly includes background_intensity (int, default 240).

Return type:

None

transform(image, **kwargs)[source]

Normalize staining of image.

Parameters:

  • image (Image.Image) – Image to normalize. Can be RGB or RGBA.

  • **kwargs – Additional arguments passed to stain_matrix method. Commonly includes background_intensity (int, default 240).

Returns:

Image with normalized stain.

Return type:

Image.Image

abstractmethod stain_matrix(img_rgb, background_intensity=240, **kwargs)[source]

Calculate stain matrix for image.

Parameters:

  • img_rgb (Image.Image) – Input image.

  • background_intensity (int, optional) – Background transmitted light intensity. Default is 240.

  • **kwargs – Additional arguments specific to the normalization method.

Returns:

Stain matrix of image. Shape (3, 3).

Return type:

np.ndarray

glasscut.stain_normalizers.macenko module

class glasscut.stain_normalizers.macenko.MacenkoStainNormalizer[source]

Bases: TransformerStainMatrixMixin, StainNormalizer

Stain normalizer using M. Macenko et al.’s method.

This method performs unsupervised color deconvolution to identify stain vectors, then normalizes stain concentrations to a reference image. It works well for standard H&E stained histopathology images.

The algorithm: 1. Converts image to optical density (OD) space 2. Performs principal component analysis on OD values 3. Identifies stain vectors using angular decomposition 4. Normalizes stain concentrations to match reference

stain_color_map

Mapping of stain names to their normalized OD vectors.

Type:

dict

Examples

>>> from PIL import Image
>>> from glasscut.stain_normalizers import MacenkoStainNormalizer
>>> normalizer = MacenkoStainNormalizer()
>>> ref_image = Image.open("reference.png")
>>> normalizer.fit(ref_image)
>>> test_image = Image.open("test.png")
>>> normalized_image = normalizer.transform(test_image)
stain_color_map = {'dab': array([0.27, 0.57, 0.78]), 'eosin': array([0.07, 0.99, 0.11]), 'hematoxylin': array([0.65, 0.7 , 0.29]), 'null': array([0., 0., 0.])}
__init__()[source]

Initialize MacenkoStainNormalizer.

stain_matrix(img_rgb, background_intensity=240, **kwargs)[source]

Estimate stain matrix using Macenko’s method.

Parameters:

  • img_rgb (PIL.Image.Image) – Input image in RGB or RGBA format.

  • background_intensity (int, optional) – Background transmitted light intensity. Default is 240.

  • **kwargs – Additional keyword arguments.

  • alpha (int, optional) – Minimum angular percentile. Default is 1.

  • beta (float, optional) – Threshold for OD magnitude filtering. Default is 0.15.

  • stains (list of str, optional) – List of stain names in order. Default is ["hematoxylin", "eosin"].

Returns:

Calculated 3×3 stain matrix with stain vectors as columns.

Return type:

np.ndarray

Raises:

glasscut.stain_normalizers.reinhardt module

class glasscut.stain_normalizers.reinhardt.ReinhardtStainNormalizer[source]

Bases: StainNormalizer

Stain normalizer using E. Reinhardt et al.’s color transfer method.

This method normalizes stain appearance by matching the mean and standard deviation of each channel in LAB color space between source and target images. The normalization is performed only on tissue regions.

The algorithm is: 1. Identify tissue using tissue masking 2. Convert to LAB color space 3. Compute per-channel mean and std on tissue 4. Normalize source statistics to match target statistics 5. Convert back to RGB

target_means

Target mean values per LAB channel.

Type:

np.ndarray or None

target_stds

Target standard deviation values per LAB channel.

Type:

np.ndarray or None

Notes

This method is computationally fast and suitable for real-time preview during stain normalization parameter tuning. However, it may not preserve color relationships as well as matrix-based methods for complex stains.

Examples

>>> from PIL import Image
>>> from glasscut.stain_normalizers import ReinhardtStainNormalizer
>>> normalizer = ReinhardtStainNormalizer()
>>> ref_image = Image.open("reference.png")
>>> normalizer.fit(ref_image)
>>> test_image = Image.open("test.png")
>>> normalized_image = normalizer.transform(test_image)
__init__()[source]

Initialize ReinhardtStainNormalizer.

fit(target_image, **kwargs)[source]

Fit stain normalizer using target image.

Parameters:

  • target_image (Image.Image) – Target image for stain normalization. Can be RGB or RGBA.

  • **kwargs – Additional arguments (unused for Reinhardt method).

Return type:

None

transform(image, **kwargs)[source]

Normalize staining of image.

Parameters:

  • image (Image.Image) – Image to normalize. Can be RGB or RGBA.

  • **kwargs – Additional arguments (unused for Reinhardt method).

Returns:

Image with normalized stain.

Return type:

Image.Image

static rgb_to_lab(img_rgb)[source]

Convert RGB image to LAB color space.

Parameters:

img_rgb (Image.Image) – Input image in RGB or RGBA format.

Returns:

Array representation of the image in LAB space.

Return type:

np.ndarray

Raises:

ValueError – If the input image is grayscale.

static lab_to_rgb(img_lab)[source]

Convert LAB image to RGB color space.

Parameters:

img_lab (np.ndarray) – Input image in LAB color space.

Returns:

Image in RGB color space.

Return type:

Image.Image

Module contents

Stain normalization module for histopathology image preprocessing.

This module provides multiple stain normalization methods to standardize color variations in histological images, which is critical for downstream analysis and computer vision tasks.

Available Methods

  • MacenkoStainNormalizer: Unsupervised color deconvolution-based method, well-suited for H&E stained images. Fast and robust.

  • ReinhardtStainNormalizer: Color transfer-based method, computationally efficient and good for interactive normalization.

References

For method details, see the docstrings of individual normalizer classes.

Examples

Basic usage with Macenko normalizer:

>>> from PIL import Image
>>> from glasscut.stain_normalizers import MacenkoStainNormalizer
>>> normalizer = MacenkoStainNormalizer()
>>> reference_image = Image.open("reference.png")
>>> normalizer.fit(reference_image)
>>> test_image = Image.open("test.png")
>>> normalized = normalizer.transform(test_image)

Usage with Reinhardt normalizer:

>>> from glasscut.stain_normalizers import ReinhardtStainNormalizer
>>> normalizer = ReinhardtStainNormalizer()
>>> normalizer.fit(reference_image)
>>> normalized = normalizer.transform(test_image)
class glasscut.stain_normalizers.StainNormalizer[source]

Bases: ABC

Abstract base class for stain normalization strategies.

Stain normalization is a crucial preprocessing step in digital pathology to reduce color variations caused by staining protocols and imaging conditions.

Subclasses must implement the fit and transform methods.

abstractmethod fit(target_image, **kwargs)[source]

Fit the normalizer to a target image.

Parameters:

  • target_image (Image.Image) – Target reference image for normalization.

  • **kwargs – Additional arguments specific to the normalization method.

Return type:

None

abstractmethod transform(image, **kwargs)[source]

Apply stain normalization to an image.

Parameters:

  • image (Image.Image) – Image to normalize.

  • **kwargs – Additional arguments specific to the normalization method.

Returns:

Normalized image.

Return type:

Image.Image

class glasscut.stain_normalizers.TransformerStainMatrixMixin[source]

Bases: object

Mixin implementing fit/transform for matrix-based stain normalizers.

This mixin assumes the subclass implements a stain_matrix method that returns a 3×3 stain matrix.

fit(target_image, **kwargs)[source]

Fit stain normalizer using target image.

Parameters:

  • target_image (Image.Image) – Target image for stain normalization. Can be RGB or RGBA.

  • **kwargs – Additional arguments passed to stain_matrix method. Commonly includes background_intensity (int, default 240).

Return type:

None

transform(image, **kwargs)[source]

Normalize staining of image.

Parameters:

  • image (Image.Image) – Image to normalize. Can be RGB or RGBA.

  • **kwargs – Additional arguments passed to stain_matrix method. Commonly includes background_intensity (int, default 240).

Returns:

Image with normalized stain.

Return type:

Image.Image

abstractmethod stain_matrix(img_rgb, background_intensity=240, **kwargs)[source]

Calculate stain matrix for image.

Parameters:

  • img_rgb (Image.Image) – Input image.

  • background_intensity (int, optional) – Background transmitted light intensity. Default is 240.

  • **kwargs – Additional arguments specific to the normalization method.

Returns:

Stain matrix of image. Shape (3, 3).

Return type:

np.ndarray

class glasscut.stain_normalizers.MacenkoStainNormalizer[source]

Bases: TransformerStainMatrixMixin, StainNormalizer

Stain normalizer using M. Macenko et al.’s method.

This method performs unsupervised color deconvolution to identify stain vectors, then normalizes stain concentrations to a reference image. It works well for standard H&E stained histopathology images.

The algorithm: 1. Converts image to optical density (OD) space 2. Performs principal component analysis on OD values 3. Identifies stain vectors using angular decomposition 4. Normalizes stain concentrations to match reference

stain_color_map

Mapping of stain names to their normalized OD vectors.

Type:

dict

Examples

>>> from PIL import Image
>>> from glasscut.stain_normalizers import MacenkoStainNormalizer
>>> normalizer = MacenkoStainNormalizer()
>>> ref_image = Image.open("reference.png")
>>> normalizer.fit(ref_image)
>>> test_image = Image.open("test.png")
>>> normalized_image = normalizer.transform(test_image)
stain_color_map = {'dab': array([0.27, 0.57, 0.78]), 'eosin': array([0.07, 0.99, 0.11]), 'hematoxylin': array([0.65, 0.7 , 0.29]), 'null': array([0., 0., 0.])}
__init__()[source]

Initialize MacenkoStainNormalizer.

stain_matrix(img_rgb, background_intensity=240, **kwargs)[source]

Estimate stain matrix using Macenko’s method.

Parameters:

  • img_rgb (PIL.Image.Image) – Input image in RGB or RGBA format.

  • background_intensity (int, optional) – Background transmitted light intensity. Default is 240.

  • **kwargs – Additional keyword arguments.

  • alpha (int, optional) – Minimum angular percentile. Default is 1.

  • beta (float, optional) – Threshold for OD magnitude filtering. Default is 0.15.

  • stains (list of str, optional) – List of stain names in order. Default is ["hematoxylin", "eosin"].

Returns:

Calculated 3×3 stain matrix with stain vectors as columns.

Return type:

np.ndarray

Raises:
class glasscut.stain_normalizers.ReinhardtStainNormalizer[source]

Bases: StainNormalizer

Stain normalizer using E. Reinhardt et al.’s color transfer method.

This method normalizes stain appearance by matching the mean and standard deviation of each channel in LAB color space between source and target images. The normalization is performed only on tissue regions.

The algorithm is: 1. Identify tissue using tissue masking 2. Convert to LAB color space 3. Compute per-channel mean and std on tissue 4. Normalize source statistics to match target statistics 5. Convert back to RGB

target_means

Target mean values per LAB channel.

Type:

np.ndarray or None

target_stds

Target standard deviation values per LAB channel.

Type:

np.ndarray or None

Notes

This method is computationally fast and suitable for real-time preview during stain normalization parameter tuning. However, it may not preserve color relationships as well as matrix-based methods for complex stains.

Examples

>>> from PIL import Image
>>> from glasscut.stain_normalizers import ReinhardtStainNormalizer
>>> normalizer = ReinhardtStainNormalizer()
>>> ref_image = Image.open("reference.png")
>>> normalizer.fit(ref_image)
>>> test_image = Image.open("test.png")
>>> normalized_image = normalizer.transform(test_image)
__init__()[source]

Initialize ReinhardtStainNormalizer.

fit(target_image, **kwargs)[source]

Fit stain normalizer using target image.

Parameters:

  • target_image (Image.Image) – Target image for stain normalization. Can be RGB or RGBA.

  • **kwargs – Additional arguments (unused for Reinhardt method).

Return type:

None

transform(image, **kwargs)[source]

Normalize staining of image.

Parameters:

  • image (Image.Image) – Image to normalize. Can be RGB or RGBA.

  • **kwargs – Additional arguments (unused for Reinhardt method).

Returns:

Image with normalized stain.

Return type:

Image.Image

static rgb_to_lab(img_rgb)[source]

Convert RGB image to LAB color space.

Parameters:

img_rgb (Image.Image) – Input image in RGB or RGBA format.

Returns:

Array representation of the image in LAB space.

Return type:

np.ndarray

Raises:

ValueError – If the input image is grayscale.

static lab_to_rgb(img_lab)[source]

Convert LAB image to RGB color space.

Parameters:

img_lab (np.ndarray) – Input image in LAB color space.

Returns:

Image in RGB color space.

Return type:

Image.Image