org.geotools.gp
Class OperationJAI

java.lang.Object
  org.geotools.gp.Operation
      org.geotools.gp.OperationJAI

All Implemented Interfaces:

java.io.Serializable

public class OperationJAI

extends Operation

Wrap an OperationDescriptor for interoperability with Java Advanced Imaging. This class help to leverage the rich set of JAI operators in an OpenGIS framework. OperationJAI inherits operation name and argument types from OperationDescriptor, except source argument type which is set to GridCoverage.class. If there is only one source argument, il will be renamed "Source" for better compliance to OpenGIS usage.

The entry point for applying operation is the usual doOperation method. The default implementation forward the call to other methods for different bits of tasks, resulting in the following chain of calls:

1. doOperation (the entry point)
2. resampleToCommonGeometry (reproject all source to the same coordinate system)
3. deriveGridCoverage (gets the destination properties)
4. deriveSampleDimension(org.geotools.cv.SampleDimension[][], org.geotools.gp.OperationJAI.Parameters) (gets the destination sample dimensions)
5. deriveCategory(org.geotools.cv.Category[], org.geotools.gp.OperationJAI.Parameters) (gets the destination categories)
6. deriveUnit(org.geotools.units.Unit[], org.geotools.gp.OperationJAI.Parameters) (gets the destination units)
7. createRenderedImage(javax.media.jai.ParameterBlockJAI, java.awt.RenderingHints) (the actual call to JAI.createNS)

Version:

$Id: OperationJAI.java 17672 2006-01-19 00:25:55Z desruisseaux $

Author:

Martin Desruisseaux

See Also:

Serialized Form

Nested Class Summary

protected static class

OperationJAI.Parameters A block of parameters for a GridCoverage processed by a OperationJAI.

Field Summary

protected javax.media.jai.OperationDescriptor

descriptor The operation descriptor.

Fields inherited from class org.geotools.gp.Operation

MONADIC

Constructor Summary

	OperationJAI(javax.media.jai.OperationDescriptor descriptor) Construct an OpenGIS operation from a JAI operation descriptor.
	OperationJAI(java.lang.String operationName) Construct an OpenGIS operation from a JAI operation name.
protected	OperationJAI(java.lang.String name, javax.media.jai.OperationDescriptor operationDescriptor, javax.media.jai.ParameterListDescriptor paramDescriptor) Construct an OpenGIS operation backed by a JAI operation.

Method Summary

protected java.awt.image.RenderedImage	createRenderedImage(javax.media.jai.ParameterBlockJAI parameters, java.awt.RenderingHints hints) Apply the JAI operation.
protected Category	deriveCategory(Category[] categories, OperationJAI.Parameters parameters) Derive the quantitative category for a sample dimension in the destination coverage.
protected GridCoverage	deriveGridCoverage(GridCoverage[] sources, OperationJAI.Parameters parameters) Apply a JAI operation to a grid coverage.
protected java.lang.String	deriveName(GridCoverage source, OperationJAI.Parameters parameters) Returns a name for the target grid coverage based on the given source.
protected SampleDimension[]	deriveSampleDimension(SampleDimension[][] bandLists, OperationJAI.Parameters parameters) Derive the SampleDimensions for the destination image.
protected Unit	deriveUnit(Unit[] units, OperationJAI.Parameters parameters) Derive the unit of data for a sample dimension in the destination coverage.
protected GridCoverage	doOperation(javax.media.jai.ParameterList parameters, java.awt.RenderingHints hints) Apply a process operation to a grid coverage.
boolean	equals(java.lang.Object object) Compares the specified object with this operation for equality.
java.lang.String	getDescription(java.util.Locale locale) Returns the description of the processing operation.
protected static javax.media.jai.JAI	getJAI(java.awt.RenderingHints hints) Returns the JAI instance to use for operations on RenderedImage.
int	getNumSources() Returns the number of source grid coverages required for the operation.
protected static javax.media.jai.OperationDescriptor	getOperationDescriptor(java.lang.String name) Returns the operation descriptor for the specified JAI operation name.
protected void	resampleToCommonGeometry(GridCoverage[] sources, CoordinateSystem coordinateSystem, MathTransform gridToCS, java.awt.RenderingHints hints) Resample all sources grid coverages to the same geometry before to apply an operation.

Methods inherited from class org.geotools.gp.Operation

getGridCoverageProcessor, getName, getNumParameters, getParameterInfo, getParameterInfo, getParameterList, getParameterListDescriptor, hashCode, print, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

descriptor

protected final javax.media.jai.OperationDescriptor descriptor

The operation descriptor.

Constructor Detail

OperationJAI

public OperationJAI(java.lang.String operationName)
             throws OperationNotFoundException

