Package org.esa.snap.core.gpf

Class Operator

java.lang.Object
org.esa.snap.core.gpf.Operator
Direct Known Subclasses:
BandMathsOp, GraphOp, ImportVectorOp, JaiOp, MergeOp, MosaicOp, PassThroughOp, PointOperator, ProductSetReaderOp, QuantizationOp, RasterToVectorOp, 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:

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.

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.

Since:
4.1
See Also:

  • Constructor Details

    • Operator

      protected Operator()
      Constructs a new operator.

  • Method Details

    • 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 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.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.

      Throws:
      OperatorException - If an error occurs during operator initialisation.
      See Also:

    • 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

      1. once before the very first tile is computed, or
      2. 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 in targetRasters).
      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's computeTileStack 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's computeTileStack 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 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:

    • 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:

    • 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

      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 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

    • 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 case getParameter(String) returns null. May be null.
      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 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 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. 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).

    • 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 their initialize() 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 their initialize() method if they can only deal with single-size sources.
      Parameters:
      products - Source products products to test.
      Returns:
      the unique raster size, null if products 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 if rasterDataNodes 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.