javax.media.jai.operator
Class ExtremaDescriptor

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

public class ExtremaDescriptor
extends OperationDescriptorImpl

An OperationDescriptor describing the "Extrema" operation.

The Extrema operation scans a specific region of a rendered image and finds the maximum and minimum pixel values for each band within that region of the image. The image data pass through this operation unchanged.

The region-wise maximum and minimum pixel values may be obtained as properties. Calling the getProperty method on this operation with "extrema" as the property name retrieves both the region-wise maximum and minimum pixel values. Calling it with "maximum" as the property name retrieves the region-wise maximum pixel value, and with "minimum" as the property name retrieves the region-wise minimum pixel value. The return value for "extrema" has type double[2][#bands], and those for "maximum" and "minimum" have type double[#bands].

The region of interest (ROI) does not have to be a rectangle. It may be null, in which case the entire image is scanned to find the image-wise maximum and minimum pixel values for each band.

The set of pixels scanned may be further reduced by specifying the "xPeriod" and "yPeriod" parameters that represent the sampling rate along each axis. These variables may not be less than 1. However, they may be null, in which case the sampling rate is set to 1; that is, every pixel in the ROI is processed.

The Boolean parameter "saveLocations" indicates whether the locations of the extrema will be computed. If TRUE, the locations are computed and stored in the properties "minLocations" and "maxLocations" in the form of lists of run length codes. Each run length code is stored as a three-entry integer array (xStart, yStart, length). Because the statistics are implemented on the low-resolution image, this length is defined on the image coordinate system of the low-resolution image. Thus, the run length code above means the pixels (xStart, yStart), (xStart + xPeriod, yStart), ..., (xStart + (length - 1) * xPeriod, yStart) of the original image have a value of the maximum or minimum, depending on whether this run exists in the property "maxLocations" or "minLocations". The run length code is row-based, thus the run doesn't wrap on the image boundaries. Runs are not guaranteed to be maximal, e.g. a run that crosses tile boundaries might be broken at the boundary into multiple runs. The order of the runs is not guaranteed.

The value objects of the properties "minLocations" and "maxLocations" are arrays of java.util.List. Each array entry contains the minimum/maximum locations of one band. The elements in a list can be accessed using the iterator of the java.util.List. For example, the sample code below demonstrates how to retrieve the minimum locations of the first band:

	List minLocations = ((List[])extremaOp.getProperty("minLocations"))[0];
	Iterator iter = minLocations.iterator();
	while(iter.hasNext()) {
	    int[] runLength = (int[])iter.next();
	    int xStart = runLength[0];
          int yStart = runLength[1];
          int length = runLength[2];
      }
 

In the implementation of this operator, the proper use of the parameter "saveLocations" also helps to keep the efficiency of the operator in the common case: when only the extremal values are computed.

The parameter "maxRuns" is the maximum number of run length codes that the user would like to store. It is defined to reduce memory consumption on very large images. If the parameter "saveLocations" is FALSE, this parameter will be ignored. If this parameter is equal to Integer.MAX_VALUE, all the locations will be saved.

Resource List
Name Value
GlobalName Extrema
LocalName Extrema
Vendor com.sun.media.jai
Description Finds the maximum and minimum pixel value in each band of an image.
DocURL http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/ExtremaDescriptor.html
Version 1.0
arg0Desc The region of the image to scan.
arg1Desc The horizontal sampling rate, may not be less than 1.
arg2Desc The vertical sampling rate, may not be less than 1.
arg3Desc Whether to store extrema locations.
arg4Desc Maximum number of run length codes to store.

Parameter List
Name Class Type Default Value
roi javax.media.jai.ROI null
xPeriod java.lang.Integer 1
yPeriod java.lang.Integer 1
saveLocations java.lang.Boolean Boolean.FALSE
maxRuns java.lang.Integer 1

See Also:
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
ExtremaDescriptor()
          Constructor.
 
Method Summary
static RenderedOp create(RenderedImage source0, ROI roi, Integer xPeriod, Integer yPeriod, Boolean saveLocations, Integer maxRuns, RenderingHints hints)
          Finds the maximum and minimum pixel value in each band of an image.
 Number getParamMinValue(int index)
          Returns the minimum legal value of a specified numeric parameter for this operation.
 
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, 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

ExtremaDescriptor

public ExtremaDescriptor()
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)

create

public static RenderedOp create(RenderedImage source0,
                                ROI roi,
                                Integer xPeriod,
                                Integer yPeriod,
                                Boolean saveLocations,
                                Integer maxRuns,
                                RenderingHints hints)
Finds the maximum and minimum pixel value in each band 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 scan. 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.
saveLocations - Whether to store extrema locations. May be null.
maxRuns - Maximum number of run length codes to store. 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