Construct an OpenGIS operation from a JAI operation name. This convenience constructor fetch the OperationDescriptor from the specified operation name using the default JAI instance.

Parameters:

operationName - JAI operation name (e.g. "GradientMagnitude").

Throws:

OperationNotFoundException - if no JAI descriptor was found for the given name.

OperationJAI

public OperationJAI(javax.media.jai.OperationDescriptor descriptor)

Construct an OpenGIS operation from a JAI operation descriptor. The OpenGIS operation will have the same name than the JAI operation.

Parameters:

descriptor - The operation descriptor. This descriptor must supports the "rendered" mode (which is the case for most JAI operations).

OperationJAI

protected OperationJAI(java.lang.String name,
                       javax.media.jai.OperationDescriptor operationDescriptor,
                       javax.media.jai.ParameterListDescriptor paramDescriptor)

Construct an OpenGIS operation backed by a JAI operation.

Parameters:

name - The operation name for GridCoverageProcessor registration. May or may not be the same than the JAI operation name. If null, then the JAI operation name is used.

operationDescriptor - The operation descriptor. This descriptor must supports supports the "rendered" mode (which is the case for most JAI operations).

paramDescriptor - The parameters descriptor. If null, then it will be infered from the JAI's parameter descriptor.

Throws:

java.lang.NullPointerException - if operationDescriptor is null.

Method Detail

getOperationDescriptor

protected static javax.media.jai.OperationDescriptor getOperationDescriptor(java.lang.String name)
                                                                     throws OperationNotFoundException

Returns the operation descriptor for the specified JAI operation name. This method uses the default JAI instance and looks for the "rendered" mode.

Parameters:

name - The operation name.

Returns:

The operation descriptor for the given name.

Throws:

OperationNotFoundException - if no JAI descriptor was found for the given name.

getDescription

public java.lang.String getDescription(java.util.Locale locale)

Returns the description of the processing operation. If there is no description, returns null. The default implementation fetch the description from the descriptor.

Overrides:

getDescription in class Operation

Parameters:

locale - The desired locale, or null for the default locale.

See Also:

GP_Operation.getDescription()

getNumSources

public int getNumSources()

Returns the number of source grid coverages required for the operation. The default implementation fetch the information from the descriptor.

Overrides:

getNumSources in class Operation

See Also:

GP_Operation.getNumSources()

doOperation

protected GridCoverage doOperation(javax.media.jai.ParameterList parameters,
                                   java.awt.RenderingHints hints)

Apply a process operation to a grid coverage. The default implementation performs the following steps:

• Convert source grid coverages to their geophysics view, using GridCoverage.geophysics(true). This allow to performs all computation on geophysics values instead of encoded samples.
• Ensure that every source GridCoverages use the same coordinate system and have the same envelope.
• Invoke deriveGridCoverage(org.geotools.gc.GridCoverage[], org.geotools.gp.OperationJAI.Parameters). The sources in the ParameterBlock are RenderedImage objects obtained from GridCoverage.getRenderedImage().
• If the source GridCoverages was not a geophysics view, convert the result back to the same type with GridCoverage.geophysics(false).

Specified by:

doOperation in class Operation

Parameters:

parameters - List of name value pairs for the parameters required for the operation.

hints - A set of rendering hints, or null if none.

Returns:

The result as a grid coverage.

See Also:

deriveGridCoverage(org.geotools.gc.GridCoverage[], org.geotools.gp.OperationJAI.Parameters)

resampleToCommonGeometry

protected void resampleToCommonGeometry(GridCoverage[] sources,
                                        CoordinateSystem coordinateSystem,
                                        MathTransform gridToCS,
                                        java.awt.RenderingHints hints)
                                 throws InvalidGridGeometryException,
                                        CannotReprojectException

Resample all sources grid coverages to the same geometry before to apply an operation. Subclasses should overrides this method if they want to specify a target grid geometry and coordinate system different than the default one.

Parameters:

sources - The source grid coverages to resample. This array is updated in-place as needed.

coordinateSystem - The target coordinate system to use, or null for a default one.

gridToCS - The target "grid to coordinate system" transform, or null for a default one.

hints - The rendering hints, or null if none.

Throws:

InvalidGridGeometryException - if a source coverage has an unsupported grid geometry.

CannotReprojectException - if a grid coverage can't be resampled for some other reason.

deriveGridCoverage

protected GridCoverage deriveGridCoverage(GridCoverage[] sources,
                                          OperationJAI.Parameters parameters)

Apply a JAI operation to a grid coverage. The default implementation performs the following steps:

• Get the SampleDimensions for the target images by invoking the deriveSampleDimension(...) method.
• Apply the operation using the following pseudo-code:

   JAI.createNS(descriptor.getName(), parameters, hints)
   

