Image pre-processing

Functions

Collection of pre-processing methods for aligning images

valis.preprocessing.create_tissue_mask_from_multichannel(img, kernel_size=3)

Get foreground of multichannel imaage

valis.preprocessing.create_tissue_mask_from_rgb(img, brightness_q=0.99, kernel_size=3, gray_thresh=0.075, light_gray_thresh=0.875, dark_gray_thresh=0.7)

Create mask that only covers tissue

Also remove dark regions on the edge of the slide, which could be artifacts

Parameters:

• grey_thresh (float) – Colorfulness values (from JCH) below this are considered “grey”, and thus possibly dirt, hair, coverslip edges, etc…

• light_gray_thresh (float) – Upper limit for light gray

• dark_gray_thresh (float) – Upper limit for dark gray

Returns:

• tissue_mask (ndarray) – Mask covering tissue

• concave_tissue_mask (ndarray) – Similar to tissue_mask, but each region is replaced by a concave hull. Covers more area

valis.preprocessing.get_luminosity(img, **kwargs)

Get luminosity of an RGB image

Converts and RGB image to the CAM16-UCS colorspace, extracts the luminosity, and then scales it between 0-255

Parameters:

img (ndarray) – RGB image

Returns:

lum – CAM16-UCS luminosity

Return type:

ndarray

valis.preprocessing.match_histograms(src_image, ref_histogram, bins=256)

Source: https://automaticaddison.com/how-to-do-histogram-matching-using-opencv/

This method matches the source image histogram to the reference signal :param image src_image: The original source image :param image ref_image: The reference image :return: image_after_matching :rtype: image (array)

valis.preprocessing.match_histograms(src_image, ref_histogram, bins=256)

Source: https://automaticaddison.com/how-to-do-histogram-matching-using-opencv/

This method matches the source image histogram to the reference signal :param image src_image: The original source image :param image ref_image: The reference image :return: image_after_matching :rtype: image (array)

valis.preprocessing.norm_img_stats(img, target_stats, mask=None)

Normalize an image

Image will be normalized to have same stats as target_stats

Based on method in “A nonlinear mapping approach to stain normalization in digital histopathology images using image-specific color deconvolution.”, Khan et al. 2014

Assumes that img values range between 0-255

valis.preprocessing.norm_img_stats(img, target_stats, mask=None)

Normalize an image

Image will be normalized to have same stats as target_stats

Based on method in “A nonlinear mapping approach to stain normalization in digital histopathology images using image-specific color deconvolution.”, Khan et al. 2014

Assumes that img values range between 0-255

valis.preprocessing.standardize_colorfulness(img, c=0.2, h=0)

Give image constant colorfulness and hue

Image is converted to cylindrical CAM-16UCS assigned a constant hue and colorfulness, and then coverted back to RGB.

Parameters:

• img (ndarray) – Image to be processed

• c (int) – Colorfulness

• h (int) – Hue, in radians (-pi to pi)

Returns:

rgb2 – img with constant hue and colorfulness

Return type:

ndarray

Classes

Base ImageProcesser

class valis.preprocessing.ImageProcesser(image, src_f, level, series)

Process images for registration

ImageProcesser sub-classes processes images to single channel images which are then used in image registration.

Each ImageProcesser is initialized with an image, the path to the image, the pyramid level, and the series number. These values will be set during the registration process.

ImageProcesser must also have a process_image method, which is called during registration. As ImageProcesser has the image and and its relevant information (filename, level, series) as attributes, it should be able to access and modify the image as needed. However, one can also pass extra args and kwargs to process_image. As such, process_image will also need to accept args and kwargs.

image

Image to be processed

Type:

ndarray

src_f

Path to slide/image.

Type:

str

level

Pyramid level to be read.

Type:

int

series

The series to be read.

Type:

int

__init__(image, src_f, level, series)

Parameters:

• image (ndarray) – Image to be processed

• src_f (str) – Path to slide/image.

• level (int) – Pyramid level to be read.

• series (int) – The series to be read.

process_image(*args, **kwargs)

Pre-process image for registration

Pre-process image for registration. Processed image should be a single channel uint8 image.

Returns:

processed_img – Single channel processed copy of image

Return type:

ndarray

