javax.media.jai.operator
Class HistogramDescriptor

java.lang.Object
  extended byjavax.media.jai.OperationDescriptorImpl
      extended byjavax.media.jai.operator.HistogramDescriptor
All Implemented Interfaces:
OperationDescriptor, RegistryElementDescriptor, Serializable

public class HistogramDescriptor
extends OperationDescriptorImpl

This OperationDescriptor defines the "Histogram" operation.

A histogram of an image is represented by a list of "bins" where each bin is the total number of pixel samples of the image whose values lie within a given range. This data are encapulated in the javax.media.jai.Histogram object, and may be retrieved by calling the getProperty method on this operator with "histogram" as the property name.

At a request for the histogram property, this operator scans the specific region of the source image, generates the pixel count data, and returns an instance of the Histogram class where the data are stored. The source image's pixels are unchanged by this operator.

The region-of-interest (ROI), within which the pixels are counted, does not have to be a rectangle. It may be null, in which case the entire image is scanned to accumulate the histogram.

The set of pixels scanned may be further reduced by specifying the "xPeriod" and "yPeriod" parameters that represent the sampling rate along the two axis. These variables may not be less than 1. If they are not set, the default value of 1 is used so that every pixel within the ROI is counted.

The three arguments, numBins, lowValue, and highValue, define the type of the histogram to be generated. Please see the Histogram specification for their detailed descriptions. The three arrays must either have an array length of 1, in which case the same value is applied to all bands of the source image, or an array length that equals to the number of bands of the source image, in which case each value is applied to its corresponding band. The numBins must all be greater than 0, and each lowValue must be less than its corresponding highValue. Note that the default values of these three parameters are specific to the case wherein the image data are of type byte. For other image data types the values of these parameters should be supplied explicitely.

Resource List
Name Value
GlobalName Histogram
LocalName Histogram
Vendor com.sun.media.jai
Description Generates a histogram based on the pixel values within a specific region of an image.
DocURL http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/HistogramDescriptor.html
Version 1.1
arg0Desc The region of the image to be scanned.
arg1Desc The horizontal sampling rate; may not be less than 1.
arg2Desc The vertical sampling rate; may not be less than 1.
arg3Desc The number of bins for each band.
arg4Desc The lowest inclusive pixel value to be checked for each band.
arg5Desc The highest exclusive pixel value to be checked for each band.

Parameter List
Name Class Type Default Value
roi javax.media.jai.ROI null
xPeriod java.lang.Integer 1
yPeriod java.lang.Integer 1
numBins int[] {256}
lowValue double[] {0.0}
highValue double[] {256.0}

See Also:
Histogram, ROI, OperationDescriptor, Serialized Form

Field Summary
 
Fields inherited from class javax.media.jai.OperationDescriptorImpl
sourceNames, supportedModes
 
Fields inherited from interface javax.media.jai.OperationDescriptor
NO_PARAMETER_DEFAULT
 
Constructor Summary
HistogramDescriptor()
          Constructor.
 
Method Summary
static RenderedOp create(RenderedImage source0, ROI roi, Integer xPeriod, Integer yPeriod, int[] numBins, double[] lowValue, double[] highValue, RenderingHints hints)
          Generates a histogram based on the pixel values within a specific region of an image.
 Number getParamMinValue(int index)
          Returns the minimum legal value of a specified numeric parameter for this operation.
protected  boolean validateParameters(ParameterBlock args, StringBuffer msg)
          Returns true if this operation is capable of handling the input parameters.
 
Methods inherited from class javax.media.jai.OperationDescriptorImpl
arePropertiesSupported, getDefaultSourceClass, getDestClass, getDestClass, getInvalidRegion, getName, getNumParameters, getNumSources, getParamClasses, getParamDefaults, getParamDefaultValue, getParameterListDescriptor, getParamMaxValue, getParamNames, getPropertyGenerators, getPropertyGenerators, getRenderableDestClass, getRenderableSourceClasses, getResourceBundle, getResources, getSourceClasses, getSourceClasses, getSourceNames, getSupportedModes, isImmediate, isModeSupported, isRenderableSupported, isRenderedSupported, makeDefaultSourceClassList, validateArguments, validateArguments, validateParameters, validateRenderableArguments, validateRenderableSources, validateSources, validateSources
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

HistogramDescriptor

public HistogramDescriptor()
Constructor.

Method Detail

getParamMinValue

public Number getParamMinValue(int index)
Returns the minimum legal value of a specified numeric parameter for this operation.

Specified by:
getParamMinValue in interface OperationDescriptor
Overrides:
getParamMinValue in class OperationDescriptorImpl
Parameters:
index - The index of the parameter to be queried.
Returns:
A Number representing the minimum legal value, or null if the specified parameter is not numeric.
See Also:
ParameterListDescriptor.getParamValueRange(java.lang.String), ParameterListDescriptor.getEnumeratedParameterValues(java.lang.String), ParameterListDescriptor.isParameterValueValid(java.lang.String, java.lang.Object)

validateParameters

protected boolean validateParameters(ParameterBlock args,
                                     StringBuffer msg)
Returns true if this operation is capable of handling the input parameters.

In addition to the default validations done in the super class, this method verifies that each element of numBins is greater than 0, and each lowValue is less than its corresponding highValue.

Overrides:
validateParameters in class OperationDescriptorImpl
Throws:
IllegalArgumentException - If args is null.
IllegalArgumentException - If msg is null and the validation fails.
See Also:
OperationDescriptorImpl.validateParameters(java.lang.String, java.awt.image.renderable.ParameterBlock, java.lang.StringBuffer)

create

public static RenderedOp create(RenderedImage source0,
                                ROI roi,
                                Integer xPeriod,
                                Integer yPeriod,
                                int[] numBins,
                                double[] lowValue,
                                double[] highValue,
                                RenderingHints hints)
Generates a histogram based on the pixel values within a specific region of an image.

Creates a ParameterBlockJAI from all supplied arguments except hints and invokes JAI.create(String,ParameterBlock,RenderingHints).

Parameters:
source0 - RenderedImage source 0.
roi - The region of the image to be scanned. May be null.
xPeriod - The horizontal sampling rate; may not be less than 1. May be null.
yPeriod - The vertical sampling rate; may not be less than 1. May be null.
numBins - The number of bins for each band. May be null.
lowValue - The lowest inclusive pixel value to be checked for each band. May be null.
highValue - The highest exclusive pixel value to be checked for each band. May be null.
hints - The RenderingHints to use. May be null.
Returns:
The RenderedOp destination.
Throws:
IllegalArgumentException - if source0 is null.
See Also:
JAI, ParameterBlockJAI, RenderedOp