com.xinapse.multisliceimage
Class Histogram

java.lang.Object
  com.xinapse.multisliceimage.Histogram

public class Histogram
extends java.lang.Object

A class for creating and finding statistics about arrays of pixel intensities, histograms of pixel intensities, and statistics about those histograms.

Nested Class Summary

static class

Histogram.BinSpec A specification for Histogram bins.

Constructor Summary

Histogram(double[] 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(java.lang.Object pixelValues, int offset, int nPixels, PixelDataType dataType)
Creates a Histogram of intensities from an array of values.

Histogram(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.Object pixelValues, PixelDataType dataType)
Creates a Histogram of intensities from an array of values.

Histogram(java.lang.Object pixelValues, PixelDataType dataType, ComplexMode complexMode)
Creates a Histogram of intensities from an array of values.

Method Summary

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(java.lang.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, given the for 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, given the for 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-intensity pixels.
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 an intensity value such that the specified fraction of pixels is below the returned intensity; zero-valued pixels are optionally excluded from the calculation.
double	getEntropy() Returns the entropy of this Histogram.
double	getHistoMax(PixelDataType dataType) Returns the maximum value that can be added to this Histogram's bins.
double	getHistoMin() Returns the minimum bin value of this Histogram.
static Histogram	getInstance(LoadableImage image) Creates a Histogram of intensities from a com.xinapse.loadableimage.LoadableImage.
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 pixel intensities 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 pixel intensities that are zero.
static double[]	getMinMax(java.lang.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(java.lang.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 pixels with the most common pixel intensity in this Histogram, optionally excluding the pixel intensities that are zero-valued.
double	getPeakPosition(boolean excludeZero) Returns the most common pixel intensity in this Histogram, optionally excluding the pixel intensities 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 pixel intensities that are zero from the calculation.
double	getTotalCount() Returns the total number of pixels that contributed to this histogram.
double	getTotalCount(boolean excludeZero) Returns the total number of pixels that contributed to this histogram, optionally excluding any zero-intensity pixels.
double	getTotalCount(double threshold) Returns the number of pixels in this histogram that are above the supplied threshold.
static void	main(java.lang.String[] args) Run the self-test of the Histogram class.
void	normalise() Normalises this Histogram, so that the sum of all the counts is unity.
void	setCount(int binIndex, double count) Sets the count in one bin of this Histogram.
java.lang.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 Detail

Histogram

public Histogram(double[] count,
                 double histoMin,
                 double binWidth)

Creates a Histogram of intensities from pre-computed values.

Parameters:

count - the number of pixels 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(java.lang.Object pixelValues,
                 PixelDataType dataType)
          throws MultiSliceImageException

Creates a Histogram of intensities from an array of values.
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:

MultiSliceImageException - 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(java.lang.Object pixelValues,
                 PixelDataType dataType,
                 ComplexMode complexMode)
          throws MultiSliceImageException

Creates a Histogram of intensities from an array of values.
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:

MultiSliceImageException - 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(java.lang.Object pixelValues,
                 int offset,
                 int nPixels,
                 PixelDataType dataType)
          throws MultiSliceImageException

Creates a Histogram of intensities from an array of values.
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:

MultiSliceImageException - 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(java.lang.Object pixelValues,
                 int offset,
                 int nPixels,
                 PixelDataType dataType,
                 ComplexMode complexMode)
          throws MultiSliceImageException

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:

MultiSliceImageException - 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(java.lang.Object pixelValues,
                 int offset,
                 int nPixels,
                 PixelDataType dataType,
                 double min,
                 double max,
                 double binWidth,
                 ComplexMode complexMode)
          throws MultiSliceImageException

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:

MultiSliceImageException - 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(java.lang.Object pixelValues,
                 int offset,
                 int nPixels,
                 PixelDataType dataType,
                 double min,
                 double max,
                 ComplexMode complexMode)
          throws MultiSliceImageException

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:

MultiSliceImageException - 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(java.lang.Object pixelValues,
                 int offset,
                 int nPixels,
                 PixelDataType dataType,
                 double min,
                 double max,
                 int nBins,
                 ComplexMode complexMode)
          throws MultiSliceImageException

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:

MultiSliceImageException - 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 Detail

getInstance

public static Histogram getInstance(LoadableImage image)
                             throws InvalidImageException

Creates a Histogram of intensities from a com.xinapse.loadableimage.LoadableImage.
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.BYTE, and Colour images, the histogram always has 255 bins with the intensities from 0 to 255.
For PixelDataType.UBYTE, and Colour images, 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.

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(java.lang.Object pixelValues,
                      int offset,
                      int nPixels,
                      PixelDataType dataType,
                      ComplexMode complexMode)
               throws MultiSliceImageException

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:

MultiSliceImageException - 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, 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 MultiSliceImageException

Calculates a suitable bin width, number of bins, and minimum bin value for a histogram, given the for 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:

MultiSliceImageException - 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 MultiSliceImageException

Calculates a suitable bin width, and minimum bin value for a histogram, given the for 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:

MultiSliceImageException - 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(java.lang.Object pixelValues,
                                 PixelDataType dataType,
                                 ComplexMode complexMode)
                          throws MultiSliceImageException

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:

MultiSliceImageException - if a the minimum and maximum values cannot be found for the supplied data type

getMinMax

public static double[] getMinMax(java.lang.Object pixelValues,
                                 int offset,
                                 int nPixels,
                                 PixelDataType dataType,
                                 ComplexMode complexMode)
                          throws MultiSliceImageException

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:

MultiSliceImageException - 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:

java.lang.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:

java.lang.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(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.

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 pixels with the most common pixel intensity in this Histogram, optionally excluding the pixel intensities 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 pixels with the most common pixel intensity 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 pixel intensity in this Histogram, optionally excluding the pixel intensities 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 pixel intensity 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 pixel intensity of this Histogram.

getMedian

public double getMedian(boolean excludeZero)

Returns the median value of this Histogram, optionally excluding all pixel intensities 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 pixel intensity of this Histogram, optionally excluding the zero-valued background.

getMean

public double getMean()

Returns the mean intensity value of this Histogram.

Returns:

the mean pixel intensity of this Histogram.

getMean

public double getMean(boolean excludeZero)

Returns the mean intensity value of this Histogram, optionally excluding all pixel intensities 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 pixel intensity 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 pixel intensities 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 pixel intensity values of this Histogram, optionally excluding the zero-valued background.

getCumulativeIntensity

public double getCumulativeIntensity(float fraction,
                                     boolean excludeZero)

Returns an intensity value such that the specified fraction of pixels is below the returned intensity; zero-valued pixels are optionally excluded from the calculation.

Parameters:

fraction - the intensity value returned is such that this fraction of pixels 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.

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.

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-intensity pixels. 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 pixels that contributed to this histogram.

Returns:

the total number of pixels 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 pixels used to compute the Histogram.

getTotalCount

public double getTotalCount(boolean excludeZero)

Returns the total number of pixels that contributed to this histogram, optionally excluding any zero-intensity pixels. 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 pixel count.

Returns:

the total number of pixels 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 pixels used to compute the Histogram (optionally excluding zero-intensity pixels).

getTotalCount

public double getTotalCount(double threshold)

Returns the number of pixels in this histogram that are above the supplied threshold.

Parameters:

threshold - pixel intensity values that are below the threshold will be excluded from the count.

Returns:

the 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.

toString

public java.lang.String toString()

Returns a String that lists the min, max, bin width and count values of this Histogram.

Overrides:

toString in class java.lang.Object

Returns:

a String that lists the min, max, bin width and count values of this Histogram.

main

public static void main(java.lang.String[] args)

Run the self-test of the Histogram class.

Parameters:

args - ignored.