

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: INNER  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object  +javax.media.jai.Histogram
This class represents a histogram accumulated from a
RenderedImage
.
A "bin" is a container, where each element stores the total number of pixel samples of an image whose values lie within a given range. A histogram of an image consists of a list of such bins whose range does not overlap with each other (mutually exclusive). For an image that has multiple samples per pixel (multibanded images), a separate list of bins represents each individual band.
A "lowvalue" specifies the lowest inclusive pixel value to be
checked, and a "highvalue" specifies the highest exclusive pixel
value to be checked. Therefore, the width of a bin
(binWidth
) is determined by
(highValue  lowValue) / numberOfBins
. The range
of bin i
is defined as from
lowValue + i * binWidth
inclusive to
lowValue + (i + 1) * binWidth
exclusive.
The image may have any data type. Its histogram may be accumulated over the entire image, or over a specific regionofinterest (ROI) within the image's bounds. Furthermore, the horizontal and vertical subsampling factors specify the rate of sampling in the two directions, so that only every nth pixel will be counted. This allows the accuracy of the histogram to be traded for the speed of the computation. Of course a subsampling rate of 1 means every pixel will be counted.
The "Histogram" operator generates the histogram data of an image
and uses this object to store the final pixel counts. The operator
returns an instance of this class when a request is made via the
getProperty
method for the "histogram" property. The actual
bins may be obtained by calling the getBins
method.
ROI
,
HistogramDescriptor
, Serialized FormConstructor Summary  
Histogram(int[] numBins,
double[] lowValue,
double[] highValue)
Constructor. 

Histogram(int[] numBins,
double[] lowValue,
double[] highValue,
int numBands)
Constructor. 

Histogram(int numBins,
double lowValue,
double highValue,
int numBands)
Constructor. 
Method Summary  
void 
clearHistogram()
Resets the values of all bins to zero. 
void 
countPixels(Raster raster,
ROI roi,
int xStart,
int yStart,
int xPeriod,
int yPeriod)
Accumulates the histogram of the pixels within a specific regionofinterest (ROI) by counting them based on the indicated horizontal and vertical sampling period. 
double 
getBinLowValue(int band,
int bin)
Returns the lowest inclusive pixel value of a given bin for a specific band. 
int[][] 
getBins()
Returns the array of bands of bins, each bin is the histogram for a band, i.e., the format of the returned array is int[bands][bins] . 
int[] 
getBins(int band)
Returns the bins of the histogram for a specific band by reference. 
int 
getBinSize(int band,
int bin)
Returns the number of pixel samples found in a given bin for a specific band. 
double[] 
getEntropy()
Returns the entropy of the histogram. 
Histogram 
getGaussianSmoothed(double standardDeviation)
Computes a Gaussian smoothed version of the histogram. 
double[] 
getHighValue()
Returns the highest exclusive pixel value checked for all bands. 
double 
getHighValue(int band)
Returns the highest exclusive pixel value checked for a specific band. 
double[] 
getIterativeThreshold()
Calculates the threshold using iterative bisection. 
double[] 
getLowValue()
Returns the lowest inclusive pixel value checked for all bands. 
double 
getLowValue(int band)
Returns the lowest inclusive pixel value checked for a specific band. 
double[] 
getMaxEntropyThreshold()
Calculates the threshold which maximizes the entropy. 
double[] 
getMaxVarianceThreshold()
Calculates the threshold which maximizes the ratio of the betweenclass variance to the withinclass variance for each band. 
double[] 
getMean()
Returns the mean values for all bands of the histogram. 
double[] 
getMinErrorThreshold()
Calculates the threshold which minimizes the probability of error. 
double[] 
getMinFuzzinessThreshold()
Calculates the threshold which minimizes the fuzziness. 
double[] 
getModeThreshold(double power)
Calculates the threshold using the mode method. 
double[] 
getMoment(int moment,
boolean isAbsolute,
boolean isCentral)
Returns a specified (absolute) (central) moment of the histogram. 
int 
getNumBands()
Returns the number of bands of the histogram. 
int[] 
getNumBins()
Returns the number of bins of the histogram for all bands. 
int 
getNumBins(int band)
Returns the number of bins of the histogram for a specific band. 
double[] 
getPTileThreshold(double p)
Calculates the ptile threshold. 
Histogram 
getSmoothed(boolean isWeighted,
int k)
Computes a smoothed version of the histogram. 
double[] 
getStandardDeviation()
Returns the standard deviation for all bands of the histogram. 
int 
getSubTotal(int band,
int minBin,
int maxBin)
Returns the total bin count for the specified subrange (via "min" and "max" bin) of the indicated band. 
int[] 
getTotals()
Returns the total bin count over all bins for all bands. 
Methods inherited from class java.lang.Object 
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait 
Constructor Detail 
public Histogram(int[] numBins, double[] lowValue, double[] highValue)
This constructor should be used when numBins
,
lowValue
, and/or highValues
are
different for each band of the image. The length of the arrays
indicates the number of bands the image has, and the three arrays
must have the same length.
Since this constructor has no way of knowing the actual number of bands of the image, the length of the arrays is not checked against anything. Therefore, it is very important that the caller supplies the correct arrays of correct lengths, or errors will occur.
numBins
 The number of bins for each band of the image.
