Package com.xinapse.image

Class Histogram

java.lang.Object
com.xinapse.image.Histogram
public class Histogram extends Object
A class for creating histograms and finding statistics about arrays of values (normally pixel intensities).

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Histogram.BinSpec
    A specification for Histogram bins.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Histogram(double[] count, double histoMin, double binWidth)
    Creates a Histogram of intensities from pre-computed values.
    Histogram(float[] count, double histoMin, double binWidth)
    Creates a Histogram of intensities from pre-computed values.
    Histogram(Histogram h)
    Creates a new Histogram, copying all values from an existing Histogram.
    Histogram(Object pixelValues, int offset, int nPixels, PixelDataType dataType)
    Creates a Histogram of intensities from an array of values of a given PixelDataType.
    Histogram(Object pixelValues, int offset, int nPixels, PixelDataType dataType, double min, double max, double binWidth, ComplexMode complexMode)
    Creates a Histogram of intensities from an array of values over a specified intensity range, and width a specified bin width.
    Histogram(Object pixelValues, int offset, int nPixels, PixelDataType dataType, double min, double max, int nBins, ComplexMode complexMode)
    Creates a Histogram of intensities from an array of values over a specified intensity range, and with the specified number of bins.
    Histogram(Object pixelValues, int offset, int nPixels, PixelDataType dataType, double min, double max, ComplexMode complexMode)
    Creates a Histogram of intensities from an array of values over a specified intensity range.
    Histogram(Object pixelValues, int offset, int nPixels, PixelDataType dataType, ComplexMode complexMode)
    Creates a Histogram of intensities from an array of values, with an option to specifiy the mode of calculation for PixelDataType.COMPLEX, or PixelDataType.DOUBLECOMPLEX images.
    Histogram(Object pixelValues, PixelDataType dataType)
    Creates a Histogram of intensities from an array of values of a given PixelDataType.
    Histogram(Object pixelValues, PixelDataType dataType, ComplexMode complexMode)
    Creates a Histogram of intensities from an array of values of a given PixelDataType.

  • Method Summary

    Modifier and Type
    Method
    Description
    Histogram
    add(Histogram histo, PixelDataType dataType)
    Adds the counts from a Histogram to this Histogram to produce a new Histogram that spans the data range of both.
    void
    addValues(Object pixelValues, int offset, int nPixels, PixelDataType dataType, ComplexMode complexMode)
    Adds some pixel values to this Histogram.
    static Histogram.BinSpec
    calcBins(double min, double max, int nBins, PixelDataType dataType, ComplexMode complexMode)
    Calculates a suitable bin width, and minimum bin value for a histogram, for the given type of pixels over the given intensity range.
    static Histogram.BinSpec
    calcBins(double min, double max, PixelDataType dataType, ComplexMode complexMode)
    Calculates a suitable bin width, number of bins, and minimum bin value for a histogram, for the given type of pixels over the given intensity range.
    double
    getAreaUnder()
    Returns the total area under this histogram.
    double
    getAreaUnder(boolean excludeZero)
    Returns the area under this histogram, optionally excluding any zero-valued values.
    double
    getBinWidth()
    Returns the bin width for this Histogram.
    double
    getCount(int binIndex)
    Returns the count in one bin of this Histogram.
    Histogram
    getCumulativeHistogram()
    Return a new Histogram that is the cumulative histogram of this one.
    double
    getCumulativeIntensity(float fraction, boolean excludeZero)
    Returns a value such that the specified fraction of values is below the returned intensity; zero-valued values are optionally excluded from the calculation.
    double
    getEntropy()
    Returns the entropy of this Histogram.
    double
    getHistoMax()
    Returns the maximum bin value of this Histogram.
    double
    getHistoMin()
    Returns the minimum bin value of this Histogram.
    double
    getMaxBinnableValue(PixelDataType dataType)
    Returns the maximum value that can be added to this Histogram's bins.
    double
    getMean()
    Returns the mean intensity value of this Histogram.
    double
    getMean(boolean excludeZero)
    Returns the mean intensity value of this Histogram, optionally excluding all values that are zero.
    double
    getMedian()
    Returns the median value of this Histogram.
    double
    getMedian(boolean excludeZero)
    Returns the median value of this Histogram, optionally excluding all values that are zero.
    static double[]
    getMinMax(Object pixelValues, int offset, int nPixels, PixelDataType dataType, ComplexMode complexMode)
    Returns the minimum and maximum intensity values present in a part of an array of pixel values.
    static double[]
    getMinMax(Object pixelValues, PixelDataType dataType, ComplexMode complexMode)
    Returns the minimum and maximum intensity values present in an array of pixel values.
    int
    getNBins()
    Returns the number of bins in this Histogram.
    double
    getPeakHeight(boolean excludeZero)
    Returns the number of values with the most common value in this Histogram, optionally excluding the values that are zero-valued.
    double
    getPeakPosition(boolean excludeZero)
    Returns the most common value in this Histogram, optionally excluding the values that are zero-valued.
    double
    getSD()
    Returns the standard deviation of intensity values of this Histogram.
    double
    getSD(boolean excludeZero)
    Returns the standard deviation of intensity values of this Histogram, optionally excluding all values that are zero from the calculation.
    double
    getTotalCount()
    Returns the total number of values that contributed to this histogram.
    double
    getTotalCount(boolean excludeZero)
    Returns the total number of values that contributed to this histogram, optionally excluding any zero-valued values.
    double
    getTotalCount(double threshold)
    Returns the number of values in this histogram that are above the supplied threshold.
    static void
    main(String[] args)
    Run the self-test of the Histogram class.
    float
    match(Histogram h, double threshold)
    Returns the intensity scaling factor that will best match this Histogram to another Histogram.
    static Histogram
    newInstance(ReadableImage image)
    Creates a Histogram of intensities from a ReadableImage.
    void
    normalise()
    Normalises this Histogram, so that the sum of all the counts is unity.
    double
    otsuThreshold()
    Calculates a threshold to separate the foreground from the background using Ostu's method of maximsing between-class variance for two classes of pixel values, where one class is assumed to be the foreground, and the other is the background.
    void
    scale(double scale)
    Scales the counts in this Histogram, mutiplying all the count values by the supplied scaling factor.
    void
    setCount(int binIndex, double count)
    Sets the count in one bin of this Histogram.
    String
    toString()
    Returns a String that lists the min, max, bin width and count values of this Histogram.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Histogram

      public Histogram(float[] count, double histoMin, double binWidth)
      Creates a Histogram of intensities from pre-computed values.
      Parameters:
      count - the number of values in each bin of the Histogram.
      histoMin - the intensity corresponding to the first bin of the Histogram.
      binWidth - the histogram bin width in intensity units.

    • Histogram

      public Histogram(double[] count, double histoMin, double binWidth)
      Creates a Histogram of intensities from pre-computed values.
      Parameters:
      count - the number of values in each bin of the Histogram.
      histoMin - the intensity corresponding to the first bin of the Histogram.
      binWidth - the histogram bin width in intensity units.

    • Histogram

      public Histogram(Object pixelValues, PixelDataType dataType) throws InvalidImageException
      Creates a Histogram of intensities from an array of values of a given PixelDataType.
      For PixelDataType.BINARY images, the histogram always has two bins with the first bin showing the number of pixel values that are false and the second bin showing the number of pixel values that are true.
      For RGB-type images (PixelDataType.RGB_BY_PLANE, PixelDataType.RGB_INTERLACED and PixelDataType.COLOURPACKED), the Histogram is a histogram of the luminance of the colour, where the luminance is (0.299 * Red) + (0.587 * Green) + (0.114 * Blue).
      Do not use this method for PixelDataType.COMPLEX or PixelDataType.DOUBLECOMPLEX images.
      Parameters:
      pixelValues - an array of pixel values for which the Histogram will be created.
      dataType - the type of pixel value stored in the pixelValues.
      Throws:
      InvalidImageException - if a Histogram cannot be created for the supplied pixel data type, or if the intensity range in the pixels overflows that which can be stored in the Histogram.

    • Histogram

      public Histogram(Object pixelValues, PixelDataType dataType, ComplexMode complexMode) throws InvalidImageException
      Creates a Histogram of intensities from an array of values of a given PixelDataType.
      For PixelDataType.BINARY images, the histogram always has two bins with the first bin showing the number of pixel values that are false and the second bin showing the number of pixel values that are true.
      For RGB-type images (PixelDataType.RGB_BY_PLANE, PixelDataType.RGB_INTERLACED and PixelDataType.COLOURPACKED), the Histogram is a histogram of the luminance of the colour, where the luminance is (0.299 * Red) + (0.587 * Green) + (0.114 * Blue).
      Parameters:
      pixelValues - an array of pixel values for which the Histogram will be created.
      dataType - the type of pixel value stored in the pixelValues.
      complexMode - the ComplexMode for complex data types.
      Throws:
      InvalidImageException - if a Histogram cannot be created for the supplied pixel data type, or if the intensity range in the pixels overflows that which can be stored in the Histogram.

    • Histogram

      public Histogram(Object pixelValues, int offset, int nPixels, PixelDataType dataType) throws InvalidImageException
      Creates a Histogram of intensities from an array of values of a given PixelDataType.
      For PixelDataType.BINARY images, the histogram always has two bins with the first bin showing the number of pixel values that are false and the second bin showing the number of pixel values that are true.
      For RGB-type images (PixelDataType.RGB_BY_PLANE, PixelDataType.RGB_INTERLACED and PixelDataType.COLOURPACKED), the Histogram is a histogram of the luminance of the colour, where the luminance is (0.299 * Red) + (0.587 * Green) + (0.114 * Blue).
      Parameters:
      pixelValues - an array of pixel values for which the Histogram will be created.
      offset - an offset (in pixels) into the array for the first pixel to be included in the Histogram.
      nPixels - the number of pixels to be included in the Histogram.
      dataType - the type of pixel value stored in the pixelValues.
      Throws:
      InvalidImageException - if a Histogram cannot be created for the supplied pixel data type, or if the intensity range in the pixels overflows that which can be stored in the Histogram.

    • Histogram

      public Histogram(Object pixelValues, int offset, int nPixels, PixelDataType dataType, ComplexMode complexMode) throws InvalidImageException
      Creates a Histogram of intensities from an array of values, with an option to specifiy the mode of calculation for PixelDataType.COMPLEX, or PixelDataType.DOUBLECOMPLEX images.
      For PixelDataType.BINARY images, the histogram always has two bins with the first bin showing the number of pixel values that are false and the second bin showing the number of pixel values that are true.
      For RGB-type images (PixelDataType.RGB_BY_PLANE, PixelDataType.RGB_INTERLACED and PixelDataType.COLOURPACKED), the Histogram is a histogram of the luminance of the colour, where the luminance is (0.299 * Red) + (0.587 * Green) + (0.114 * Blue).
      Parameters:
      pixelValues - an array of pixel values for which the Histogram will be created.
      offset - an offset (in pixels) into the array for the first pixel to be included in the Histogram.
      nPixels - the number of pixels to be included in the Histogram.
      dataType - the type of pixel value stored in the pixelValues.
      complexMode - mode for calculation of the histogram of Complex images. For all other types of image, the complexMode is ignored.
      Throws:
      InvalidImageException - if a Histogram cannot be created for the supplied pixel data type, or if the intensity range in the pixels overflows that which can be stored in the Histogram.

    • Histogram

      public Histogram(Object pixelValues, int offset, int nPixels, PixelDataType dataType, double min, double max, double binWidth, ComplexMode complexMode) throws InvalidImageException
      Creates a Histogram of intensities from an array of values over a specified intensity range, and width a specified bin width. Intensity values that are outside the supplied min/max range are not included in the histogram.
      For PixelDataType.COMPLEX or PixelDataType.DOUBLECOMPLEX images, the Histogram depends on the ComplexMode which determines whether the magnitude, real, imaginary or phase histogram is produced.
      Parameters:
      pixelValues - an array of pixel values for which the Histogram will be created.
      offset - an offset (in pixels) into the array for the first pixel to be included in the Histogram.
      nPixels - the number of pixels to be included in the Histogram.
      dataType - the type of pixel value stored in the pixelValues.
      min - the intensity of the lowest-intensity bin of the Histogram. Pixel intensities below the minimum are not included in the Histogram. For PixelDataType.BINARY images this value must be 0.
      max - the intensity of the highest-intensity bin of the Histogram. Pixel intensities above the maximum are not included in the Histogram. For PixelDataType.BINARY images this value must be 1.
      binWidth - the bin width for the Histogram.
      complexMode - mode for calculation of the histogram of Complex images. For all other types of image, the complexMode is ignored.
      Throws:
      InvalidImageException - if a Histogram cannot be created for the supplied pixel data type, or if the intensity range in the pixels overflows that which can be stored in the Histogram.

    • Histogram

      public Histogram(Object pixelValues, int offset, int nPixels, PixelDataType dataType, double min, double max, ComplexMode complexMode) throws InvalidImageException
      Creates a Histogram of intensities from an array of values over a specified intensity range. Intensity values that are outside the supplied min/max range are not included in the histogram. The bin width is calculated automatically.
      For PixelDataType.BINARY images, the histogram always has two bins with the first bin showing the number of pixel values that are false and the second bin showing the number of pixel values that are true.
      For RGB-type images (PixelDataType.RGB_BY_PLANE, PixelDataType.RGB_INTERLACED and PixelDataType.COLOURPACKED), the Histogram is a histogram of the luminance of the colour, where the luminance is (0.299 * Red) + (0.587 * Green) + (0.114 * Blue).
      For PixelDataType.COMPLEX or PixelDataType.DOUBLECOMPLEX images, the Histogram depends on the ComplexMode which determines whether the magnitude, real, imaginary or phase histogram is produced.
      Parameters:
      pixelValues - an array of pixel values for which the Histogram will be created.
      offset - an offset (in pixels) into the array for the first pixel to be included in the Histogram.
      nPixels - the number of pixels to be included in the Histogram.
      dataType - the type of pixel value stored in the pixelValues.
      min - the intensity of the lowest-intensity bin of the Histogram. Pixel intensities below the minimum are not included in the Histogram. For PixelDataType.BINARY images this value must be 0.
      max - the intensity of the highest-intensity bin of the Histogram. Pixel intensities above the maximum are not included in the Histogram. For PixelDataType.BINARY images this value must be 1.
      complexMode - mode for calculation of the histogram of Complex images. For all other types of image, the complexMode is ignored.
      Throws:
      InvalidImageException - if a Histogram cannot be created for the supplied pixel data type, or if the intensity range in the pixels overflows that which can be stored in the Histogram.

    • Histogram

      public Histogram(Object pixelValues, int offset, int nPixels, PixelDataType dataType, double min, double max, int nBins, ComplexMode complexMode) throws InvalidImageException
      Creates a Histogram of intensities from an array of values over a specified intensity range, and with the specified number of bins. Intensity values that are outside the supplied min/max range are not included in the histogram.
      For PixelDataType.BINARY images, the histogram always has two bins with the first bin showing the number of pixel values that are false and the second bin showing the number of pixel values that are true.
      For RGB-type images (PixelDataType.RGB_BY_PLANE, PixelDataType.RGB_INTERLACED and PixelDataType.COLOURPACKED), the Histogram is a histogram of the luminance of the colour, where the luminance is (0.299 * Red) + (0.587 * Green) + (0.114 * Blue).
      For PixelDataType.COMPLEX or PixelDataType.DOUBLECOMPLEX images, the Histogram depends on the ComplexMode which determines whether the magnitude, real, imaginary or phase histogram is produced.
      Parameters:
      pixelValues - an array of pixel values for which the Histogram will be created.
      offset - an offset (in pixels) into the array for the first pixel to be included in the Histogram.
      nPixels - the number of pixels to be included in the Histogram.
      dataType - the type of pixel value stored in the pixelValues.
      min - the intensity of the lowest-intensity bin of the Histogram. Pixel intensities below the minimum are not included in the Histogram. For PixelDataType.BINARY images this value must be 0.
      max - the intensity of the highest-intensity bin of the Histogram. Pixel intensities above the maximum are not included in the Histogram. For PixelDataType.BINARY images this value must be 1.
      nBins - the number of bins in the Histogram.
      complexMode - mode for calculation of the histogram of Complex images. For all other types of image, the complexMode is ignored.
      Throws:
      InvalidImageException - if the Histogram cannot be computed.

    • Histogram

      public Histogram(Histogram h)
      Creates a new Histogram, copying all values from an existing Histogram.
      Parameters:
      h - the Histogram from which the values will be copied.

  • Method Details

    • newInstance

      public static Histogram newInstance(ReadableImage image) throws InvalidImageException
      Creates a Histogram of intensities from a ReadableImage.
      For PixelDataType.BINARY images, the histogram always has two bins with the first bin showing the number of pixel values that are false and the second bin showing the number of pixel values that are true.
      For PixelDataType.UBYTE, and Colour images, the histogram always has 255 bins with the intensities from 0 to 255.
      For PixelDataType.BYTE, the histogram always has 255 bins with the intensities from -128 to 127.
      For RGB-type images (PixelDataType.RGB_BY_PLANE, PixelDataType.RGB_INTERLACED and PixelDataType.COLOURPACKED), the Histogram is a histogram of the luminance of the colour, where the luminance is (0.299 * Red) + (0.587 * Green) + (0.114 * Blue).
      Do not use this method for PixelDataType.COMPLEX or PixelDataType.DOUBLECOMPLEX images.
      Parameters:
      image - the image for which to find the Histogram.
      Returns:
      a Histogram constructed from the pixel intensity values of the supplied image.
      Throws:
      InvalidImageException - if a Histogram cannot be created for the supplied image, or if the intensity range in the pixels overflows that which can be stored in the Histogram.

    • addValues

      public void addValues(Object pixelValues, int offset, int nPixels, PixelDataType dataType, ComplexMode complexMode) throws InvalidImageException
      Adds some pixel values to this Histogram. Any pixels whose intensity under- or overflows the range of the Histogram are ignored.
      Parameters:
      pixelValues - an array of pixel values to add to the Histogram.
      offset - an offset (in pixels) into the array at which to start adding the pixel values.
      nPixels - the number of pixels in the array to add.
      dataType - the type of pixel values to be added to this Histogram.
      complexMode - for calculation of the histogram for Complex images. For all other types of image, the complexMode is ignored.
      Throws:
      InvalidImageException - if pixels of this PixelDataType cannot be added to this Histogram.

    • getBinWidth

      public double getBinWidth()
      Returns the bin width for this Histogram. For Histograms constructed from integer data types (except unsigned long), this method always returns 1.0.
      Returns:
      the bin width for this Histogram.

    • calcBins

      public static Histogram.BinSpec calcBins(double min, double max, PixelDataType dataType, ComplexMode complexMode) throws InvalidImageException
      Calculates a suitable bin width, number of bins, and minimum bin value for a histogram, for the given type of pixels over the given intensity range.
      Parameters:
      min - the minimum intensity value.
      max - the maximum intensity value.
      dataType - the PixelDataType of the intensities.
      complexMode - the ComplexMode complex display mode for complex images.
      Returns:
      a suitable bin width, number of bins and histogram minimum for this type of pixel, with the given intensity range. For integer data types, the bin width returned will be 1.0, unless this would result in an exceessively large number of bins. Excessively large for our purposes means more than 65536, which could arise for integer, or long data types with a large data range; in these cases the bin width is increased by powers of two until the number of bins needed for the histogram is less than 65535. For floating point images (including complex real, imaginary and magnitude images), the bin width will always be a power of 10, with the number of bins being as close to 100 as this constraint will allow. For complex phase images, the bin width will always be Pi/180 (1 degree).
      Throws:
      InvalidImageException - if the bin width cannot be calculated for pixels with the given minimum and maximum intensities (typically if the intensity range is infinite).

    • calcBins

      public static Histogram.BinSpec calcBins(double min, double max, int nBins, PixelDataType dataType, ComplexMode complexMode) throws InvalidImageException
      Calculates a suitable bin width, and minimum bin value for a histogram, for the given type of pixels over the given intensity range.
      Parameters:
      min - the minimum intensity value.
      max - the maximum intensity value.
      nBins - the number of bins for the Histogram.
      dataType - the PixelDataType of the intensities.
      complexMode - the ComplexMode complex display mode for complex images.
      Returns:
      a suitable bin width, number of bins and histogram minimum for this type of pixel, with the given intensity range.
      Throws:
      InvalidImageException - if the supplied bin width is unsuitable for this type of PixelDataType, or if the given minimum and maximum intensities are outside the range for this type of data.

    • getMinMax

      public static double[] getMinMax(Object pixelValues, PixelDataType dataType, ComplexMode complexMode) throws InvalidImageException
      Returns the minimum and maximum intensity values present in an array of pixel values.
      For PixelDataType.BINARY, the values returned are always 0 and 1.
      For RGB-type images (PixelDataType.RGB_BY_PLANE, PixelDataType.RGB_INTERLACED and PixelDataType.COLOURPACKED), the intensity values returned are always 0 and 255.
      For PixelDataType.COMPLEX and PixelDataType.DOUBLECOMPLEX, the minimum and maximum depend of the complexMode. If complexMode is ComplexMode.PHASE, the minimum and maximum returned are always -PI and +PI. For all other ComplexModes, the minimum is the minimum real or imaginary value, and the maximum is the maximum magnitude value.
      Parameters:
      pixelValues - an array of pixel values for which to find the minimum and maximum values.
      dataType - the type of pixel value stored in the pixelValues.
      complexMode - mode for the calculation of the minimum and maximum values for Complex images. For all other types of image, the complexMode is ignored.
      Returns:
      the minimum and maximim intensity values in a double[] of length 2.
      Throws:
      InvalidImageException - if a the minimum and maximum values cannot be found for the supplied data type

    • getMinMax

      public static double[] getMinMax(Object pixelValues, int offset, int nPixels, PixelDataType dataType, ComplexMode complexMode) throws InvalidImageException
      Returns the minimum and maximum intensity values present in a part of an array of pixel values.
      For PixelDataType.BINARY, the values returned are always 0 and 1.
      For RGB-type images (PixelDataType.RGB_BY_PLANE, PixelDataType.RGB_INTERLACED and PixelDataType.COLOURPACKED), the intensity values returned are always 0 and 255.
      For PixelDataType.COMPLEX PixelDataType.DOUBLECOMPLEX, the minimum and maximum depend of the complexMode. If complexMode is ComplexMode.PHASE, the minimum and maximum returned are always -PI and +PI. For all other ComplexModes, the minimum is the minimum real or imaginary value, and the maximum is the maximum magnitude value.
      Parameters:
      pixelValues - an array of pixel values for which to find the minimum and maximum values.
      offset - an offset (in pixels) into the array for the first pixel to be included in the calculation of min/max.
      nPixels - the number of pixels to be included in the calculation of min/max.
      dataType - the type of pixel value stored in the pixelValues.
      complexMode - mode for the calculation of the minimum and maximum values for Complex images. For all other types of image, the complexMode is ignored.
      Returns:
      the minimum and maximim intensity values in a double[] of length 2.
      Throws:
      InvalidImageException - if a the minimum and maximum values cannot be found for the supplied data type

    • getCumulativeHistogram

      public Histogram getCumulativeHistogram()
      Return a new Histogram that is the cumulative histogram of this one.
      Returns:
      a new Histogram that is the cumulative histogram of this one.

    • getNBins

      public int getNBins()
      Returns the number of bins in this Histogram.
      Returns:
      the number of Histogram bins.

    • getCount

      public double getCount(int binIndex)
      Returns the count in one bin of this Histogram.
      Parameters:
      binIndex - the index (zero-referenced) to the bin.
      Returns:
      the number of counts in the Histogram bin.
      Throws:
      IndexOutOfBoundsException - if binIndex is less than zero or greater than or equal to the number of bins in the Hostogram.

    • setCount

      public void setCount(int binIndex, double count)
      Sets the count in one bin of this Histogram.
      Parameters:
      binIndex - the index (zero-referenced) to the bin.
      count - the number of counts to set in the Histogram bin.
      Throws:
      IndexOutOfBoundsException - if binIndex is less than zero or greater than or equal to the number of bins in the Hostogram.

    • getHistoMin

      public double getHistoMin()
      Returns the minimum bin value of this Histogram.
      Returns:
      the minimum bin value of this Histogram.

    • getHistoMax

      public double getHistoMax()
      Returns the maximum bin value of this Histogram.

      Note: this is the lowest value that can be added to the highest bin. To get the highest value that can be added to the the highest bin (and therefore to the Histogram), use the getMaxBinnableValue(com.xinapse.image.PixelDataType)

      Returns:
      the maximum bin value of this Histogram.

    • getMaxBinnableValue

      public double getMaxBinnableValue(PixelDataType dataType)
      Returns the maximum value that can be added to this Histogram's bins.

      For PixelDataTypes that represent whole (integer) numbers, this method returns the highest integer value that can be added to this histogram.

      For floating-point (including double) this method returns the largest floating-point value that can be added to this histogram. This number just just less than (to within floating-point precision) the value that would be put into the next-higher histogram bin.

      Parameters:
      dataType - the PixelDataType for intensities to be added to this Histogram.
      Returns:
      the maximum intensity value that can be added to a bin of this Histogram.

    • getPeakHeight

      public double getPeakHeight(boolean excludeZero)
      Returns the number of values with the most common value in this Histogram, optionally excluding the values that are zero-valued. This is useful when an image has a background of zero, and you want to exclude this.
      Parameters:
      excludeZero - true if the zero-valued background is to be excluded from the search for the most common intensity.
      Returns:
      the number of values with the most common value in this Histogram, optionally excluding the zero-valued background. If the Histogram has multiple bins all of the same height, then the first one encountered is returned.

    • getPeakPosition

      public double getPeakPosition(boolean excludeZero)
      Returns the most common value in this Histogram, optionally excluding the values that are zero-valued. This is useful when an image has a background of zero, and you want to exclude this. If the histogram has two or more peaks of equal height, then the position of the lowest-intensity peak will be returned.
      Parameters:
      excludeZero - true if the zero-valued background is to be excluded from the search for the most common intensity.
      Returns:
      the most common value in this Histogram, optionally excluding the zero-valued background. If the Histogram has multiple bins all of the same height, then the first one encountered is returned.

    • getMedian

      public double getMedian()
      Returns the median value of this Histogram.
      Returns:
      the median value of this Histogram.

    • getMedian

      public double getMedian(boolean excludeZero)
      Returns the median value of this Histogram, optionally excluding all values that are zero. This is useful when an image has a background of zero, and you want to exclude the effect of the background on the median value.
      Parameters:
      excludeZero - true if the zero-valued background is to be excluded from the calculation of the median.
      Returns:
      the median value of this Histogram, optionally excluding the zero-valued background.

    • getMean

      public double getMean()
      Returns the mean intensity value of this Histogram.
      Returns:
      the mean value of this Histogram.

    • getMean

      public double getMean(boolean excludeZero)
      Returns the mean intensity value of this Histogram, optionally excluding all values that are zero. This is useful when an image has a background of zero, and you want to exclude the effect of the background on the mean value.
      Parameters:
      excludeZero - true if the zero-valued background is to be excluded from the calculation of the mean.
      Returns:
      the mean value of this Histogram, optionally excluding the zero-valued background.

    • getSD

      public double getSD()
      Returns the standard deviation of intensity values of this Histogram.
      Returns:
      the standard deviation of pixel intensity values of this Histogram.

    • getSD

      public double getSD(boolean excludeZero)
      Returns the standard deviation of intensity values of this Histogram, optionally excluding all values that are zero from the calculation. This is useful when an image has a background of zero, and you want to exclude the effect of the background on the SD value.
      Parameters:
      excludeZero - true if the zero-valued background is to be excluded from the calculation of the standard deviation.
      Returns:
      the standard deviation of the values of this Histogram, optionally excluding the zero-valued background.

    • getCumulativeIntensity

      public double getCumulativeIntensity(float fraction, boolean excludeZero)
      Returns a value such that the specified fraction of values is below the returned intensity; zero-valued values are optionally excluded from the calculation.
      Parameters:
      fraction - the intensity value returned is such that this fraction of values is below the returned intensity. Normally fraction would be between 0.0 and 1.0. If fraction is less than or equal to 0.0, the minimum intensity is returned. If fraction is greater than or equal to 1.0, the maximum intensity is returned.
      excludeZero - true if the zero-valued background is to be excluded from the calculation of the intensity.
      Returns:
      the intensity value such that the specified fraction of values is below the returned intensity.

    • add

      public Histogram add(Histogram histo, PixelDataType dataType)
      Adds the counts from a Histogram to this Histogram to produce a new Histogram that spans the data range of both.
      Parameters:
      histo - the Histogram from which to add the counts.
      dataType - the PixelDataType for pixel intensities from which this and the the supplied Histogram were constructed.
      Returns:
      a new Histogram compiled by adding this Histogram to the argument.

    • getAreaUnder

      public double getAreaUnder()
      Returns the total area under this histogram.
      Returns:
      the area under this Histogram. The area is the sum of the counts in all the bins multiplied by the bin width.

    • getAreaUnder

      public double getAreaUnder(boolean excludeZero)
      Returns the area under this histogram, optionally excluding any zero-valued values. This is useful when an image has a background of zero, and you want to exclude the background from the calculation of the area.
      Parameters:
      excludeZero - true if the zero-valued background is to be excluded from the calculation of the area.
      Returns:
      the area under this Histogram, optionally excluding the zero-valued background. The area is the sum of the counts in all the bins (optionally excluding zero) multiplied by the bin width.

    • getTotalCount

      public double getTotalCount()
      Returns the total number of values that contributed to this histogram.
      Returns:
      the total number of values that contributed to this Histogram. The total count is the sum of the counts in all the bins. The count returned equals the number of values used to compute the Histogram.

    • getTotalCount

      public double getTotalCount(boolean excludeZero)
      Returns the total number of values that contributed to this histogram, optionally excluding any zero-valued values. This is useful when an image has a background of zero, and you want to exclude the background from the total count.
      Parameters:
      excludeZero - true if the zero-valued background is to be excluded from the count.
      Returns:
      the total number of values in this Histogram, optionally excluding the zero-valued background. The total count is the sum of the counts in all the bins (optionally excluding zero). For integer data types, the count returned equals the number of values used to compute the Histogram (optionally excluding zero-valued values).

    • getTotalCount

      public double getTotalCount(double threshold)
      Returns the number of values in this histogram that are above the supplied threshold.
      Parameters:
      threshold - values that are below the threshold will be excluded from the count.
      Returns:
      the total counts for this Histogram, excluding the intensities that are below the threshold.

    • getEntropy

      public double getEntropy()
      Returns the entropy of this Histogram. The entropy is calculated as Sum(-p(i) log(p(i))), where p(i) is the probability (normalised frequency) of intensity i, and the sum is performed over all intensities.
      Returns:
      the entropy of this Histogram.

    • normalise

      public void normalise()
      Normalises this Histogram, so that the sum of all the counts is unity. If the sum of all counts is zero, then this method does nothing.

    • scale

      public void scale(double scale)
      Scales the counts in this Histogram, mutiplying all the count values by the supplied scaling factor.
      Parameters:
      scale - the scaling factor by which all counts will be multiplied.

    • otsuThreshold

      public double otsuThreshold()
      Calculates a threshold to separate the foreground from the background using Ostu's method of maximsing between-class variance for two classes of pixel values, where one class is assumed to be the foreground, and the other is the background.
      Returns:
      the optimal intensity threshold for separating the foreground from the background.

    • match

      public float match(Histogram h, double threshold) throws InvalidArgumentException, NumericalException
      Returns the intensity scaling factor that will best match this Histogram to another Histogram.
      Parameters:
      h - the Histogram to which the intensities should be matched.
      threshold - the intensity threshold for this Histogram. All intensities below the threshold will be ignored in the histogram matching.
      Returns:
      an intensity scaling factor such that multiplying the intensities in this Histogram will match it to the supplied Histogram.
      Throws:
      InvalidArgumentException - the Histogram is unsuitable for matching.
      NumericalException - if the Histograms cannot be matched.

    • toString

      public String toString()
      Returns a String that lists the min, max, bin width and count values of this Histogram.
      Overrides:
      toString in class Object
      Returns:
      a String that lists the min, max, bin width and count values of this Histogram.

    • main

      public static void main(String[] args)
      Run the self-test of the Histogram class.
      Parameters:
      args - ignored.