org.geotools.coverage.processing
Class OperationJAI

java.lang.Object
  extended byorg.geotools.coverage.processing.AbstractOperation
      extended byorg.geotools.coverage.processing.Operation2D
          extended byorg.geotools.coverage.processing.OperationJAI
All Implemented Interfaces:
org.opengis.coverage.processing.Operation, java.io.Serializable
Direct Known Subclasses:
Absolute, AddConst, BilevelOperation, DivideByConst, Exp, FilterOperation, GradientMagnitude, Invert, Log, MultiplyConst, Rescale, SubtractConst, SubtractFromConst

public class OperationJAI
extends Operation2D

Wraps a JAI's OperationDescriptor for interoperability with Java Advanced Imaging. This class help to leverage the rich set of JAI operators in an GeoAPI framework. inherits operation name and argument types from OperationDescriptor, except the source argument type (usually RenderedImage.class) which is set to GridCoverage2D.class. If there is only one source argument, it will be renamed for better compliance with OpenGIS usage.

The entry point for applying an 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:

doOperation the entry point.
resampleToCommonGeometry reprojects all sources to the same coordinate reference system.
deriveGridCoverage gets the destination properties.
deriveSampleDimension gets the destination sample dimensions.
deriveCategory gets the destination categories.
deriveRange gets the expected range of values.
deriveUnit gets the destination units.
createRenderedImage the actual call to JAI.createNS.

Since:
2.2
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 GridCoverage2D processed by a OperationJAI.
 
Field Summary
protected  javax.media.jai.OperationDescriptor operation
          The JAI's operation descriptor.
 
Fields inherited from class org.geotools.coverage.processing.Operation2D
SOURCE_0
 
Fields inherited from class org.geotools.coverage.processing.AbstractOperation
descriptor
 
Constructor Summary
  OperationJAI(javax.media.jai.OperationDescriptor operation)
          Constructs a grid coverage operation backed by a JAI operation.
protected OperationJAI(javax.media.jai.OperationDescriptor operation, org.opengis.parameter.ParameterDescriptorGroup descriptor)
          Constructs a grid coverage operation backed by a JAI operation.
  OperationJAI(java.lang.String operation)
          Constructs a grid coverage operation from a JAI operation name.
 
Method Summary
protected  boolean computeOnGeophysicsValues(org.opengis.parameter.ParameterValueGroup parameters)
          Returns if grid coverage content should be converted from sample values to geophysics value before to apply an operation.
protected  java.awt.image.RenderedImage createRenderedImage(javax.media.jai.ParameterBlockJAI parameters, java.awt.RenderingHints hints)
          Applies the JAI operation.
protected  Category deriveCategory(Category[] categories, OperationJAI.Parameters parameters)
          Returns the quantitative category for a single sample dimension in the target grid coverage.
protected  GridCoverage2D deriveGridCoverage(GridCoverage2D[] sources, OperationJAI.Parameters parameters)
          Applies a JAI operation to a grid coverage.
protected  org.opengis.util.InternationalString deriveName(GridCoverage2D[] sources, int primarySourceIndex, OperationJAI.Parameters parameters)
          Returns a name for the target grid coverage based on the given sources.
protected  NumberRange deriveRange(NumberRange[] ranges, OperationJAI.Parameters parameters)
          Returns the range of value for a single sample dimension in the target grid coverage.
protected  GridSampleDimension[] deriveSampleDimension(GridSampleDimension[][] bandLists, OperationJAI.Parameters parameters)
          Returns the sample dimensions for the target grid coverage.
protected  javax.units.Unit deriveUnit(javax.units.Unit[] units, OperationJAI.Parameters parameters)
          Returns the unit of data for a single sample dimension in the target grid coverage.
protected  org.opengis.coverage.Coverage doOperation(org.opengis.parameter.ParameterValueGroup parameters, Hints hints)
          Applies a process operation to a grid coverage.
 boolean equals(java.lang.Object object)
          Compares the specified object with this operation for equality.
static javax.media.jai.JAI getJAI(java.awt.RenderingHints hints)
          Returns the JAI instance to use for operations on RenderedImage.
protected  void resampleToCommonGeometry(GridCoverage2D[] sources, org.opengis.referencing.crs.CoordinateReferenceSystem crs2D, org.opengis.referencing.operation.MathTransform2D gridToCrs2D, Hints hints)
          Resamples all sources grid coverages to the same two-dimensional geometry before to apply the operation.
 
Methods inherited from class org.geotools.coverage.processing.Operation2D
getFactory, getGridCoverageProcessor
 
Methods inherited from class org.geotools.coverage.processing.AbstractOperation
ensureNonNull, getDescription, getDocURL, getName, getNumSources, getParameters, getProcessor, getVendor, getVersion, hashCode, toString
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

operation

protected final javax.media.jai.OperationDescriptor operation
The JAI's operation descriptor.

