H&E Histology Color Normalization Instructions

Manual color assignment using colorassign_manual.py

Overview

This python module works almost exactly the same as the MATLAB counterpart. View instructions.

Inputs

rgb - A multidimensional array of size [MxNx3] where M and N represent the height and width of the image respectively. The third dimension of the data represents each color value (RGB).

Outputs

The function returns a dictionary with five properties, indexedImage, lumen, stroma, nuclei, and cytoplasm. The indexedImage is a MxN array where M is the height and N is the width. Each specific entry represents an index from the reduced color palette. Each of lumen, stroma, nuclei, and cytoplasm represent an array of the indexed values that map to that particular structure.

Example returned data

{
'indexedImage': [[0,1,1,2,3.....]
'lumen': [1, 2],
'stroma':  [3, 4],
'cytoplasm':  [5, 6],
'nuclei': = [9, 10],
}

Explanation

The color assignment is the only function that requires manual human intervention. The goal of this function is to reduce the original image to a map that associates a subset of pixels in the image to a histologic element (like cell nuclei or stroma) using image indexing.

Python interface

Python interface showing color highlighting to assist with shape detection.

Free Parameters

RANDOM_STATE = None  # For stable results when testing, set to 1.
NCLUST = 10          # number of clusters
CLUSTERITER = 1e5    # maximum k-means iterations

 
NCLUST represents the number of colors used in the color downsampling. 10 colors was arbitrarily picked as a reasonable number of colors to achieve classification of structures while retaining sufficient image detail. In some image sets more colors may be desirable. Altering this constant will require changes to the GUI in order to properly classify the image.

CLUSTERITER represents the number of iterations kmeans will perform before it fails. It has been chosen to be 100,000. Kmeans clustering is a heuristic that uses a random seed to begin working towards suitable planes to separate data in space. Each iteration improves the accuracy of the heuristic solution. The number of iterations, set by This number can be changed without having to make other changes to the program though accuracy may not be significantly improved.

RANDOM_STATE should be set to None or an integer number. If None the default randomization for Python will be used. If an integer value such as 1 is used, it will seed the random number generator to a set value which is useful for producing reliable and stable results in testing.

Example Usage

Install dependencies using pip. From the directory for the module run:

pip install .

 
This should install the necessary dependencies which are:

• sklearn
• numpy
• imageio

From this point on, it can be used directly or from within another script.

Direct Usage Example

If used directly, the program requires an input tif file. An output file can also be specified. This will store the full return value structure as JSON data suitable for loading into another program.

>> python -m h_and_e_normalization.colorassign_manual -i /path/to/histology/image.tif -o /path/to/output.json

 
Usage within another program or script

>>> import imageio
>>> from h_and_e_normalization import colorassign_manual
>>> loaded_image = imageio.imread('/path/to/histology/image.tif')
>>> result = colorassign_manual(loaded_image)

Timing

When processing a 1mm² sample image of 2000x2000 pixels on a 2Ghz Intel i7 processor running with 8GB RAM, 10 minutes and 10 seconds elapsed before the GUI presented.

 
 Back to Top