public abstract class Operator extends Object
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:
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()
or computeTileStack()
method please
read also the Tile
documentation.
The framework execute either the computeTile()
or the computeTileStack()
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
the computeTile()
method and call it.
If all tiles are requested at once, e.g. writing a product to disk, it will attempt to use the computeTileStack()
method. If the framework cannot use its preferred operation, it will use the one implemented by the operator.
OperatorSpi
,
OperatorMetadata
,
Parameter
,
TargetProduct
,
TargetProperty
,
SourceProduct
,
SourceProducts
,
Tile
Modifier | Constructor and Description |
---|---|
protected |
Operator()
Constructs a new operator.
|
Modifier and Type | Method and Description |
---|---|
boolean |
canComputeTile()
Determines whether this operator's
computeTileStack method can be used. |
boolean |
canComputeTileStack()
Determines whether this operator's
computeTileStack 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.
|
protected void |
deactivateComputeTileMethod()
Deprecated.
since SNAP 3.0. Override
canComputeTile() instead. |
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 to
dispose() , 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 a
Tile for a given band and image region. |
Tile |
getSourceTile(RasterDataNode rasterDataNode,
Rectangle region,
javax.media.jai.BorderExtender borderExtender)
Gets a
Tile 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(Product sourceProduct)
Sets a single source product.
|
void |
setSourceProduct(String id,
Product product)
Sets a 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.
|
public void setParameterDefaultValues()
protected final void finalize() throws Throwable
dispose()
, if not already done.public abstract void initialize() throws OperatorException
The target product can be either defined by a field of type Product
annotated with the
TargetProduct
annotation or
by calling setTargetProduct(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 an Operator
instance.
If not already done, calling the getTargetProduct()
will always trigger
a call to the initialize()
method.
Any client code that must be performed before computation of tile data
should be placed here.
OperatorException
- If an error occurs during operator initialisation.getTargetProduct()
public final void update()
public final void execute(ProgressMonitor pm)
pm
- A progress monitor to be notified for long-running tasks.public void doExecute(ProgressMonitor pm) throws OperatorException
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
execute(ProgressMonitor)
.The default implementation does nothing.
pm
- A progress monitor to be notified for long-running tasks.OperatorException
- If an error occurs during computation of the target raster.public void computeTile(Band targetBand, Tile targetTile, ProgressMonitor pm) throws OperatorException
The default implementation throws a runtime exception with the message "not implemented".
This method shall never be called directly.
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.OperatorException
- If an error occurs during computation of the target raster.public void computeTileStack(Map<Band,Tile> targetTiles, Rectangle targetRectangle, ProgressMonitor pm) throws OperatorException
The default implementation throws a runtime exception with the message "not implemented".
This method shall never be called directly.
targetTiles
- The current tiles to be computed for each target band.targetRectangle
- The area in pixel coordinates to be computed (same for all rasters in targetRasters
).pm
- A progress monitor which should be used to determine computation cancellation requests.OperatorException
- If an error occurs during computation of the target rasters.public void dispose()
Overrides should make sure to call super.dispose()
as well.
public boolean canComputeTile()
computeTileStack
method can be used.
The default implementation of this method checks if the this operator's class
overrides the Operator.computeTileStack
method.
true
if so.public boolean canComputeTileStack()
computeTileStack
method can be used.
The default implementation of this method checks if the this operator's class
overrides the Operator.computeTileStack
method.
true
if so.@Deprecated protected final void deactivateComputeTileMethod() throws IllegalStateException
canComputeTile()
instead.computeTile
method. This method can be called from within the initialize()
method if the current operator configuration prevents
the computation of tiles of individual, independent target bands.IllegalStateException
- if the computeTileStack
method is not implementedpublic ProductManager getProductManager()
protected final void setRequiresAllBands(boolean requiresAllBands)
public final String getId()
public final Product[] getSourceProducts()
public final void setSourceProducts(Product... products)
products
- The source products.public Product getSourceProduct()
getSourceProduct("sourceProduct")
.null
if not set.public void setSourceProduct(Product sourceProduct)
setSourceProduct("sourceProduct", sourceProduct)
.sourceProduct
- the source product to be setpublic final Product getSourceProduct(String id)
id
- the identifiernull
if not foundgetSourceProductId(Product)
public final void setSourceProduct(String id, Product product)
id
- a source product identifierproduct
- the source product to be setpublic final String getSourceProductId(Product product)
product
- The source product.null
if no such exists.getSourceProduct(String)
public final Product getTargetProduct() throws OperatorException
If the target product is not set, calling this method results in a
call to initialize()
.
OperatorException
- May be caused by initialize()
, if the operator is not initialised,
or if the target product is not set.public final void setTargetProduct(Product targetProduct)
Must be called from within the initialize()
method.
targetProduct
- The target product.public final Object getTargetProperty(String name) throws OperatorException
If the requested target property is not set, calling this method results in a
call to initialize()
.
name
- the name of the property requested.OperatorException
- May be caused by initialize()
, if the operator is not initialised,
or if the target product is not been set.public Object getParameter(String name)
name
- The parameter name.null
.public Object getParameter(String name, Object defaultValue)
name
- The parameter name.defaultValue
- The default value which is used in case getParameter(String)
returns null
. May be null
.defaultValue
.public void setParameter(String name, Object value)
name
- The parameter name.value
- The parameter value, which may be null
.public final Tile getSourceTile(RasterDataNode rasterDataNode, Rectangle region) throws OperatorException
Tile
for a given band and image region.rasterDataNode
- the raster data node of a data product,
e.g. a Band
or
TiePointGrid
.region
- the image region in pixel coordinatesOperatorException
- if the tile request cannot be processedpublic final Tile getSourceTile(RasterDataNode rasterDataNode, Rectangle region, javax.media.jai.BorderExtender borderExtender) throws OperatorException
Tile
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.rasterDataNode
- the raster data node of a data product,
e.g. a Band
or
TiePointGrid
.region
- The image region in pixel coordinatesborderExtender
- A strategy used to fill the raster regions that lie outside the bounds of the source image.OperatorException
- if the tile request cannot be processedprotected final void checkForCancellation() throws OperatorException
OperatorException
- if the current processing request has been canceled (e.g. by the user).protected void ensureSceneGeoCoding(Product... products) throws OperatorException
initialize()
method to ensure that their
sources are geo-coded.products
- The products to test.OperatorException
- if any product has no geo-coding.protected Dimension ensureSingleRasterSize(Product... products) throws OperatorException
initialize()
method if they can only deal with
single-size sources.products
- Source products products to test.null
if products
is an empty arrayOperatorException
- if the product contains multi-size rasters.protected Dimension ensureSingleRasterSize(RasterDataNode... rasterDataNodes) throws OperatorException
rasterDataNodes
- Other optional products to test.null
if rasterDataNodes
is an empty arrayOperatorException
- if the product contains multi-size rasters.public final Logger getLogger()
public void stopTileComputationObservation()
public final void setLogger(Logger logger)
logger
- The logger.public final OperatorSpi getSpi()
public final void setSpi(OperatorSpi operatorSpi)
operatorSpi
- The operator SPI.Copyright © 2014–2017 European Space Agency (ESA). All rights reserved.