Constructor Detail

OperationJAI

public OperationJAI(java.lang.String operation)
             throws org.opengis.coverage.processing.OperationNotFoundException
Constructs a grid coverage operation from a JAI operation name. This convenience constructor fetch the OperationDescriptor from the specified operation name using the default JAI instance.

Parameters:
operation - JAI operation name (e.g. ).
Throws:
org.opengis.coverage.processing.OperationNotFoundException - if no JAI descriptor was found for the given name.

OperationJAI

public OperationJAI(javax.media.jai.OperationDescriptor operation)
Constructs a grid coverage operation backed by a JAI operation. The operation descriptor must supports the mode (which is the case for most JAI operations).

Parameters:
operation - The JAI operation descriptor.

OperationJAI

protected OperationJAI(javax.media.jai.OperationDescriptor operation,
                       org.opengis.parameter.ParameterDescriptorGroup descriptor)
Constructs a grid coverage operation backed by a JAI operation. The operation descriptor must supports the mode (which is the case for most JAI operations).

Parameters:
operation - The JAI operation descriptor.
descriptor - The OGC parameters descriptor.
Method Detail

computeOnGeophysicsValues

protected boolean computeOnGeophysicsValues(org.opengis.parameter.ParameterValueGroup parameters)
Returns if grid coverage content should be converted from sample values to geophysics value before to apply an operation. This method is invoked automatically by doOperation. If this method returns , then the computation will be performed on the geophysics view as returned by GridCoverage2D.geophysics(true). If this method returns , then the view will not be changed before the operation is applied (i.e. the method is not invoked at all). The default implementation always returns .

Parameters:
parameters - The parameters supplied by the user to the method.
Returns:
if this operation should be applied on geophysics values.
See Also:
GridCoverage2D.geophysics(boolean)

doOperation

protected org.opengis.coverage.Coverage doOperation(org.opengis.parameter.ParameterValueGroup parameters,
                                                    Hints hints)
Applies a process operation to a grid coverage. The default implementation performs the following steps:
  1. Converts source grid coverages to their geophysics view using GridCoverage2D.geophysics(true). This allow to performs all computation on geophysics values instead of encoded samples. Note: this step is disabled if computeOnGeophysicsValues returns .
  2. Ensures that every sources s use the same coordinate reference system (at least for the two-dimensional part) with the same gridToCRS relationship.
  3. Invokes deriveGridCoverage(org.geotools.coverage.grid.GridCoverage2D[], org.geotools.coverage.processing.OperationJAI.Parameters). The sources in the are RenderedImage objects obtained from GridCoverage2D.getRenderedImage().
  4. If a changes from non-geophysics to geophysics view were performed at step 1, converts the result back to the original view using GridCoverage2D.geophysics(false).

Specified by:
doOperation in class AbstractOperation
Parameters:
parameters - List of name value pairs for the parameters required for the operation.
hints - A set of rendering hints, or if none.
Returns:
The result as a grid coverage.
See Also:
deriveGridCoverage(org.geotools.coverage.grid.GridCoverage2D[], org.geotools.coverage.processing.OperationJAI.Parameters)

resampleToCommonGeometry

protected void resampleToCommonGeometry(GridCoverage2D[] sources,
                                        org.opengis.referencing.crs.CoordinateReferenceSystem crs2D,
                                        org.opengis.referencing.operation.MathTransform2D gridToCrs2D,
                                        Hints hints)
                                 throws InvalidGridGeometryException,
                                        CannotReprojectException
Resamples all sources grid coverages to the same two-dimensional geometry before to apply the operation. This method is invoked automatically by the doOperation method. Only the two-dimensional part is reprojected (usually the spatial component of a CRS). Extra dimension (if any) are left unchanged. Extra dimensions are typically time axis or depth. Note that extra dimensions are not forced to a common geometry; only the two dimensions that apply to a PlanarImage are. This is because the extra dimensions don't need to be compatible for all operations. For example if a source image is a slice in a time series, a second source image could be a slice in the frequency representation of this time series.

Subclasses should override this method if they want to specify target grid geometry and coordinate reference system different than the default ones. For example if a subclass wants to force all images to be referenced in a WGS 84 CRS, then it may overrides this method as below:

 protected void resampleToCommonGeometry(...) {
    crs2D = DefaultGeographicCRS.WGS84;
    super.resampleToCommonGeometry(sources, crs2D, gridToCrs2D, hints);
 }

Parameters:
sources - The source grid coverages to resample. This array is updated in-place as needed (for example if a grid coverage is replaced by a projected one).
crs2D - The target coordinate reference system to use, or for a default one.
gridToCrs2D - The target "grid to coordinate reference system" transform, or for a default one.
hints - The rendering hints, or 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 GridCoverage2D deriveGridCoverage(GridCoverage2D[] sources,
                                            OperationJAI.Parameters parameters)
