Class Operator
- java.lang.Object
-
- org.esa.snap.core.gpf.Operator
-
- Direct Known Subclasses:
BandMathsOp
,GraphOp
,ImportVectorOp
,JaiOp
,MergeOp
,MosaicOp
,PassThroughOp
,PointOperator
,ProductSetReaderOp
,ReadOp
,ReprojectionOp
,ResamplingOp
,SubsetOp
,ToolAdapterOp
,WriteOp
,WriteRGBOp
public abstract class Operator extends Object
The abstract base class for all operators intended to be extended by clients.The following methods are intended to be implemented or overridden:
initialize()
: must be implemented in order to initialise the operator and create the target product.computeTile()
: implemented to compute the tile for a single band.computeTileStack(Map, Rectangle, ProgressMonitor)
: implemented to compute the tiles for multiple bands.dispose()
: can be overridden in order to free all resources previously allocated by the operator.
Generally, only one
computeTile
method needs to be implemented. It depends on the type of algorithm which of both operations is most advantageous to implement:- If bands can be computed independently of each other, then it is
beneficial to implement the
computeTile()
method. This is the case for sub-sampling, map-projections, band arithmetic, band filtering and statistic analyses. computeTileStack()
should be overridden in cases where the bands of a product cannot be computed independently, e.g. because they are a simultaneous output. This is often the case for algorithms based on neural network, cluster analyses, model inversion methods or spectral unmixing.
For information on how to best implement the
computeTile()
orcomputeTileStack()
method please read also theTile
documentation.The framework execute either the
computeTile()
or thecomputeTileStack()
method based on the current use case or request. If tiles for single bands are requested, e.g. for image display, it will always prefer an implementation of thecomputeTile()
method and call it. If all tiles are requested at once, e.g. writing a product to disk, it will attempt to use thecomputeTileStack()
method. If the framework cannot use its preferred operation, it will use the one implemented by the operator.- Since:
- 4.1
- See Also:
OperatorSpi
,OperatorMetadata
,Parameter
,TargetProduct
,TargetProperty
,SourceProduct
,SourceProducts
,Tile
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
Operator()
Constructs a new operator.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description boolean
canComputeTile()
Determines whether this operator'scomputeTileStack
method can be used.boolean
canComputeTileStack()
Determines whether this operator'scomputeTileStack
method can be used.protected void
checkForCancellation()
Checks for cancellation of the current processing request.void
computeTile(Band targetBand, Tile targetTile, ProgressMonitor pm)
Called by the framework in order to compute a tile for the given target band.void
computeTileStack(Map<Band,Tile> targetTiles, Rectangle targetRectangle, ProgressMonitor pm)
Called by the framework in order to compute the stack of tiles for the given target bands.void
dispose()
Releases the resources the operator has acquired during its lifetime.void
doExecute(ProgressMonitor pm)
Executes the operator.protected void
ensureSceneGeoCoding(Product... products)
Ensures that the given source products all have a scene geo-coding.protected Dimension
ensureSingleRasterSize(Product... products)
Ensures that the given source products only contain raster data nodes having the same size in pixels and that all products have the same scene raster size.protected Dimension
ensureSingleRasterSize(RasterDataNode... rasterDataNodes)
Ensures that the given raster data nodes only contain raster data nodes having the same size in pixels.void
execute(ProgressMonitor pm)
Executes the operator.protected void
finalize()
Overridden in order to force a call todispose()
, if not already done.String
getId()
Logger
getLogger()
Gets the logger whuich can be used to log information during initialisation and tile computation.Object
getParameter(String name)
Gets the value for the parameter with the given name.Object
getParameter(String name, Object defaultValue)
Gets the value for the parameter with the given name.ProductManager
getProductManager()
Provides the context product manager which can be used to exchange product instances across operators or allow (reading) operators to check if a given product is already opened.Product
getSourceProduct()
Gets a single source product.Product
getSourceProduct(String id)
Gets the source product using the specified name.String
getSourceProductId(Product product)
Gets the identifier for the given source product.Product[]
getSourceProducts()
Gets the source products in the order they have been declared.Tile
getSourceTile(RasterDataNode rasterDataNode, Rectangle region)
Gets aTile
for a given band and image region.Tile
getSourceTile(RasterDataNode rasterDataNode, Rectangle region, javax.media.jai.BorderExtender borderExtender)
Gets aTile
for a given band and image region.OperatorSpi
getSpi()
Gets the SPI which was used to create this operator.Product
getTargetProduct()
Gets the target product for the operator.Object
getTargetProperty(String name)
Gets a target property of the operator.abstract void
initialize()
Initializes this operator and sets the one and only target product.void
setLogger(Logger logger)
Sets the logger which can be used to log information during initialisation and tile computation.void
setParameter(String name, Object value)
Sets the value for the parameter with the given name.void
setParameterDefaultValues()
Sets the operator parameters to their default values, if any.protected void
setRequiresAllBands(boolean requiresAllBands)
void
setSourceProduct(String id, Product product)
Sets a source product.void
setSourceProduct(Product sourceProduct)
Sets a single source product.void
setSourceProducts(Product... products)
Sets the source products.void
setSpi(OperatorSpi operatorSpi)
Sets the SPI which was used to create this operator.void
setTargetProduct(Product targetProduct)
Sets the target product for the operator.void
stopTileComputationObservation()
Non-API.void
update()
Updates this operator forcing it to recreate the target product.
-
-
-
Method Detail
-
setParameterDefaultValues
public void setParameterDefaultValues()
Sets the operator parameters to their default values, if any.
-
finalize
protected final void finalize() throws Throwable
Overridden in order to force a call todispose()
, if not already done.
-
initialize
public abstract void initialize() throws OperatorException
Initializes this operator and sets the one and only target product.The target product can be either defined by a field of type
Product
annotated with theTargetProduct
annotation or by callingsetTargetProduct(org.esa.snap.core.datamodel.Product)
method.This method shall never be called directly. The framework calls this method after it has created an instance of this
Operator
. This will occur only once durting the lifetime of anOperator
instance. If not already done, calling thegetTargetProduct()
will always trigger a call to theinitialize()
method.Any client code that must be performed before computation of tile data should be placed here.
- Throws:
OperatorException
- If an error occurs during operator initialisation.- See Also:
getTargetProduct()
-
update
public final void update()
Updates this operator forcing it to recreate the target product.
-
execute
public final void execute(ProgressMonitor pm)
Executes the operator. Call this method to execute an operator that doesn't compute raster data tiles on its own.- Parameters:
pm
- A progress monitor to be notified for long-running tasks.
-
doExecute
public void doExecute(ProgressMonitor pm) throws OperatorException
Executes the operator.For operators that compute raster data tiles, the method is usually a no-op. Other operators might perform their main work in this method, e.g. perform some image analysis such as extracting statistics and other features from data products.
Don't call this method directly. The framework may call this method
- once before the very first tile is computed, or
- as a result of a call to
execute(ProgressMonitor)
.
The default implementation only progresses the progress monitor.
- Parameters:
pm
- A progress monitor to be notified for long-running tasks.- Throws:
OperatorException
- If an error occurs during computation of the target raster.
-
computeTile
public void computeTile(Band targetBand, Tile targetTile, ProgressMonitor pm) throws OperatorException
Called by the framework in order to compute a tile for the given target band.The default implementation throws a runtime exception with the message "not implemented".
This method shall never be called directly.
- Parameters:
targetBand
- The target band.targetTile
- The current tile associated with the target band to be computed.pm
- A progress monitor which should be used to determine computation cancellation requests.- Throws:
OperatorException
- If an error occurs during computation of the target raster.
-
computeTileStack
public void computeTileStack(Map<Band,Tile> targetTiles, Rectangle targetRectangle, ProgressMonitor pm) throws OperatorException
Called by the framework in order to compute the stack of tiles for the given target bands.The default implementation throws a runtime exception with the message "not implemented".
This method shall never be called directly.
- Parameters:
targetTiles
- The current tiles to be computed for each target band.targetRectangle
- The area in pixel coordinates to be computed (same for all rasters intargetRasters
).pm
- A progress monitor which should be used to determine computation cancellation requests.- Throws:
OperatorException
- If an error occurs during computation of the target rasters.
-
dispose
public void dispose()
Releases the resources the operator has acquired during its lifetime. The default implementation does nothing.Overrides should make sure to call
super.dispose()
as well.
-
canComputeTile
public boolean canComputeTile()
Determines whether this operator'scomputeTileStack
method can be used.The default implementation of this method checks if the this operator's class overrides the
Operator.computeTileStack
method.- Returns:
true
if so.- Since:
- SNAP 3.0
-
canComputeTileStack
public boolean canComputeTileStack()
Determines whether this operator'scomputeTileStack
method can be used.The default implementation of this method checks if the this operator's class overrides the
Operator.computeTileStack
method.- Returns:
true
if so.- Since:
- SNAP 3.0
-
getProductManager
public ProductManager getProductManager()
Provides the context product manager which can be used to exchange product instances across operators or allow (reading) operators to check if a given product is already opened.- Returns:
- A context product manager.
- Since:
- SNAP 3.0
-
setRequiresAllBands
protected final void setRequiresAllBands(boolean requiresAllBands)
-
getId
public final String getId()
- Returns:
- The operator's runtime identifier assigned by the framework.
-
getSourceProducts
public final Product[] getSourceProducts()
Gets the source products in the order they have been declared.- Returns:
- The array source products.
-
setSourceProducts
public final void setSourceProducts(Product... products)
Sets the source products.- Parameters:
products
- The source products.- Since:
- BEAM 4.2
-
getSourceProduct
public Product getSourceProduct()
Gets a single source product. This method is a shortcut forgetSourceProduct("sourceProduct")
.- Returns:
- The source product, or
null
if not set. - Since:
- BEAM 4.2
-
setSourceProduct
public void setSourceProduct(Product sourceProduct)
Sets a single source product. This method is a shortcut forsetSourceProduct("sourceProduct", sourceProduct)
.- Parameters:
sourceProduct
- the source product to be set- Since:
- BEAM 4.2
-
getSourceProduct
public final Product getSourceProduct(String id)
Gets the source product using the specified name.- Parameters:
id
- the identifier- Returns:
- the source product, or
null
if not found - See Also:
getSourceProductId(Product)
-
setSourceProduct
public final void setSourceProduct(String id, Product product)
Sets a source product. One product instance can be registered with different identifiers, e.g. "source", "source1" and "input" in consecutive calls.- Parameters:
id
- a source product identifierproduct
- the source product to be set- Since:
- BEAM 4.2
-
getSourceProductId
public final String getSourceProductId(Product product)
Gets the identifier for the given source product.- Parameters:
product
- The source product.- Returns:
- The identifier, or
null
if no such exists. - See Also:
getSourceProduct(String)
-
getTargetProduct
public final Product getTargetProduct() throws OperatorException
Gets the target product for the operator.If the target product is not set, calling this method results in a call to
initialize()
.- Returns:
- The target product.
- Throws:
OperatorException
- May be caused byinitialize()
, if the operator is not initialised, or if the target product is not set.
-
setTargetProduct
public final void setTargetProduct(Product targetProduct)
Sets the target product for the operator.Must be called from within the
initialize()
method.- Parameters:
targetProduct
- The target product.
-
getTargetProperty
public final Object getTargetProperty(String name) throws OperatorException
Gets a target property of the operator.If the requested target property is not set, calling this method results in a call to
initialize()
.- Parameters:
name
- the name of the property requested.- Returns:
- the target property requested.
- Throws:
OperatorException
- May be caused byinitialize()
, if the operator is not initialised, or if the target product is not been set.
-
getParameter
public Object getParameter(String name)
Gets the value for the parameter with the given name.- Parameters:
name
- The parameter name.- Returns:
- The parameter value, which may be
null
. - Since:
- BEAM 4.7
-
getParameter
public Object getParameter(String name, Object defaultValue)
Gets the value for the parameter with the given name.- Parameters:
name
- The parameter name.defaultValue
- The default value which is used in casegetParameter(String)
returnsnull
. May benull
.- Returns:
- The parameter value, or the given
defaultValue
. - Since:
- BEAM 5.0
-
setParameter
public void setParameter(String name, Object value)
Sets the value for the parameter with the given name.- Parameters:
name
- The parameter name.value
- The parameter value, which may benull
.- Since:
- BEAM 4.7
-
getSourceTile
public final Tile getSourceTile(RasterDataNode rasterDataNode, Rectangle region) throws OperatorException
Gets aTile
for a given band and image region.- Parameters:
rasterDataNode
- the raster data node of a data product, e.g. aBand
orTiePointGrid
.region
- the image region in pixel coordinates- Returns:
- a tile.
- Throws:
OperatorException
- if the tile request cannot be processed
-
getSourceTile
public final Tile getSourceTile(RasterDataNode rasterDataNode, Rectangle region, javax.media.jai.BorderExtender borderExtender) throws OperatorException
Gets aTile
for a given band and image region. The region can overlap the bounds of source image. This method is particularly useful if you need to compute target pixels from an n x m region around a corresponding source pixel. In this case an extended tile will need to be read from the source.- Parameters:
rasterDataNode
- the raster data node of a data product, e.g. aBand
orTiePointGrid
.region
- The image region in pixel coordinatesborderExtender
- A strategy used to fill the raster regions that lie outside the bounds of the source image.- Returns:
- A tile whose region can overlap the bounds of source image.
- Throws:
OperatorException
- if the tile request cannot be processed- Since:
- BEAM 4.7.1
-
checkForCancellation
protected final void checkForCancellation() throws OperatorException
Checks for cancellation of the current processing request. Throws an exception, if the request has been canceled (e.g. by the user).- Throws:
OperatorException
- if the current processing request has been canceled (e.g. by the user).
-
ensureSceneGeoCoding
protected void ensureSceneGeoCoding(Product... products) throws OperatorException
Ensures that the given source products all have a scene geo-coding. Operator implementations may use this method in theirinitialize()
method to ensure that their sources are geo-coded.- Parameters:
products
- The products to test.- Throws:
OperatorException
- if any product has no geo-coding.- Since:
- SNAP 3
-
ensureSingleRasterSize
protected Dimension ensureSingleRasterSize(Product... products) throws OperatorException
Ensures that the given source products only contain raster data nodes having the same size in pixels and that all products have the same scene raster size. Operator implementations may use this method in theirinitialize()
method if they can only deal with single-size sources.- Parameters:
products
- Source products products to test.- Returns:
- the unique raster size,
null
ifproducts
is an empty array - Throws:
OperatorException
- if the product contains multi-size rasters.- Since:
- SNAP 3
-
ensureSingleRasterSize
protected Dimension ensureSingleRasterSize(RasterDataNode... rasterDataNodes) throws OperatorException
Ensures that the given raster data nodes only contain raster data nodes having the same size in pixels.- Parameters:
rasterDataNodes
- Other optional products to test.- Returns:
- the unique raster size,
null
ifrasterDataNodes
is an empty array - Throws:
OperatorException
- if the product contains multi-size rasters.- Since:
- SNAP 3
-
getLogger
public final Logger getLogger()
Gets the logger whuich can be used to log information during initialisation and tile computation.- Returns:
- The logger.
-
setLogger
public final void setLogger(Logger logger)
Sets the logger which can be used to log information during initialisation and tile computation.- Parameters:
logger
- The logger.
-
stopTileComputationObservation
public void stopTileComputationObservation()
Non-API.
-
getSpi
public final OperatorSpi getSpi()
Gets the SPI which was used to create this operator. If no operator has been explicitly set, the method will return an anonymous SPI.- Returns:
- The operator SPI.
-
setSpi
public final void setSpi(OperatorSpi operatorSpi)
Sets the SPI which was used to create this operator.- Parameters:
operatorSpi
- The operator SPI.
-
-