Parameters:

sources - The source coverages.

parameters - Parameters, rendering hints and coordinate system to use.

Returns:

The result as a grid coverage.

See Also:

doOperation(javax.media.jai.ParameterList, java.awt.RenderingHints), deriveSampleDimension(org.geotools.cv.SampleDimension[][], org.geotools.gp.OperationJAI.Parameters), JAI.createNS(java.lang.String, java.awt.image.renderable.ParameterBlock, java.awt.RenderingHints)

deriveSampleDimension

protected SampleDimension[] deriveSampleDimension(SampleDimension[][] bandLists,
                                                  OperationJAI.Parameters parameters)

Derive the SampleDimensions for the destination image. The default implementation iterate among all bands and invokes the deriveCategory and deriveUnit methods for each individual band.

Parameters:

bandLists - SampleDimensions for each band in each source GridCoverages. For a band (or "sample dimension") band in a source coverage source, the corresponding SampleDimension is bandLists[source][band].

parameters - Parameters, rendering hints and coordinate system to use.

Returns:

The sample dimensions for each band in the destination image. The length of this array must matches the number of bands in the destination image. If the SampleDimensions are unknow, then this method may returns null.

See Also:

deriveCategory(org.geotools.cv.Category[], org.geotools.gp.OperationJAI.Parameters), deriveUnit(org.geotools.units.Unit[], org.geotools.gp.OperationJAI.Parameters)

deriveCategory

protected Category deriveCategory(Category[] categories,
                                  OperationJAI.Parameters parameters)

Derive the quantitative category for a sample dimension in the destination coverage. This method is invoked automatically by the deriveSampleDimension method for each band in the destination image. Subclasses should override this method in order to compute the destination Category from the source categories. For example, the "add" operation may implements this method as below:

 NumberRange r0 = categories[0].getRange();
 NumberRange r1 = categories[0].getRange();
 double min = r0.getMinimum() + r1.getMinimum();
 double min = r0.getMaximum() + r1.getMaximum();
 NumberRange newRange = new NumberRange(min, max);
 return new Category("My category", null, r0, newRange);
 

Parameters:

categories - The quantitative categories from every sources. For unary operations like "GradientMagnitude", this array has a length of 1. For binary operations like "add" and "multiply", this array has a length of 2.

parameters - Parameters, rendering hints and coordinate system to use.

Returns:

The quantative category to use in the destination image, or null if unknow.

deriveUnit

protected Unit deriveUnit(Unit[] units,
                          OperationJAI.Parameters parameters)

Derive the unit of data for a sample dimension in the destination coverage. This method is invoked automatically by the deriveSampleDimension method for each band in the destination image. Subclasses should override this method in order to compute the destination units from the source units. For example, the "multiply" operation may implement this method as below:

 if (units[0]!=null && units[1]!=null) {
     return units[0].multiply(units[1]);
 } else {
     return super.deriveUnit(units, cs, parameters);
 }
 

Parameters:

units - The units from every sources. For unary operations like "GradientMagnitude", this array has a length of 1. For binary operations like "add" and "multiply", this array has a length of 2.

parameters - Parameters, rendering hints and coordinate system to use.

Returns:

The unit of data in the destination image, or null if unknow.

deriveName

protected java.lang.String deriveName(GridCoverage source,
                                      OperationJAI.Parameters parameters)

Returns a name for the target grid coverage based on the given source. The default implementation returns the operation name followed by the source name between parenthesis.

Parameters:

source - The source grid coverage.

parameters - Parameters, rendering hints and coordinate system to use.

Returns:

A name for the target grid coverage.

createRenderedImage

protected java.awt.image.RenderedImage createRenderedImage(javax.media.jai.ParameterBlockJAI parameters,
                                                           java.awt.RenderingHints hints)

Apply the JAI operation. The operation name can be fetch from descriptor. The JAI instance to use can be fetch from getJAI(java.awt.RenderingHints). The default implementation invokes JAI.createNS. Subclasses may overrides this method in order to invokes a different JAI operation according the parameters.

Parameters:

parameters - The parameters to be given to JAI.

hints - The rendering hints to be given to JAI.

getJAI

protected static javax.media.jai.JAI getJAI(java.awt.RenderingHints hints)

Returns the JAI instance to use for operations on RenderedImage. If no JAI instance is defined for the Hints.JAI_INSTANCE key, then the default instance is returned.

Parameters:

hints - The rendering hints, or null if none.

Returns:

The JAI instance to use (never null).

equals

public boolean equals(java.lang.Object object)

Compares the specified object with this operation for equality.

Overrides:

equals in class Operation