Applies a JAI operation to a grid coverage. This method is invoked automatically by doOperation(org.opengis.parameter.ParameterValueGroup, org.geotools.factory.Hints). The default implementation performs the following steps:

Parameters:
sources - The source coverages.
parameters - Parameters, rendering hints and coordinate reference system to use.
Returns:
The result as a grid coverage.
See Also:
doOperation(org.opengis.parameter.ParameterValueGroup, org.geotools.factory.Hints), deriveSampleDimension(org.geotools.coverage.GridSampleDimension[][], org.geotools.coverage.processing.OperationJAI.Parameters), JAI.createNS(java.lang.String, java.awt.image.renderable.ParameterBlock, java.awt.RenderingHints)

deriveSampleDimension

protected GridSampleDimension[] deriveSampleDimension(GridSampleDimension[][] bandLists,
                                                      OperationJAI.Parameters parameters)
Returns the sample dimensions for the target grid coverage. This method is invoked automatically by deriveGridCoverage with a argument initialized as below:

This method shall returns an array with a length equals to the number of bands in the target image. If the sample dimensions can't be determined, then this method is allowed to returns .

The default implementation iterates among all bands and invokes the deriveCategory and deriveUnit methods for each of them. Subclasses should override this method if they know a more accurate algorithm for determining sample dimensions.

Parameters:
bandLists - The set of sample dimensions for each source GridCoverage2Ds.
parameters - Parameters, rendering hints and coordinate reference system to use.
Returns:
The sample dimensions for each band in the destination image, or if unknow.
See Also:
deriveCategory(org.geotools.coverage.Category[], org.geotools.coverage.processing.OperationJAI.Parameters), deriveUnit(javax.units.Unit[], org.geotools.coverage.processing.OperationJAI.Parameters)

deriveCategory

protected Category deriveCategory(Category[] categories,
                                  OperationJAI.Parameters parameters)
Returns the quantitative category for a single sample dimension in the target grid coverage. This method is invoked automatically by the deriveSampleDimension method for each band in the target image. The default implementation creates a default category from the target range of values returned by deriveRange.

Parameters:
categories - The quantitative categories from every sources. For unary operations like , this array has a length of 1. For binary operations like and , this array has a length of 2.
parameters - Parameters, rendering hints and coordinate reference system to use.
Returns:
The quantative category to use in the destination image, or if unknow.

deriveRange

protected NumberRange deriveRange(NumberRange[] ranges,
                                  OperationJAI.Parameters parameters)
Returns the range of value for a single sample dimension in the target grid coverage. This method is invoked automatically by the deriveCategory method for each band in the target image. Subclasses should override this method in order to compute the target range of values. For example, the operation may implements this method as below:
 double min = ranges[0].getMinimum() + ranges[1].getMinimum();
 double max = ranges[0}.getMaximum() + ranges[1}.getMaximum();
 return new NumberRange(min, max);
 

Parameters:
ranges - The range of values from every sources. For unary operations like , this array has a length of 1. For binary operations like and , this array has a length of 2.
parameters - Parameters, rendering hints and coordinate reference system to use.
Returns:
The range of values to use in the destination image, or if unknow.

deriveUnit

protected javax.units.Unit deriveUnit(javax.units.Unit[] units,
                                      OperationJAI.Parameters parameters)
Returns the unit of data for a single sample dimension in the target grid coverage. This method is invoked automatically by the deriveSampleDimension method for each band in the target image. Subclasses should override this method in order to compute the target units from the source units. For example a 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 , this array has a length of 1. For binary operations like and , this array has a length of 2.
parameters - Parameters, rendering hints and coordinate reference system to use.
Returns:
The unit of data in the destination image, or if unknow.

deriveName

protected org.opengis.util.InternationalString deriveName(GridCoverage2D[] sources,
                                                          int primarySourceIndex,
                                                          OperationJAI.Parameters parameters)
Returns a name for the target grid coverage based on the given sources. This method is invoked once by the deriveGridCoverage method. The default implementation returns the operation name followed by the source name between parenthesis, for example "GradientMagnitude(Sea Surface Temperature)".

Parameters:
sources - The sources grid coverage.
primarySourceIndex - The index of what seems to be the primary source, or if none of unknow.
parameters - Parameters, rendering hints and coordinate reference 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)
Applies the JAI operation. The operation name can be fetch from operation. The JAI instance to use can be fetch from getJAI(java.awt.RenderingHints). The default implementation returns the following:
 getJAI(hints).createNS(operation.getName(), parameters, hints)
 
Subclasses may override 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

public 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 if none.
Returns:
The JAI instance to use (never ).

equals

public boolean equals(java.lang.Object object)
Compares the specified object with this operation for equality.

Overrides:
equals in class AbstractOperation


Copyright © GeoTools. All Rights Reserved.