Class ColorDeconvolutionHelper

java.lang.Object
qupath.lib.color.ColorDeconvolutionHelper

public class ColorDeconvolutionHelper extends Object
Static methods to assist with color deconvolution.
  • Constructor Summary

    Constructors
    Constructor
    Description
     
  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    colorDeconvolve(float[] red, float[] green, float[] blue, ColorDeconvolutionStains stains)
    Apply color deconvolution in-place for RGB channels.
    static float[]
    colorDeconvolve(BufferedImage img, ColorDeconvolutionStains stains, int stainNumber, float[] pixels)
    Apply color deconvolution to an input image, extracting a single channel as output and returning as a float array.
    static void
    convertPixelsToOpticalDensities(float[] px, double maxValue, boolean use8BitLUT)
    For originally-8-bit images, optical densities can usually be computed faster by preallocating a LUT with the 0-255 required values.
    static void
    convertToOpticalDensity(float[] pixels, double max)
    Convert an array of pixel values to optical densities in-place, normalizing using the specified maximum.
    static double[]
    Estimate white (background) values for a brightfield image.
    generateMedianStainVectorFromPixels(String name, int[] rgb, double redMax, double greenMax, double blueMax)
    Determine median RGB optical densities for an array of pixels (packed RGB), and combine these into a StainVector with the specified name.
    generateMedianStainVectorFromPixels(String name, BufferedImage img, double redMax, double greenMax, double blueMax)
    Generate a stain vector by taking the median optical densities from an input image.
    static float[]
    getBlueOpticalDensities(int[] rgb, double maxValue, float[] px)
    Convert red channel of packed rgb pixel to optical density values, using a specified maximum value.
    static float[]
    getGreenOpticalDensities(int[] rgb, double maxValue, float[] px)
    Convert red channel of packed rgb pixel to optical density values, using a specified maximum value.
    static float
    getMedian(float[] array)
    Get the median value from a float array.
    static int
    getMedianRGB(int[] rgb)
    Determine median of RGB values.
    static float[]
    getOpticalDensities(Raster raster, int band, double maxValue, float[] px)
    Extract a band from a raster and convert the pixel values to optical densities, using the specified maximum value.
    static float[]
    getPixels(Raster raster, int band)
    Extract a band from a raster and return the values in a float array.
    static float[]
    getPixels(Raster raster, int band, float[] px)
    Extract a band from a raster and return the values in a float array.
    static float[]
    getRedOpticalDensities(int[] rgb, double maxValue, float[] px)
    Convert red channel of packed rgb pixel to optical density values, using a specified maximum value.
    static double
    makeOD(double val, double max)
    Convert a single pixel value to an optical density as max(0, -log10(val/max).
    static double
    makeODByLUT(float val, double[] OD_LUT)
    Convert a float pixel to an optical density value using a pre-computed lookup table.
    static double
    makeODByLUT(int val, double[] OD_LUT)
    Convert an int pixel to an optical density value using a pre-computed lookup table.
    static double[]
    makeODLUT(double maxValue)
    Create an optical density lookup table with 256 entries, normalizing to the specified background value.
    static double[]
    makeODLUT(double maxValue, int nValues)
    Create an optical density lookup table, normalizing to the specified background value.
    refineColorDeconvolutionStains(int[] rgb, ColorDeconvolutionStains stains, double minStain, double percentageClipped)
    Attempt to automatically refine color deconvolution stains based upon pixel values.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • ColorDeconvolutionHelper

      public ColorDeconvolutionHelper()
  • Method Details

    • makeOD

      public static double makeOD(double val, double max)
      Convert a single pixel value to an optical density as max(0, -log10(val/max). where val is clipped to be >= 1.
      Parameters:
      val -
      max -
      Returns:
    • makeODByLUT

      public static double makeODByLUT(int val, double[] OD_LUT)
      Convert an int pixel to an optical density value using a pre-computed lookup table. This is likely to be much faster than calling makeOD(double, double).
      Parameters:
      val -
      OD_LUT -
      Returns:
      See Also:
    • makeODByLUT

      public static double makeODByLUT(float val, double[] OD_LUT)
      Convert a float pixel to an optical density value using a pre-computed lookup table. This is likely to be much faster than calling makeOD(double, double), but involves rounding the float first.
      Parameters:
      val -
      OD_LUT -
      Returns:
      See Also:
    • makeODLUT

      public static double[] makeODLUT(double maxValue)
      Create an optical density lookup table with 256 entries, normalizing to the specified background value.
      Parameters:
      maxValue -
      Returns:
      See Also:
    • makeODLUT

      public static double[] makeODLUT(double maxValue, int nValues)
      Create an optical density lookup table, normalizing to the specified background value.
      Parameters:
      maxValue - background (white value)
      nValues - number of values to include in the lookup table
      Returns:
    • convertPixelsToOpticalDensities

      public static void convertPixelsToOpticalDensities(float[] px, double maxValue, boolean use8BitLUT)
      For originally-8-bit images, optical densities can usually be computed faster by preallocating a LUT with the 0-255 required values. Otherwise, log values need to be calculated for every pixel (which can be relatively slow).
      Parameters:
      px -
      maxValue -
      use8BitLUT -
    • getRedOpticalDensities

      public static float[] getRedOpticalDensities(int[] rgb, double maxValue, float[] px)
      Convert red channel of packed rgb pixel to optical density values, using a specified maximum value.
      Parameters:
      rgb -
      maxValue -
      px - optional array used for output
      Returns:
    • getOpticalDensities

      public static float[] getOpticalDensities(Raster raster, int band, double maxValue, float[] px)
      Extract a band from a raster and convert the pixel values to optical densities, using the specified maximum value.
      Parameters:
      raster - the input image
      band - the band (channel) to extract
      maxValue - the maximum value used for normalization whe calculating optical densities
      px - optional array used for output
      Returns:
      a float array containing the optical density values (may be the same as px)
    • colorDeconvolve

      public static float[] colorDeconvolve(BufferedImage img, ColorDeconvolutionStains stains, int stainNumber, float[] pixels)
      Apply color deconvolution to an input image, extracting a single channel as output and returning as a float array.
      Parameters:
      img - input image, which should have 3 (non-alpha) channels
      stains - the color deconvolution stains to apply
      stainNumber - zero-based stain number (i.e. 0 for the first stain, 1 for the second stain, 2 for the third)
      pixels - optional array to store the output
      Returns:
      an array of optical density values after color deconvolution (possibly the same as pixels).
    • colorDeconvolve

      public static void colorDeconvolve(float[] red, float[] green, float[] blue, ColorDeconvolutionStains stains)
      Apply color deconvolution in-place for RGB channels. This can be used to apply color deconvolution to get all 3 output stains, without needing to allocate new arrays to store the result.
      Parameters:
      red - the red input channel
      green - the green input channel
      blue - the blue input channel
      stains - the stains to use
    • convertToOpticalDensity

      public static void convertToOpticalDensity(float[] pixels, double max)
      Convert an array of pixel values to optical densities in-place, normalizing using the specified maximum. Note that very small, zero and negative input values will be clipped.
      Parameters:
      pixels - the input pixel values
      max - the maximum used in the calculation of optical densities
    • getPixels

      public static float[] getPixels(Raster raster, int band, float[] px)
      Extract a band from a raster and return the values in a float array.
      Parameters:
      raster - the input raster
      band - the band (channel) to extract
      px - optional array used for output
      Returns:
      a float array containing the pixel values (may be the same as px)
    • getPixels

      public static float[] getPixels(Raster raster, int band)
      Extract a band from a raster and return the values in a float array.
      Parameters:
      raster - the input raster
      band - the band (channel) to extract
      Returns:
      a new float array containing the pixel values
    • getGreenOpticalDensities

      public static float[] getGreenOpticalDensities(int[] rgb, double maxValue, float[] px)
      Convert red channel of packed rgb pixel to optical density values, using a specified maximum value.
      Parameters:
      rgb -
      maxValue -
      px - optional array used for output
      Returns:
    • getBlueOpticalDensities

      public static float[] getBlueOpticalDensities(int[] rgb, double maxValue, float[] px)
      Convert red channel of packed rgb pixel to optical density values, using a specified maximum value.
      Parameters:
      rgb -
      maxValue -
      px - optional array used for output
      Returns:
    • generateMedianStainVectorFromPixels

      public static StainVector generateMedianStainVectorFromPixels(String name, BufferedImage img, double redMax, double greenMax, double blueMax)
      Generate a stain vector by taking the median optical densities from an input image.
      Parameters:
      name - name of the output stain vector
      img - input image containing pixels
      redMax - maximum value for red channel to use when calculating optical densities
      greenMax - maximum value for green channel to use when calculating optical densities
      blueMax - maximum value for blue channel to use when calculating optical densities
      Returns:
      the estimated stain vector
      See Also:
    • generateMedianStainVectorFromPixels

      public static StainVector generateMedianStainVectorFromPixels(String name, int[] rgb, double redMax, double greenMax, double blueMax)
      Determine median RGB optical densities for an array of pixels (packed RGB), and combine these into a StainVector with the specified name.
      Parameters:
      name - name of the output stain vector
      rgb - packed RGB array of pixels
      redMax - maximum value for red channel to use when calculating optical densities
      greenMax - maximum value for green channel to use when calculating optical densities
      blueMax - maximum value for blue channel to use when calculating optical densities
      Returns:
      the estimated stain vector
      See Also:
    • getMedianRGB

      public static int getMedianRGB(int[] rgb)
      Determine median of RGB values. The median of each channel is computed separately.
      Parameters:
      rgb - array of packed RGB values
      Returns:
    • getMedian

      public static float getMedian(float[] array)
      Get the median value from a float array. Note that the array will be sorted in-place; you need to pass a clone of the array if this is problematic.
      Parameters:
      array -
      Returns:
    • refineColorDeconvolutionStains

      public static ColorDeconvolutionStains refineColorDeconvolutionStains(int[] rgb, ColorDeconvolutionStains stains, double minStain, double percentageClipped)
      Attempt to automatically refine color deconvolution stains based upon pixel values.

      Warning! This is really only for testing - it has not be very extensively validated.

      The method used is based very loosely on that of Macenko et al. (2009), but avoids eigenvalue computations in favor of determining an initial stain inputs. TODO: Improve automatic stain vector refinement.

      Parameters:
      rgb -
      stains -
      minStain - minimum optical density for each RGB channel (default 0.15)
      percentageClipped -
      Returns:
    • estimateWhiteValues

      public static double[] estimateWhiteValues(int[] rgb)
      Estimate white (background) values for a brightfield image.

      The algorithm computes histograms for each RGB channel, and takes the mode of the histogram in the region of the histogram > the mean value for that channel.

      Parameters:
      rgb - an array of packed RGB values
      Returns:
      an array containing estimated [red, green and blue] background values