The length of this array indicates the number of bands for
this histogram.lowValue
 The lowest inclusive pixel value checked for
each band.highValue
 The highest exclusive pixel value checked for
each band.IllegalArgumentException
 If numBins
,
lowValue
, or highValue
is
null
.IllegalArgumentException
 If the array length of the three
arguments are not the same, or any array length is 0.IllegalArgumentException
 If the number of bins for any band
is less than or equal to 0.IllegalArgumentException
 If the lowvalue of any band is
greater than or equal to its corresponding highvalue.public Histogram(int[] numBins, double[] lowValue, double[] highValue, int numBands)
This constructor should be used when numBins
,
lowValue
, and/or highValues
may be
different for each band of the image. The number of bands in the
image is provided explicitly. If any of the arrays provided
has a length which is less than the number of bands, the first
element in that array is used to fill out the array to a length
of numBands
.
numBins
 The number of bins for each band of the image.lowValue
 The lowest inclusive pixel value checked for
each band.highValue
 The highest exclusive pixel value checked for
each band.numBands
 The number of bands in the image.IllegalArgumentException
 If numBins
,
lowValue
, or highValue
is
null
.IllegalArgumentException
 If any array length is 0.IllegalArgumentException
 If the number of bins for any band
is less than or equal to 0.IllegalArgumentException
 If the lowvalue of any band is
greater than or equal to its corresponding highvalue.IllegalArgumentException
 If numBands
is less
than or equal to 0.public Histogram(int numBins, double lowValue, double highValue, int numBands)
The same numBins
, lowValue
, and
highValue
is applied to every band of the image.
numBins
 The number of bins for all bands of the image.lowValue
 The lowest inclusive pixel value checked for
all bands.highValue
 The highest exclusive pixel value checked for
all bands.numBands
 The number of bands of the image.IllegalArgumentException
 If numBins
or
numBands
is less than or equal to 0.IllegalArgumentException
 If lowValue
is less than or equal to highValue
.Method Detail 
public int[] getNumBins()
public int getNumBins(int band)
band
 The index of the band whose numBins
is to be returned.ArrayIndexOutOfBoundsException
 If an invalid band index
is specified.public double[] getLowValue()
public double getLowValue(int band)
band
 The index of the band whose lowValue
is to be returned.ArrayIndexOutOfBoundsException
 If an invalid band index
is specified.public double[] getHighValue()
public double getHighValue(int band)
band
 The index of the band whose highValue
is to be returned.ArrayIndexOutOfBoundsException
 If an invalid band index
is specified.public int getNumBands()
bins.length
.public int[][] getBins()
int[bands][bins]
.public int[] getBins(int band)
band
 The index of the band whose bins
are to be returned.ArrayIndexOutOfBoundsException
 If an invalid band index
is specified.public int getBinSize(int band, int bin)
band
 The index of the bandofinterest.bin
 The index of the bin whose value is to be returned.ArrayIndexOutOfBoundsException
 If an invalid band or
bin index is specified.public double getBinLowValue(int band, int bin)
band
 The index of the bandofinterest.bin
 The index of the bin whose lowValue
is to be returned.ArrayIndexOutOfBoundsException
 If an invalid band
index is specified.public void clearHistogram()
bins
has
not been initialized (null
), this method does nothing.public int[] getTotals()
An array which stores the total bin count is kept in this class
and a reference to this array is returned by this method for
performance reasons. The elements of the returned array should
not be modified or undefined errors may occur. The array format is
int[numBands]
.
public int getSubTotal(int band, int minBin, int maxBin)
band
 The index of the bandofinterest.minBin
 The minimum bin index to be counted.maxBin
 The maximum bin index to be counted.ArrayIndexOutOfBoundsException
 If an invalid band index
