Warning This page is out-dated and will be rewritten soon.

Requirements

Framework Requirements

Service provider interface

Operator implementations shall be published via the Java service provider interface (SPI). A JAR publishes its operators in the resource file META-INF/services/org.esa.beam.framework.gpf.OperatorSpi.

Operator and OperatorSpi

The operator API shall be as simple and lightweigt as possible. The API shall be build around two main interfaces: OperatorSpi and Operator.

public interface OperatorSpi {
   Operator createOperator();
   //...
}

public interface Operator {
   OperatorSpi getSpi();
   Product initialize(OperatorContext context);
   void computeTile(Tile targetTile, ProgressMonitor pm);
   void computeTiles(Rectangle targetTileRectangle, ProgressMonitor pm);
   void dispose();
}

These interfaces provide exactly the methods required by the framework, not more (no e.g. utility methods).

The computeTile and computeTiles methods express different application requirements. Clients may either implement computeTile or computeTiles or both. In general, the algorithm dictates which of the methods will be implemented. Some algorithms can compute their output bands independently (band-arithmetic, radiance to reflectance conversion), other cannot (e.g.)

The GPF selects the method which best fit to the application requirements:

• In order to display an image of a band, the GPF is asked to compute tiles of single bands. The GPF therefore will prefer calling the computeTile method, if implemented. Otherwise it has to call computeTiles, which might not be the best choise in this case.
• In order to process in batch-mode or to save a product to disk within VISAT, the GPF is asked to compute the tiles of all bands of a product. The GPF therefore will prefer calling the computeTiles method, if implemented. Otherwise it will consecutively call the computeTile for each output band.

OperatorContext

TODO

public interface OperatorContext {
   Product getTargetProduct();
   Product getSourceProduct(String name);
   Product[] getSourceProducts();
   Raster getTile(RasterDataset dataset, 
                  Rectangle tileRectangle);
   Raster getTile(RasterDataset dataset, 
                  Rectangle tileRectangle, 
                  ProgressMonitor pm);
   Raster getTile(RasterDataset dataset, 
                  Rectangle tileRectangle, 
                  ProductData dataBuffer, 
                  ProgressMonitor pm);
   Logger getLogger();
}

public interface Raster {
   ProductData getDataBuffer();
   int getX();
   int getY();
   int getWidth();
   int getHeight();
   // ... 
   double getDouble(int x, int y);
   void setDouble(int x, int y, double value);
}

OperatorProductReader

The Operator interface is designed in a way that makes it possible to easily adapt it to the existing ProductReader interface:

public class OperatorProductReader implements ProductReader {
   private Operator operator;
   // ...
}

Since a Product always has a ProductReader, the processing graph XML is effectively transformed in graph of products – connected by their {{ProductReader}}s.

AbstractOperator

Clients shall be advised not to implement the Operator interface directly, but use the AbstractOperator as base class instead. The Operator interface may change in the future. In this case, the AbstractOperator will provide reasonable default implementations for new interface methods in order to provide backward compatibility.

Operator developers (clients of the framework) may also want a richer operator API. The AbstractOperator provides methods that simply delegate to the OperatorContext and {{TileProvider}}s interfaces (see below). This way, the client code is more easy to understand and not cluttered with delegations to framework-provided interfaces.

AbstractOperator shall also provide some frequently used operations:

• Create target product covering same scene as source product(s)
  • Copy geocoding
  • Use source scene raster dimensions
• Get array of band objects (Band[]) from array of band names (String[]).
• More to come...

2D-wrapper for product data

Provide 2D-wrapper for product data, e.g. Raster, see below

public interface Raster {
   public ProductData getDataBuffer();
   //...
   public getDouble(int, x, int y);
   public setDouble(int, x, int y, double v);
}

Application Requirements

Fields of applications for the GPF are

• command-line interface (CLI) applications and batch mode processing
• web services. e.g. MERCI
• desktop applications with a graphical user interface (GUI), e.g. VISAT

Invoking a Operator

A static class shall be provided to invoke an Operator. This class shall be similar to the one provided by JAI.

CLI

CLI applications and web services will read a graph XML stream and generate one or more output products at once. This requires the effective and performant computation of all bands of the requested output products.

Many algorithms TODO

GUI

Tiled image display

TODO

Operator editors

A GUI (e.g. VISAT) that works on graphs, shall be able to let the user edit parameters of an operator node. The GUI shall then recompute all dependencies on the modified operator node.

Operator dependencies and change events

If it is assumed that the target products of operator nodes of a graph are displayed in a GUI in a tree view component. The user shall then be able to open a band of any target product. Operator nodes may then raise an exception if e.g. the parameters are not complete. E.g. if the exception message displayed to the user is "Insufficient number of enough ground control points selected.", the user gets the chance to add GCPs with a dedicated tool to the exception causing operator node.

TODO

Ceres

The GPF shall be provided as a Ceres module but at least command-line interfaces and web services shall also work without a Ceres runtime.

Graph XML Requirements

Specifying variable inputs, outputs and parameters

Processing graph XML should contain the sections <inputs>, <outputs> and <parameters> valid for the entire chain. Although, output nodes are detected by the GPF, it is important that (human) readers of the chain XML understand what the inputs, outputs and parameters are.

Operator identification

In XML the operator shall be identified via its fully qualified SPI class name or by an alias name. This is important, because different implementations for the same algorithm can then be configured in the chain XML and not via different JARs providing different algorithms with same name.

Custom parameters section

Some operators require advanced parameter settings. An operator shall be able to parse (unmarshal) its parameters elements by a custom converter. For writing, XML the converter shall also be able to format (marshal) the operator's parameter values into parameters elements:

    public interface Converter {
        void convertDomToParameters(Xpp3Dom parametersDom, Operator op); 
        void convertParametersToDom(Operator op, Xpp3Dom parametersDom); 
    }

TODO: Xpp3DomConfigurable depends on XPP3. Shall we use the more common W3C DOM here?

Multiple output products

Some operators not only generate a single output product, e.g. CHRIS/Proba noise reduction. The framework shall consider m:n operators, m:1 is only special case. Within the graph, multiple outputs could then be accessible as follows:

	
    <node>
        <id>cluster</id>
        ...
        <targets>
            <abundance/>
            <reflectance/>
        </targets>
        ...
    </node>
   
    <node>
        ...
        <sources>
           <abundance>cluster.abundance</abundance>
           ...
        </sources>
        ...
    </node>

Tile caching

Permanent tiles

Some operators will always ask their sources to return entire rasters, e.g. clustering. They shall be able to tell the framework to permanently keep their source rasters in cache.
Only the implementor knows that a requested tile should be permanent.

class AbstractOperator implements Operator {
   // ...
   Tile getTile(RasterDataset rds, Rectangle r, TileCachingScope tcs);
   // ...
}

Operator implementors shall also be able to directly release a tile:

class Tile {
   // ...
   void release();
   // ...
}

Global tile cache

It is much more simpler to configure and manage a global tile cache instead of having a cache per CachingOperator as we have now. (v1.0)

Tile cache observers

A TileCacheListener shall be used to observe the tile cache as it is modified during processing.

Operator Implementations

JAIOperator

This operator shall at least be able to write images as tiles.
The extended/advanced version could be a wrapper around JAI, so it's possible to use nearly every JAI-operation for processing.

Operator Documentation

1. Generate operator documentation from Operator class (annotation processing) Operator Documentation

Operator Testing

1. Provide test bed for new operators.
2. Optionally generate test from Operator class (annotation processing)
3. Optionally use special TestCase class for testing