Class OperationJAI
- Object
-
- AbstractOperation
-
- Operation2D
-
- OperationJAI
-
- All Implemented Interfaces:
Serializable
,Operation
- Direct Known Subclasses:
AddConst
,BandMerge
,BaseMathOperationJAI
,BaseScaleOperationJAI
,BaseStatisticsOperationJAI
,BilevelOperation
,Convolve
,DivideByConst
,FilterOperation
,MaxFilter
,MedianFilter
,MinFilter
,Mosaic
,MultiplyConst
,Rescale
,ShadedRelief
,SubtractConst
,SubtractFromConst
,TransparencyFill
public class OperationJAI extends Operation2D
Wraps a JAI'sOperationDescriptor
for interoperability with Java Advanced Imaging. This class help to leverage the rich set of JAI operators in an GeoAPI framework.OperationJAI
inherits operation name and argument types fromOperationDescriptor
, except the source argument type (usuallyRenderedImage.class
) which is set toGridCoverage2D.class
. If there is only one source argument, it will be renamed"source"
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
- Author:
- Martin Desruisseaux (IRD), Simone Giannecchini
- See Also:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description protected static class
OperationJAI.Parameters
A block of parameters for aGridCoverage2D
processed by aOperationJAI
.
-
Field Summary
Fields Modifier and Type Field Description protected OperationDescriptor
operation
The JAI's operation descriptor.protected static String
RENDERED_MODE
The rendered mode for JAI operation.-
Fields inherited from class Operation2D
PRIMARY_SOURCE_INDEX, SOURCE_0
-
Fields inherited from class AbstractOperation
descriptor
-
-
Constructor Summary
Constructors Modifier Constructor Description OperationJAI(String operation)
Constructs a grid coverage operation from a JAI operation name.OperationJAI(String operationName, OperationDescriptor operation)
Constructs a grid coverage operation backed by a JAI operation.OperationJAI(OperationDescriptor operation)
Constructs a grid coverage operation backed by a JAI operation.protected
OperationJAI(OperationDescriptor operation, ParameterDescriptorGroup descriptor)
Constructs a grid coverage operation backed by a JAI operation.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description protected RenderedImage
createRenderedImage(ParameterBlockJAI parameters, 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 InternationalString
deriveName(GridCoverage2D[] sources, int primarySourceIndex, OperationJAI.Parameters parameters)
Returns a name for the target grid coverage based on the given sources.protected NumberRange<? extends Number>
deriveRange(NumberRange<? extends Number>[] 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 Unit<?>
deriveUnit(Unit<?>[] units, OperationJAI.Parameters parameters)
Returns the unit of data for a single sample dimension in the target grid coverage.Coverage
doOperation(ParameterValueGroup parameters, Hints hints)
Applies a process operation to a grid coverage.boolean
equals(Object object)
Compares the specified object with this operation for equality.protected void
extractSources(ParameterValueGroup parameters, Collection<GridCoverage2D> sources, String[] sourceNames)
Extraction of the sources from the parameter called SOURCES.static JAI
getJAI(RenderingHints hints)
Returns theJAI
instance to use for operations onRenderedImage
.protected static OperationDescriptor
getOperationDescriptor(String name)
Returns the operation descriptor for the specified JAI operation name.protected Map<String,?>
getProperties(RenderedImage data, CoordinateReferenceSystem crs, InternationalString name, MathTransform gridToCRS, GridCoverage2D[] sources, OperationJAI.Parameters parameters)
Prepares the properties to be given to the coverage created by thederiveGridCoverage
method.protected static int
getQuantitative(Category[] categories)
Returns the index of the quantitative category, providing that there is one and only one quantitative category.protected void
handleJAIEXTParams(ParameterBlockJAI parameters, ParameterValueGroup parameters2)
Extension point for adding to the JAIParameterBlockJAI
object the parameters defined in theParameterValueGroup
, which can be read by the JAI-EXT operations.protected static void
handleROINoDataInternal(ParameterBlockJAI parameters, GridCoverage2D sourceCoverage, String operationName, int roiIndex, int noDataIndex)
This method can be used for merging input coverage properties (ROI and NoData) with the ones provided as input in the ParameterBlock instance.protected static Map<String,Object>
handleROINoDataProperties(Map<String,Object> properties, ParameterBlockJAI parameters, GridCoverage2D sourceCoverage, String operationName, int roiIndex, int noDataIndex, int backgroundIndex)
This method can be used for creating a property Map to set to the new coverage generated by the current operation.int
hashCode()
Returns a hash value for this operation.protected ParameterBlockJAI
prepareParameters(ParameterValueGroup parameters)
Copies parameter values from the specifiedParameterValueGroup
to theParameterBlockJAI
, except the sources.protected void
resampleToCommonGeometry(GridCoverage2D[] sources, CoordinateReferenceSystem crs2D, MathTransform2D gridToCrs2D, Hints hints)
Resamples all sources grid coverages to the same two-dimensional geometry before to apply the operation.-
Methods inherited from class Operation2D
extractSources, getFactory
-
Methods inherited from class AbstractOperation
getDescription, getDocURL, getName, getNumSources, getParameters, getVendor, getVersion, toString
-
-
-
-
Field Detail
-
RENDERED_MODE
protected static final String RENDERED_MODE
The rendered mode for JAI operation.- See Also:
- Constant Field Values
-
operation
protected final OperationDescriptor operation
The JAI's operation descriptor.
-
-
Constructor Detail
-
OperationJAI
public OperationJAI(String operation) throws OperationNotFoundException
Constructs a grid coverage operation from a JAI operation name. This convenience constructor fetch theOperationDescriptor
from the specified operation name using the defaultJAI
instance.- Parameters:
operation
- JAI operation name- Throws:
OperationNotFoundException
- if no JAI descriptor was found for the given name.
-
OperationJAI
public OperationJAI(OperationDescriptor operation)
Constructs a grid coverage operation backed by a JAI operation. The operation descriptor must supports the"rendered"
mode (which is the case for most JAI operations).- Parameters:
operation
- The JAI operation descriptor.
-
OperationJAI
public OperationJAI(String operationName, OperationDescriptor operation)
Constructs a grid coverage operation backed by a JAI operation. The operation descriptor must supports the"rendered"
mode (which is the case for most JAI operations).- Parameters:
operationName
- JAI operation nameoperation
- The JAI operation descriptor.
-
OperationJAI
protected OperationJAI(OperationDescriptor operation, ParameterDescriptorGroup descriptor)
Constructs a grid coverage operation backed by a JAI operation. The operation descriptor must supports the"rendered"
mode (which is the case for most JAI operations).- Parameters:
operation
- The JAI operation descriptor.descriptor
- The OGC parameters descriptor.
-
-
Method Detail
-
getOperationDescriptor
protected static OperationDescriptor getOperationDescriptor(String name) throws OperationNotFoundException
Returns the operation descriptor for the specified JAI operation name. This method uses the defaultJAI
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.- Since:
- 2.4
-
prepareParameters
protected ParameterBlockJAI prepareParameters(ParameterValueGroup parameters)
Copies parameter values from the specifiedParameterValueGroup
to theParameterBlockJAI
, except the sources.Note: it would be possible to use
ImagingParameters.parameters
directly in some occasions. However, we perform an unconditional copy instead because some operations may change the values.- Parameters:
parameters
- TheParameterValueGroup
to be copied.- Returns:
- A copy of the provided
ParameterValueGroup
as a JAI block. - Since:
- 2.4
-
doOperation
public Coverage doOperation(ParameterValueGroup parameters, Hints hints) throws CoverageProcessingException
Applies a process operation to a grid coverage. The default implementation performs the following steps:- Ensures that every sources
GridCoverage2D
s use the same coordinate reference system (at least for the two-dimensional part) with the samegridToCRS
relationship. - Invokes
deriveGridCoverage(org.geotools.coverage.grid.GridCoverage2D[], org.geotools.coverage.processing.OperationJAI.Parameters)
. The sources in theParameterBlock
areRenderedImage
objects obtained fromGridCoverage2D.getRenderedImage()
. - 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 classAbstractOperation
- Parameters:
parameters
- List of name value pairs for the parameters required for the operation.hints
- A set of rendering hints, ornull
if none.- Returns:
- The result as a grid coverage.
- Throws:
CoverageProcessingException
- if the operation can't be applied.- See Also:
deriveGridCoverage(org.geotools.coverage.grid.GridCoverage2D[], org.geotools.coverage.processing.OperationJAI.Parameters)
- Ensures that every sources
-
resampleToCommonGeometry
protected void resampleToCommonGeometry(GridCoverage2D[] sources, CoordinateReferenceSystem crs2D, 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 thedoOperation
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 aPlanarImage
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, ornull
for a default one.gridToCrs2D
- The target "grid to coordinate reference system" transform, ornull
for a default one.hints
- The rendering hints, ornull
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 bydoOperation(org.geotools.api.parameter.ParameterValueGroup, org.geotools.util.factory.Hints)
. The default implementation performs the following steps:- Gets the sample dimensions for the target images by
invoking the
deriveSampleDimension(...)
method. - Applied the JAI operation using
createRenderedImage(javax.media.jai.ParameterBlockJAI, java.awt.RenderingHints)
. - Wraps the result in a
GridCoverage2D
object.
- 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.geotools.api.parameter.ParameterValueGroup, org.geotools.util.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)
- Gets the sample dimensions for the target images by
invoking the
-
getProperties
protected Map<String,?> getProperties(RenderedImage data, CoordinateReferenceSystem crs, InternationalString name, MathTransform gridToCRS, GridCoverage2D[] sources, OperationJAI.Parameters parameters)
Prepares the properties to be given to the coverage created by thederiveGridCoverage
method. The default implementation returnsnull
.- Parameters:
data
- TheRenderedImage
created by this operation.crs
- The coordinate reference system assigned to the coverage thisOperationJAI
will produce.name
- The name assigned to the coverage thisOperationJAI
will produce.gridToCRS
- The transform from grid tocrs
to be assigned to the coverage thisOperationJAI
will produce.sources
- The sources to be assigned to the coverage thisOperationJAI
will produce.parameters
- The parameters that were used by thisOperationJAI
.- Returns:
- a
Map
with the properties generated by thisOperationJAI
or null if we haven't any. - Since:
- 2.4
-
getQuantitative
protected static int getQuantitative(Category[] categories)
Returns the index of the quantitative category, providing that there is one and only one quantitative category. Ifcategories
contains 0, 2 or more quantitative category, then this method returns-1
.- Parameters:
categories
- The categories to test.- Returns:
- The index of the quantitative category, or
-1
if none can be choosen. - Since:
- 2.4
-
deriveSampleDimension
protected GridSampleDimension[] deriveSampleDimension(GridSampleDimension[][] bandLists, OperationJAI.Parameters parameters)
Returns the sample dimensions for the target grid coverage. This method is invoked automatically byderiveGridCoverage
with abandLists
argument initialized as below:- The
bandLists
array length is equals to the number of source coverages. - The
bandLists[i]
array length is equals to the number of sample dimensions in the source coverage i. - The sample dimension for a band at index band in the source at index
source is
bandLists[source][band]
.
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
null
.The default implementation iterates among all bands and invokes the
deriveCategory
andderiveUnit
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 sourceGridCoverage2D
s.parameters
- Parameters, rendering hints and coordinate reference system to use.- Returns:
- The sample dimensions for each band in the destination image, or
null
if unknown. - See Also:
deriveCategory(org.geotools.coverage.Category[], org.geotools.coverage.processing.OperationJAI.Parameters)
,deriveUnit(javax.measure.Unit<?>[], org.geotools.coverage.processing.OperationJAI.Parameters)
- The
-
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 thederiveSampleDimension
method for each band in the target image. The default implementation creates a default category from the target range of values returned byderiveRange
.- Parameters:
categories
- The quantitative categories from every sources. For unary operations like, 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 reference system to use.- Returns:
- The quantitative category to use in the destination image, or
null
if unknown.
-
deriveRange
protected NumberRange<? extends Number> deriveRange(NumberRange<? extends Number>[] 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 thederiveCategory
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"add"
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 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 reference system to use.- Returns:
- The range of values to use in the destination image, or
null
if unknow.
-
deriveUnit
protected Unit<?> deriveUnit(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 thederiveSampleDimension
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"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 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 reference system to use.- Returns:
- The unit of data in the destination image, or
null
if unknow.
-
deriveName
protected 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 thederiveGridCoverage
method. The default implementation returns the operation name followed by the source name between parenthesis, for example "Add(Sea Surface Temperature)".- Parameters:
sources
- The sources grid coverage.primarySourceIndex
- The index of what seems to be the primary source, or-1
if none of unknown.parameters
- Parameters, rendering hints and coordinate reference system to use.- Returns:
- A name for the target grid coverage.
-
createRenderedImage
protected RenderedImage createRenderedImage(ParameterBlockJAI parameters, RenderingHints hints)
Applies the JAI operation. The operation name can be fetch fromoperation
. The JAI instance to use can be fetch fromgetJAI(java.awt.RenderingHints)
. The default implementation returns the following:getJAI(hints).createNS(operation.getName(), parameters, hints)
- Parameters:
parameters
- The parameters to be given to JAI.hints
- The rendering hints to be given to JAI.- Returns:
- The result of JAI operation using the given parameters and hints.
-
getJAI
public static final JAI getJAI(RenderingHints hints)
Returns theJAI
instance to use for operations onRenderedImage
. If no JAI instance is defined for theHints.JAI_INSTANCE
key, then the default instance is returned.- Parameters:
hints
- The rendering hints, ornull
if none.- Returns:
- The JAI instance to use (never
null
).
-
equals
public boolean equals(Object object)
Compares the specified object with this operation for equality.- Overrides:
equals
in classAbstractOperation
- Parameters:
object
- The object to compare with this operation.- Returns:
true
if the given object is equals to this operation.
-
hashCode
public int hashCode()
Description copied from class:AbstractOperation
Returns a hash value for this operation. This value need not remain consistent between different implementations of the same class.- Overrides:
hashCode
in classAbstractOperation
-
handleJAIEXTParams
protected void handleJAIEXTParams(ParameterBlockJAI parameters, ParameterValueGroup parameters2)
Extension point for adding to the JAIParameterBlockJAI
object the parameters defined in theParameterValueGroup
, which can be read by the JAI-EXT operations.Notice that if you are using JAI, the new parameters will not be accepted by the
ParameterBlockJAI
instance.- Parameters:
parameters
-ParameterBlockJAI
instance used by the current JAI-EXT/JAI operationparameters2
-ParameterValueGroup
instance containing input operation parameters
-
handleROINoDataProperties
protected static Map<String,Object> handleROINoDataProperties(Map<String,Object> properties, ParameterBlockJAI parameters, GridCoverage2D sourceCoverage, String operationName, int roiIndex, int noDataIndex, int backgroundIndex)
This method can be used for creating a property Map to set to the new coverage generated by the current operation. Internally the method will search for ROI and NoData parameters set for the operation and will report them as coverage properties- Returns:
- A
Map
containing all the coverage properties and alsoROI
and NoData if present
-
handleROINoDataInternal
protected static void handleROINoDataInternal(ParameterBlockJAI parameters, GridCoverage2D sourceCoverage, String operationName, int roiIndex, int noDataIndex)
This method can be used for merging input coverage properties (ROI and NoData) with the ones provided as input in the ParameterBlock instance. If a ROI instance is already present as a coverage property, it will be intersected with an eventual ROI object defined as a parameter inside the ParameterBlock. If no NoData Range is defined in the parameters but is defined as coverage property, it will be set in the input ParameterBlock
-
extractSources
protected void extractSources(ParameterValueGroup parameters, Collection<GridCoverage2D> sources, String[] sourceNames) throws ParameterNotFoundException, InvalidParameterValueException
Extraction of the sources from the parameter called SOURCES. The sources are stored inside a List.
-
-