org.esa.beam.framework.gpf
Class Operator

java.lang.Object
  org.esa.beam.framework.gpf.Operator

Direct Known Subclasses:

GraphOp, PointOperator

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(java.util.Map, java.awt.Rectangle, com.bc.ceres.core.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:

1. 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.
2. 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.

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.

todo - Explain the role of operator annotations (nf - 15.10.2007)

todo - Explain the role of the SPI (nf - 15.10.2007)

Since:

4.1

Author:

Norman Fomferra, Marco Peters, Marco Zühlke

See Also:

OperatorSpi, OperatorMetadata, Parameter, TargetProduct, TargetProperty, SourceProduct, SourceProducts

Constructor Summary

protected

Operator() Constructs a new operator.

Method Summary

protected void	checkForCancellation() Checks for cancellation of the current processing request.
void	computeTile(Band targetBand, Tile targetTile, com.bc.ceres.core.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, com.bc.ceres.core.ProgressMonitor pm) Called by the framework in order to compute the stack of tiles for the given target bands.
protected void	deactivateComputeTileMethod() Deactivates the computeTile method.
void	dispose() Releases the resources the operator has acquired during its lifetime.
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.
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.
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.
protected 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.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Operator

protected Operator()

Constructs a new operator.

Method Detail

finalize

protected final void finalize()
                       throws Throwable

Overridden in order to force a call to dispose(), if not already done.

Overrides:

finalize in class Object

Throws:

Throwable - The Exception raised by this method

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 the TargetProduct annotation or by calling setTargetProduct(org.esa.beam.framework.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.

Throws:

OperatorException - If an error occurs during operator initialisation.

See Also:

getTargetProduct()

update

public void update()

Updates this operator forcing it to recreate the target product. Warning: Experimental API added by nf (25.02.2010)

Since:

BEAM 4.8

computeTile

public void computeTile(Band targetBand,
                        Tile targetTile,
                        com.bc.ceres.core.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 cancelation requests.

Throws:

OperatorException - If an error occurs during computation of the target raster.

computeTileStack

public void computeTileStack(Map<Band,Tile> targetTiles,
                             Rectangle targetRectangle,
                             com.bc.ceres.core.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 in targetRasters).

pm - A progress monitor which should be used to determine computation cancelation 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.

deactivateComputeTileMethod

protected final void deactivateComputeTileMethod()
                                          throws IllegalStateException

Deactivates the 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 bands.

Throws:

IllegalStateException - if the computeTileStack method is not implemented

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 for getSourceProduct("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 for setSourceProduct("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 identifier

product - 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 by initialize(), if the operator is not initialised, or if the target product is not set.

setTargetProduct

protected 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 by initialize(), 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

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 be null.

Since:

BEAM 4.7

getSourceTile

public final Tile getSourceTile(RasterDataNode rasterDataNode,
                                Rectangle region)
                         throws OperatorException

Gets a Tile for a given band and image region.

Parameters:

rasterDataNode - the raster data node of a data product, e.g. a Band or TiePointGrid.

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 a Tile for a given band and image region. The region can overlap the bounds of source image. This method is particulary 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. a Band or TiePointGrid.

region - The image region in pixel coordinates

borderExtender - 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).

getLogger

public final Logger getLogger()

Gets the logger whuich can be used to log information during initialisation and tile computation.

Returns:

The logger.

stopTileComputationObservation

public void stopTileComputationObservation()

Non-API.

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.

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.