is specified.IllegalArgumentException
 If minBin
is greater than
maxBin
.public double[] getMean()
public void countPixels(Raster raster, ROI roi, int xStart, int yStart, int xPeriod, int yPeriod)
bins
array and may be obtained
by calling the getBins
method.
The ROI
specifies the region within which
the pixels are counted. If it is null
, the
entire Raster
is counted. If it is not
null
and does not intersect with the
Raster
, then this method returns without changing
the bins
.
The set of pixels to be counted may be obtained by
intersecting the grid (xStart + i * xPeriod,
yStart + j * yPeriod); i, j >= 0
with the ROI
and the bounding rectangle of the Raster
.
raster
 The Raster that contains the pixels to be counted.roi
 The regionofinterest within which the pixels are counted.xStart
 The initial X sample coordinate.yStart
 The initial Y sample coordinate.xPeriod
 The X sampling period.yPeriod
 The Y sampling period.IllegalArgumentException
 If raster
is
null
.IllegalArgumentException
 If the pixels stored in the
raster
do not have the same number of bands
(samples per pixel) as this histogram's bins.public double[] getMoment(int moment, boolean isAbsolute, boolean isCentral)
The ith moment in each band is defined to be the mean of the image pixel values raised to the ith power in that band. For central moments the average of the ith power of the deviation from the mean is used. For absolute moments the absolute value of the exponentiated term is used.
Note that the mean is the first moment, the average energy the second central moment, etc.
moment
 The moment number or index which must be positive or
an IllegalArgumentException
will be thrown.isAbsolute
 Whether to calculate the absolute moment.isCentral
 Whether to calculate the central moment.public double[] getStandardDeviation()
public double[] getEntropy()
The histogram entropy is defined to be the negation of the sum of the products of the probability associated with each bin with the base2 log of the probability.
public Histogram getSmoothed(boolean isWeighted, int k)
Each band of the histogram is smoothed by averaging over a moving window of a size specified by the method parameter: if the value of the parameter is k then the width of the window is 2*k + 1. If the window runs off the end of the histogram only those values which intersect the histogram are taken into consideration. The smoothing may optionally be weighted to favor the central value using a "triangular" weighting. For example, for a value of k equal to 2 the central bin would have weight 1/3, the adjacent bins 2/9, and the next adjacent bins 1/9.
isWeighted
 Whether bins will be weighted using a triangular
weighting scheme favoring bins near the central bin.k
 The smoothing parameter which must be nonnegative or an
IllegalArgumentException
will be thrown. If zero, the
histogram object will be returned with no smoothing applied.public Histogram getGaussianSmoothed(double standardDeviation)
Each band of the histogram is smoothed by discrete convolution with a kernel approximating a Gaussian impulse response with the specified standard deviation.
standardDeviation
 The standard deviation of the Gaussian
smoothing kernel which must be nonnegative or an
IllegalArgumentException
will be thrown. If zero, the
histogram object will be returned with no smoothing applied.public double[] getPTileThreshold(double p)
Computes thresholds such that a specified proportion of the sample values in each band are below the threshold.
p
 The proportion of samples in each band which should be below
the threshold in the band. If p
is not in the range
(0.0, 1.0) an IllegalArgumentException
will be thrown.public double[] getModeThreshold(double power)
The threshold is defined to be the minimum between two peaks. The first peak is the highest peak in the histogram. The second peak is the highest peak in the histogram weighted by a specified power of the distance from the first peak.
power
 The exponent of the distance weighting from the
first peak.public double[] getIterativeThreshold()
For each band an initial threshold is defined to be the midpoint of the range of data represented by the histogram. The mean value is calculated for each subhistogram and a new threshold is defined as the arithmetic mean of the two subhistogram means. This process is repeated until the threshold value no longer changes.
public double[] getMaxVarianceThreshold()
public double[] getMaxEntropyThreshold()
The entropy of a range of gray levels is defined to be the negation of the sum of products of the probability and the logarithm thereof over all gray levels in the range. The maximum entropy threshold is defined to be that value which maximizes the sum of the entropy of the two ranges which are above and below the threshold, respectively. This computation is effected for each band.
public double[] getMinErrorThreshold()
For each band the histogram is modeled as the sum of two Gaussian distributions and the threshold which minimizes the misclassification error is computed. If the underlying histogram is unimodal the mean value of each band will be returned as the threshold. The bimodality of the histogram for that band will be identically zero.
public double[] getMinFuzzinessThreshold()


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: INNER  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 