Package qupath.lib.color

Class ColorTransformer

java.lang.Object
qupath.lib.color.ColorTransformer
public class ColorTransformer extends Object
Static methods for computing a range of color transforms for packed RGB values.

Several straightforward methods of manipulating RGB channels that may be used to enhance (or suppress) primarily DAB staining, or otherwise assist in exploring IHC data. More details on each method (in particular 'Blue normalized', here 'Blue chromaticity') are provided in:

Brey, E. M., Lalani, Z., Johnston, C., Wong, M., McIntire, L. V., Duke, P. J., & Patrick, C. W. (2003). Automated Selection of DAB-labeled Tissue for Immunohistochemical Quantification. Journal of Histochemistry & Cytochemistry, 51(5) doi:10.1177/002215540305100503

Color deconvolution methods use default stain vectors - qupath.lib.color contains more flexible options for this.

  • Constructor Details

    • ColorTransformer

      public ColorTransformer()

  • Method Details

    • getODNormalizedColor

      public static int getODNormalizedColor(int rgb, double minOD, float offset, float scale)
      Create a 'normalized' color for visualization.

      This is achieved by converting RGB values to optical densities, putting the RGB ODs into a 3x1 vector and normalizing this to unit length, then rescaling the result to give an RGB representation. Because of the somewhat strange rescaling involved, the final RGB values produced should not be over-interpreted - this is really intended for visualization, such as when interactively looking for regions of single stains when selecting color deconvolution stain vectors.

      Parameters:
      rgb - original 8-bit RGB values
      minOD - the minimum OD; pixels with an OD less than this will be considered unstained, and shown as white
      offset - brightness and contrast offset
      scale - brightness and contrast scale value
      Returns:
      normalized color, as packed RGB value

    • getDefaultTransformedMax

      public static float getDefaultTransformedMax(ColorTransformer.ColorTransformMethod method)
      Get default maximum value to use with a specific transform method.

      Where this is well-defined, this should be the maximum possible value after the transform.

      Parameters:
      method -
      Returns:

    • getSimpleTransformedPixels

      public static float[] getSimpleTransformedPixels(int[] buf, ColorTransformer.ColorTransformMethod method, float[] pixels)
      Apply a color transform to all pixels in a packed (A)RGB array.

      This method is *only* compatible with color transforms that do not require a ColorDeconvolutionStains object - other transforms will throw an IllegalArgumentException.

      Parameters:
      buf - the input pixel buffer to be transformed
      method - the transfor method to apply
      pixels - optional output array to store the results; if null or of the wrong length, a new array will be created
      Returns:
      either the input array pixels, or a new array if required

    • getTransformedPixels

      public static float[] getTransformedPixels(int[] buf, ColorTransformer.ColorTransformMethod method, float[] pixels, ColorDeconvolutionStains stains)
      Apply a color transform to all pixels in a packed (A)RGB array.
      Parameters:
      buf - the input pixel buffer to be transformed
      method - the transfor method to apply
      pixels - optional output array to store the results; if null or of the wrong length, a new array will be created
      stains - a ColorDeconvolutionStains object, required for some transforms (and ignored otherwise).
      Returns:
      either the input array pixels, or a new array if required

    • getStainRejection

      public static float getStainRejection(int rgb, double rStain, double gStain, double bStain, double[] od_lut_red, double[] od_lut_green, double[] od_lut_blue)
      Calculate magnitude of rejection of pixel OD onto stain OD.
      Parameters:
      rgb -
      rStain -
      gStain -
      bStain -
      od_lut_red -
      od_lut_green -
      od_lut_blue -
      Returns:

    • getStainProjection

      public static float getStainProjection(int rgb, double rStain, double gStain, double bStain, double[] od_lut_red, double[] od_lut_green, double[] od_lut_blue)
      Calculate magnitude of projection of pixel OD onto stain OD.
      Parameters:
      rgb -
      rStain -
      gStain -
      bStain -
      od_lut_red -
      od_lut_green -
      od_lut_blue -
      Returns:

    • opticalDensitySum

      public static float opticalDensitySum(int rgb, double[] od_lut)
      Extract optical density sum value from a packed RGB pixel.
      Parameters:
      rgb -
      od_lut - lookup table to aid with fast optical density calculations
      Returns:

    • opticalDensitySum

      public static float opticalDensitySum(int rgb, double[] od_lut_red, double[] od_lut_green, double[] od_lut_blue)
      Extract optical density sum value from a packed RGB pixel.
      Parameters:
      rgb -
      od_lut_red - red lookup table to aid with fast optical density calculations
      od_lut_green - green lookup table to aid with fast optical density calculations
      od_lut_blue - blue lookup table to aid with fast optical density calculations
      Returns:

    • rgbMean

      public static float rgbMean(int rgb)
      Extract mean of RGB values from a packed RGB pixel.
      Parameters:
      rgb -
      Returns:

    • redChromaticity

      public static float redChromaticity(int rgb)
      Extract red chromaticity value from a packed RGB pixel, red / max(1, red + green + blue)
      Parameters:
      rgb -
      Returns:

    • greenChromaticity

      public static float greenChromaticity(int rgb)
      Extract green chromaticity value from a packed RGB pixel, green / max(1, red + green + blue)
      Parameters:
      rgb -
      Returns:

    • blueChromaticity

      public static float blueChromaticity(int rgb)
      Extract blue chromaticity value from a packed RGB pixel, blue / max(1, red + green + blue)
      Parameters:
      rgb -
      Returns:

    • greenOverBlue

      public static float greenOverBlue(int rgb)
      Extract green over blue value from a packed RGB pixel, green / max(1, blue)
      Parameters:
      rgb -
      Returns:

    • brown

      public static float brown(int rgb)
      Extract brown value, (blue - (red + green)*0.3f)
      Parameters:
      rgb -
      Returns:

    • hue

      public static float hue(int rgb)
      Extract hue value from RGB-to-HSB transform.
      Parameters:
      rgb -
      Returns:

    • saturation

      public static float saturation(int rgb)
      Extract saturation value from RGB-to-HSB transform.
      Parameters:
      rgb -
      Returns:

    • brightness

      public static float brightness(int rgb)
      Extract brightness value from RGB-to-HSB transform.
      Parameters:
      rgb -
      Returns:

    • getPixelValue

      public static float getPixelValue(int rgb, ColorTransformer.ColorTransformMethod method)
      Get the value of a single packed RGB pixel after applying a specified color transform method.
      Parameters:
      rgb -
      method -
      Returns:

    • getPixelValue

      public static float getPixelValue(int rgb, ColorTransformer.ColorTransformMethod method, ColorDeconvolutionStains stains)
      Get the value of a single packed RGB pixel after applying a specified color transform method, with color deconvolution stains provided.
      Parameters:
      rgb -
      method -
      stains -
      Returns:

    • makeScaledRGBwithRangeCheck

      public static int makeScaledRGBwithRangeCheck(float v, float offset, float scale, ColorModel cm)
      Create a packed RGB pixel value by applying a ColorModel to a (possibly scaled and offset) floating point value.
      Parameters:
      v - the 'raw' pixel value
      offset - an offset to subtract from the value
      scale - a scaling factor to apply after the offset subtraction
      cm - a ColorModel used to determine the output packed RGB value
      Returns:
      a packed RGB value after applying the transformations to v

    • getDefaultColorModel

      public static ColorModel getDefaultColorModel(ColorTransformer.ColorTransformMethod method)
      This does not guarantee a ColorModel will be returned! If it is not, then a default grayscale LUT should be used.
      Parameters:
      method -
      Returns:

    • transformRGB

      public static void transformRGB(int[] buf, int[] bufOutput, ColorTransformer.ColorTransformMethod method, float offset, float scale, boolean useColorLUT)
      Apply a specified color transform to a packed (A)RGB array and output another (A)RGB array.

      The aim is to perform fast transformations for visualization purposes, and not to obtain the 'raw' transformed values.

      Parameters:
      buf -
      bufOutput -
      method -
      offset -
      scale -
      useColorLUT -
      See Also:

    • colorDeconvolveRGBPixel

      public static float colorDeconvolveRGBPixel(int rgb, ColorDeconvolutionStains stains, int channel)
      Calculate the color deconvolved value for a single pixel, stored as a packed (A)RGB int.
      Parameters:
      rgb -
      stains -
      channel -
      Returns:

    • colorDeconvolveReconvolveRGBArray

      public static int[] colorDeconvolveReconvolveRGBArray(int[] buf, ColorDeconvolutionStains stainsInput, ColorDeconvolutionStains stainsOutput, boolean discardResidual, int[] bufOutput)
      Deconvolve RGB array with one set of stain vectors, and reconvolve with another.

      This supports in-place operation, i.e. buf and bufOutput can be the same array. Otherwise, if bufOutput == null, a new output array will be created.

      Parameters:
      buf -
      stainsInput -
      stainsOutput -
      discardResidual -
      bufOutput -
      Returns:
      output RGB buffer

    • colorDeconvolveReconvolveRGBArray

      public static int[] colorDeconvolveReconvolveRGBArray(int[] buf, ColorDeconvolutionStains stainsInput, ColorDeconvolutionStains stainsOutput, int[] bufOutput, double[] stainScales)
      Deconvolve RGB array with one set of stain vectors, and reconvolve with another - with optional scaling.

      This supports in-place operation, i.e. buf and bufOutput can be the same array. Otherwise, if bufOutput == null, a new output array will be created.

      Note: If stainsInput is null, the returned array will be filled with zeros.

      Parameters:
      buf - buffer of input RGB values
      stainsInput - stain vectors for deconvolution
      stainsOutput - stain vectors for reconvolution
      bufOutput - output RGB buffer
      stainScales - optional array of scale values for each stain (e.g. [1, 2, 0] to double the second stain and discard the third)
      Returns:
      output RGB buffer
      Since:
      v0.6.0
      Implementation Note
      this method changed in v0.6.0 to support scaling of the stains, and to retain the alpha value.