ChannelGetter

class valis.preprocessing.ChannelGetter(image, src_f, level, series, *args, **kwargs)

Bases: ImageProcesser

Select channel from image

__init__(image, src_f, level, series, *args, **kwargs)

Parameters:

• image (ndarray) – Image to be processed

• src_f (str) – Path to slide/image.

• level (int) – Pyramid level to be read.

• series (int) – The series to be read.

process_image(channel='dapi', adaptive_eq=True, *args, **kwaargs)

Pre-process image for registration

Pre-process image for registration. Processed image should be a single channel uint8 image.

Returns:

processed_img – Single channel processed copy of image

Return type:

ndarray

ColorfulStandardizer

class valis.preprocessing.ColorfulStandardizer(image, src_f, level, series, *args, **kwargs)

Bases: ImageProcesser

Standardize the colorfulness of the image

__init__(image, src_f, level, series, *args, **kwargs)

Parameters:

• image (ndarray) – Image to be processed

• src_f (str) – Path to slide/image.

• level (int) – Pyramid level to be read.

• series (int) – The series to be read.

process_image(c=0.2, invert=True, adaptive_eq=False, *args, **kwargs)

Pre-process image for registration

Pre-process image for registration. Processed image should be a single channel uint8 image.

Returns:

processed_img – Single channel processed copy of image

Return type:

ndarray

StainFlattener

class valis.preprocessing.StainFlattener(image, src_f, level, series, *args, **kwargs)

Bases: ImageProcesser

__init__(image, src_f, level, series, *args, **kwargs)

Parameters:

• image (ndarray) – Image to be processed

• src_f (str) – Path to slide/image.

• level (int) – Pyramid level to be read.

• series (int) – The series to be read.

process_image(n_colors=100, q=95, with_mask=True, adaptive_eq=True, max_colors=100)

Parameters:

• n_colors (int) – Number of colors to use for deconvolution. If n_stains = -1, then the number of colors will be estimated using the K-means “elbow method”.

• max_colors (int) – If n_colors = -1, this value sets the maximum number of color clusters

BgColorDistance

class valis.preprocessing.BgColorDistance(image, src_f, level, series, *args, **kwargs)

Bases: ImageProcesser

Calculate distance between each pixel and the background color

__init__(image, src_f, level, series, *args, **kwargs)

Parameters:

• image (ndarray) – Image to be processed

• src_f (str) – Path to slide/image.

• level (int) – Pyramid level to be read.

• series (int) – The series to be read.

process_image(brightness_q=0.99, *args, **kwargs)

Pre-process image for registration

Pre-process image for registration. Processed image should be a single channel uint8 image.

Returns:

processed_img – Single channel processed copy of image

Return type:

ndarray

Luminosity

class valis.preprocessing.Luminosity(image, src_f, level, series, *args, **kwargs)

Bases: ImageProcesser

Get luminosity of an RGB image

__init__(image, src_f, level, series, *args, **kwargs)

Parameters:

• image (ndarray) – Image to be processed

• src_f (str) – Path to slide/image.

• level (int) – Pyramid level to be read.

• series (int) – The series to be read.

process_image(*args, **kwaargs)

Pre-process image for registration

Pre-process image for registration. Processed image should be a single channel uint8 image.

Returns:

processed_img – Single channel processed copy of image

Return type:

ndarray

H&E deconvolution

class valis.preprocessing.HEDeconvolution(image, src_f, level, series, *args, **kwargs)

Bases: ImageProcesser

Normalize staining appearence of hematoxylin and eosin (H&E) stained image and get the H or E deconvolution image.

Reference

A method for normalizing histology slides for quantitative analysis. M. Macenko et al., ISBI 2009.

__init__(image, src_f, level, series, *args, **kwargs)

Parameters:

• image (ndarray) – Image to be processed

• src_f (str) – Path to slide/image.

• level (int) – Pyramid level to be read.

• series (int) – The series to be read.

process_image(stain='hem', Io=240, alpha=1, beta=0.15, *args, **kwargs)

Reference

A method for normalizing histology slides for quantitative analysis. M. Macenko et al., ISBI 2009.

Note

Adaptation of the code from https://github.com/schaugf/HEnorm_python.