Package org.esa.snap.core.gpf

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

    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:
    OperatorSpi, OperatorMetadata, Parameter, TargetProduct, TargetProperty, SourceProduct, SourceProducts, Tile

    • Constructor Detail

      • Operator

        protected Operator()
        Constructs a new operator.

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

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

        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.