def color_convolution(im_stains, w, I_0=None):
"""Perform Color Convolution.
Reconstructs a color image from the stain matrix `w` and
the individual images stored as channels in `im_stains` and generated
by ColorDeconvolution.
Parameters
----------
im_stains : array_like
An RGB image where in each channel contains image of one stain
w : array_like
A 3x3 matrix containing the stain colors in its columns.
In the case of two stains, the third column is zero and will be
complemented using cross-product. The matrix should contain a
minumum two nonzero columns.
I_0 : float or array_like, optional
A float a 3-vector containing background RGB intensities.
If unspecified, use the old OD conversion.
Returns
-------
im_rgb : array_like
Reconstructed RGB image with intensity values ranging from [0, 255],
suitable for display.
See Also
--------
histomicstk.preprocessing.color_deconvolution.complement_stain_matrix,
histomicstk.preprocessing.color_deconvolution.color_deconvolution
histomicstk.preprocessing.color_conversion.rgb_to_od
histomicstk.preprocessing.color_conversion.od_to_rgb
histomicstk.preprocessing.color_conversion.rgb_to_sda
histomicstk.preprocessing.color_conversion.sda_to_rgb
"""
# transform 3D input stain image to 2D stain matrix format
m = utils.convert_image_to_matrix(im_stains)
# transform input stains to optical density values, convolve and
# tfm back to stain
sda_fwd = color_conversion.rgb_to_sda(m,
255 if I_0 is not None else None,
allow_negatives=True)
sda_conv = np.dot(w, sda_fwd)
sda_inv = color_conversion.sda_to_rgb(sda_conv, I_0)
# reshape output, transform type
im_rgb = (utils.convert_matrix_to_image(sda_inv, im_stains.shape).clip(
0, 255).astype(np.uint8))
return im_rgb
def perturb_stain_concentration(StainsFloat,
W,
I_0=None,
mask_out=None,
sigma1=0.9,
sigma2=0.9):
u"""Perturb stain concentrations in SDA space and return augmented image.
This is an implementation of the method described in Tellez et
al, 2018 (see below). The SDA matrix is perturbed by multiplying each
channel independently by a value chosen from a random uniform distribution
in the range [1 - sigma1, 1 + sigma1], then add a value chosed from another
random uniform distribution in the range [-sigma2, sigma2].
Parameters
------------
StainsFloat : array_like
An intensity image (m, n, 3) of deconvolved stains that is unbounded,
suitable for reconstructing color images of deconvolved stains
with color_convolution.
W : array_like
A 3x3 complemented stain matrix.
I_0 : float or array_like, optional
A float a 3-vector containing background RGB intensities.
If unspecified, use the old OD conversion.
mask_out : array_like, default is None
if not None, should be (m x n) boolean numpy array.
This parameter ensures exclusion of non-masked areas from perturbing.
This is relevant because elements like blood, sharpie marker,
white space, etc cannot be simply modeled as a mix of two stains.
sigma1 : float
parameter, see beginning of this docstring.
sigma2 : float
parameter, see beginning of this docstring.
Returns
--------
array_like
Color augmented RGB image (m x n x 3)
References
----------
.. [#] Tellez, David, Maschenka Balkenhol, Irene Otte-Höller,
Rob van de Loo, Rob Vogels, Peter Bult, Carla Wauters et al.
"Whole-slide mitosis detection in H&E breast histology using PHH3
as a reference to train distilled stain-invariant convolutional
networks." IEEE transactions on medical imaging 37, no. 9
(2018): 2126-2136.
.. [#] Tellez, David, Geert Litjens, Peter Bandi, Wouter Bulten,
John-Melle Bokhorst, Francesco Ciompi, and Jeroen van der Laak.
"Quantifying the effects of data augmentation and stain color
normalization in convolutional neural networks for computational
pathology." arXiv preprint arXiv:1902.06543 (2019).
.. [#] Implementation inspired by Peter Byfield StainTools repository. See
https://github.com/Peter554/StainTools/blob/master/LICENSE.txt
for copyright license (MIT license).
"""
# augment everything, otherwise only augment specific pixels
if mask_out is None:
keep_mask = np.zeros(StainsFloat.shape[:2]) == 0
else:
keep_mask = np.equal(mask_out, False)
keep_mask = np.tile(keep_mask[..., None], (1, 1, 3))
keep_mask = convert_image_to_matrix(keep_mask)
# transform 3D input stain image to 2D stain matrix format
m = convert_image_to_matrix(StainsFloat)
# transform input stains to optical density values
sda_fwd = rgb_to_sda(m,
255 if I_0 is not None else None,
allow_negatives=True)
# perturb concentrations in SDA space
augmented_sda = sda_fwd.copy()
for i in range(3):
alpha = np.random.uniform(1 - sigma1, 1 + sigma1)
beta = np.random.uniform(-sigma2, sigma2)
augmented_sda[i, keep_mask[i, :]] *= alpha
augmented_sda[i, keep_mask[i, :]] += beta
# convolve with stains column vectors and convert to RGB
sda_conv = np.dot(W, augmented_sda)
sda_inv = sda_to_rgb(sda_conv, I_0)
# reshape output, transform type
augmented_rgb = (convert_matrix_to_image(sda_inv, StainsFloat.shape).clip(
0, 255).astype(np.uint8))
return augmented_rgb
def color_deconvolution(im_rgb, w, I_0=None):
"""Perform color deconvolution.
The given RGB Image `I` is first first transformed into optical density
space, and then projected onto the stain vectors in the columns of the
3x3 stain matrix `W`.
For deconvolving H&E stained image use:
`w` = array([[0.650, 0.072, 0], [0.704, 0.990, 0], [0.286, 0.105, 0]])
Parameters
----------
im_rgb : array_like
Input RGB Image that needs to be deconvolved.
w : array_like
A 3x3 matrix containing the color vectors in columns.
For two stain images the third column is zero and will be
complemented using cross-product. Atleast two of the three
columns must be non-zero.
I_0 : float or array_like, optional
A float a 3-vector containing background RGB intensities.
If unspecified, use the old OD conversion.
Returns
-------
Stains : array_like
An rgb image where in each channel contains the image of the
stain of the corresponding column in the stain matrix `W`.
The intensity range of each channel is [0, 255] suitable for
displaying.
StainsFloat : array_like
An intensity image of deconvolved stains that is unbounded,
suitable for reconstructing color images of deconvolved stains
with color_convolution.
Wc : array_like
A 3x3 complemented stain matrix. Useful for color image
reconstruction with color_convolution.
See Also
--------
histomicstk.preprocessing.color_deconvolution.complement_stain_matrix,
histomicstk.preprocessing.color_deconvolution.color_convolution
histomicstk.preprocessing.color_conversion.rgb_to_od
histomicstk.preprocessing.color_conversion.od_to_rgb
histomicstk.preprocessing.color_conversion.rgb_to_sda
histomicstk.preprocessing.color_conversion.sda_to_rgb
"""
# complement stain matrix if needed
if np.linalg.norm(w[:, 2]) <= 1e-16:
wc = complement_stain_matrix(w)
else:
wc = w
# normalize stains to unit-norm
wc = normalize(wc)
# invert stain matrix
Q = np.linalg.inv(wc)
# transform 3D input image to 2D RGB matrix format
m = utils.convert_image_to_matrix(im_rgb)[:3]
# transform input RGB to optical density values and deconvolve,
# tfm back to RGB
sda_fwd = color_conversion.rgb_to_sda(m, I_0)
sda_deconv = np.dot(Q, sda_fwd)
sda_inv = color_conversion.sda_to_rgb(sda_deconv,
255 if I_0 is not None else None)
# reshape output
StainsFloat = utils.convert_matrix_to_image(sda_inv, im_rgb.shape)
# transform type
Stains = StainsFloat.clip(0, 255).astype(np.uint8)
# return
Unmixed = collections.namedtuple('Unmixed',
['Stains', 'StainsFloat', 'Wc'])
Output = Unmixed(Stains, StainsFloat, wc)
return Output