[FrontPage] [TitleIndex] [WordIndex

Sextante Process Provider Implementation Notes

1. Introduction

SEXTANTE is a set of free geospatial analysis tools. The main goal of SEXTANTE is to develop new (geo)algorithms based on the SEXTANTE framework. deegree uses the already developed geoalgorihms to be provided within the WPS framework, focusing the processing of vector data.

2. Get SEXTANTE

On the SEXTANTE website you can download binary files. Source code is available via the SVN repository. To handle vector data you will need the following libraries:

These libraries you will find within the folder "core" of sextante-x.x.zip.

3. Architecture of SEXTANTE

http://wiki.deegree.org/deegreeWiki/deegree3/SextanteImplementationNotes?action=AttachFile&do=get&target=architecture_of_sextante.png

SEXTANTE has three basic components:

The bindings consist of three basic interfaces: IVectorLayer, IRasterLayer and ITable to describe the input and output data of the algorithm. SEXTANTE provides no implementations of those basis interfaces, this means that you should use a geodata access library like deegree. Instead of implementing this interfaces directly, there are three abstract classes AbstractVectorLayer, AbstractRasterLayer and AbstractTable that should be extended. For using vector data you should be extend the class AbstractVectorLayer.

Every algorithm returns one or more output objects. Every output object implements one of the basic interfaces. An algorithm needs an output factory to create the output objects. You must extend the class OutputFactory to create the corresponding output factory.

4. Executing a geoalgorithm

An algorithm can be executed when initialized with input data and an output factory. For example, the centroid algorithm needs only a IVectorLayer with input data and a OutputFactory to create a IVectorLayer with the processed data.

The following source code shows the execution of the centroid algorithm.

...
// initialize SEXTANTE
Sextante.initialize();

// create vector layer with input data
IVectorLayer inputLayer = ...

// create algorithm
GeoAlgorithm alg = new CentroidsAlgorithm();

// commit input data to algorithm
ParametersSet inputParams = alg.getParameters();
inputParams.getParameter( CentroidsAlgorithm.LAYER ).setParameterValue( inputLayer );

// execute algorithm
alg.execute( null, new OutputFactory... );

// create vector layer with output data
OutputObjectsSet outputParams = alg.getOutputObjects();
Output output = outputParams.getOutput( CentroidsAlgorithm.RESULT );
IVectorLayer outputLayer = (IVectorLayer) output.getOutputObject();
...

5. Implementation

This chapter gives an overview of all the necessary steps to use SEXTANTE for the WPS.

5.1. AbstractVectorLayer

SEXTANTE algorithms need vector data as IVectorLayer. It is recommended to extend the abstract class AbstractVectorLayer as the interface directly. The class AbstractVectorLayer inherits from the interfaces IDataObject, ILayer, IVectorLayer and implements a part of that. Following methods must be implemented:

Methods of IVectorLayer:

// adds a feature with geometry and properties
public void addFeature(com.vividsolutions.jts.geom.Geometry geometry, java.lang.Object[] attributes);

// returns number of properties
public int getFieldCount();

// returns property name
public String getFieldName( int index );

// returns property type
public Class<?> getFieldType( int index );

// returns geometry type  (POINT, LINE, POLYGON or MIX)
public int getShapeType();

// returns number of geometries
public int getShapesCount();

// returns iterator to iterate over the IFeatures
public IFeatureIterator iterator();

Methods of ILayer:

// returns the coordinate reference system
public Object getCRS();

// returns a envelope of all features
public Rectangle2D getFullExtent();

Methods of IDataObject:

// closes the data object, which was opened
public void close();

// returns the filename
public String getFilename();

// returns the name
public String getName();

// opens the data object
public void open();

// post processes the data object
public void postProcess();

// sets a new name
public void setName( java.lang.String sName );

5.2. OutputFactory

The OutputFactory defines how new data objects (IVectorLayer, IRasterLayer or ITable) are created. The methods of this class are called from geoalgorithms to create output objects. To adapt an output factory for your need, you must implement the following methods:

// returns the default CRS for new layers
public Object getDefaultCRS();

// create new raster layer
public IRasterLayer getNewRasterLayer( java.lang.String sName, int iDataType, GridExtent extent, int iBands, IOutputChannel channel, java.lang.Object crs);

// create new table
public ITable getNewTable( java.lang.String sName, java.lang.Class[] types, java.lang.String[] sFields, IOutputChannel channel);

// create new vector layer
public IVectorLayer getNewVectorLayer( java.lang.String sName, int iShapeType, java.lang.Class[] types, java.lang.String[] sFields, IOutputChannel channel, java.lang.Object crs );

// create new vector layer
public IVectorLayer getNewVectorLayer( java.lang.String sName, int iShapeType, java.lang.Class[] types, java.lang.String[] sFields, IOutputChannel channel, java.lang.Object crs, int[] fieldSize );

// returns supported extensions for raster layers
public String[] getRasterLayerOutputExtensions();

// returns supported extensions for tables
public String[] getTableOutputExtensions();

// returns task monitor
public ITaskMonitor getTaskMonitor( java.lang.String sTitle, boolean bDeterminate, javax.swing.JDialog parent );

// returns the temp folder
protected String getTempFolder();

// returns supported extensions for vector layers
public String[] getVectorLayerOutputExtensions();

5.3. VectorLayerAdapter

Currently, the conversion from a FeatureCollection, a Feature or a Geometry to a IVectorLayer and reverse is complicated. The VectorLayerAdapter takes care of these conversions. The IVectorLayerAdaper has the following methods:

// convert to vector layer
public static IVectorLayer createVectorLayer( FeatureCollection c );
public static IVectorLayer createVectorLayer( Feature f );
public static IVectorLayer createVectorLayer( Geometry g );

// convert back
public static FeatureCollection createFeatureCollection( IVectorLayer l );
public static Feature createFeature( IVectorLayer l );
public static Geometry createGeometry( IVectorLayer l );

5.4. SextanteWPSProcess

The class SextanteWPSProcess implements the interface WPSProcess for compatibility with the deegree WPS. One instance represents one WPS process. Following methods must be implemented:

// returns description about input and output data of the process
public ProcessDefinition getDescription();

// returns sextante processlet
public Processlet getProcesslet();

// returns exception customizer
public ExceptionCustomizer getExceptionCustomizer();

The method getDescription() is very extensive. The class SextanteWPSProcess should represent every SEXTANTE algorithm, so you need to differentiate all input and output parameters of an algorithm. These parameters are wrapped in methods like create...InputParameter() and create...OuputParameter(). For example, for process vector data you must implement the methods createVectorLayerInputParameter() and createVectorLayerOutputParameter(). The constructor uses these methods to create the process description.

5.5. SextanteProcesslet

The class SextanteProcesslet wraps the execution of a SEXTANTE algorithm and implements the interface Processlet, so it's compatible with the WPSProcess. The interface Processlet requires the following three methods:

// called by the ProcessManager to perform the execution of this Processlet
public void process( ProcessletInputs in, ProcessletOutputs out, ProcessletExecutionInfo info );

// called by the ProcessManager to indicate to this Processlet that it's being placed into service.
public void init();

//Called by the ProcessManager to indicate to this Processlet that it's being taken out of service.
public void destroy();

The method process(...) executes the SEXTANTE algorithm, so you must differentiate all input and output data to transfer it to and from algorithm. This is wrapped in methods like set...InputValue() for input data and write...() for output data. For example, to transfer vector data to the algorithm you must implement the method setVectorLayerInputValue(). To transfer vector data back from algorithm you must implement the method writeVectorLayer(). This two methods use the implementation of IVectorLayer and the IVectorLayerAdapter.

5.6. FormatHelper

The class FormatHelper contains all supported input and output schemas and methods to get input and output formats and to determine GMLVersion and GMLType.

// determine GMLVersion (GML_2, GML_30, GML_31, GML_32)
public static GMLVersion determineGMLVersion( ComplexInput input );
public static GMLVersion determineGMLVersion( ComplexOutput output );

// determine GMLType (GEOMETRY, FEATURE_COLLECTION)
public static GMLType determineGMLType( ComplexInput input );
public static GMLType determineGMLType( ComplexOutput output );

// get ComplexFormatTypes
public static ComplexFormatType getDefaultInputFormat();
public static ComplexFormatType getDefaultOutputFormat();
public static LinkedList<ComplexFormatType> getInputFormatsWithoutDefault();
public static LinkedList<ComplexFormatType> getOutputFormatsWithoutDefault();

This class will be used by SextanteWPSProcess and SextanteProcesslet to obtain information on how to parse or write data.

5.7. deegree 3 WPS process provider

With the above-mentioned classes, we can implement and use a ProcessProviderProvider and a ProcessProvider for SEXTANTE. These will use the SEXTANTE processes with the deegree WPS.

It is explained in detail here: HowToCreateWPSProcessProviders.

6. Problems

6.1. Process a FeatureCollection

If you want to send a feature collection to the WPS, you must specify the application schema.

<ComplexData encoding="UTF-8" mimeType="text/xml" schema="http://schemas.opengis.net/gml/3.1.1/base/feature.xsd">
        ...
</ComplexData>

<Output asReference="false" encoding="UTF-8" mimeType="text/xml" schema="http://schemas.opengis.net/gml/3.1.1/base/feature.xsd">
        ...
</Output>

It will be used for the correct parsing of a feature collection. Since there is no general feature collection schema available, we use the following schemas to process feature collections:



2018-04-20 12:05