What to consider when writing an Operator in Python

Even though SNAP is based on the Java programming language it supports also the development of operator plugins written in Python. This is mad possible by the snappy module. It enables Python developers to write operators for SNAP. In the background, snappy uses the library jpy which builds a bridge between Java and Python.
The intention of this page is to point out where writing an operator in Python is different from writing an operator in Java and what you need to consider. In general, the concepts presented in How to create a new operator , How to integrate an operator, and Operator Implementation Guidelines also apply here. This page will focus on pointing out where they are different. A working example of a Python operator plugin can be found in the snap-examples repository on GitHub. The RUT project provides an example of a Python-based Operator in operational use. As you will use the Java API of SNAP Engine via snappy, you should familiarise yourself with this API, or at least know where and how to look things up. 

Table of Contents

Prerequisites 

In order to write a Python plugin for SNAP, you need the following tools:

• Maven >= v3.2.5
  Maven is the build tool used to build and package the final plugin file.
  
• 2.7 <= Python <= 3.4 (recommend is =3.4)

In order to make the development easier, we recommend PyCharm as your IDE. Also, before starting to implement an operator you should make sure that you have followed the procedure described in Configure Python to use the SNAP-Python (snappy) interface.

Project Structure

The recommended basic project structure differs slightly from the structure of a Java project. It looks as shown in the following code block.

my-module/
    src/main/
        python/my_python_op.py
        python/my_python_op-info.xml
        nbm/manifest.mf
        resources/META-INF/services/org.esa.snap.python.gpf.PyOperatorSpi
        resources/layer.xml
pom.xml

The main differences are that you use (1) a Python file for your operator (obviously), (2) a dedicated .xml-file to set the operator metadata, and (3) a Python-specific OperatorSpi-file to register the Operator in SNAP. These files will be explained below in detail.

Operator Implementation

An Operator implemented in Python needs to have three methods. The initialize() - method , one of the three methods to compute ( doExecute(), computeTile() or computeTileStack() ) and the dispose() method. Please have a look at the following skeleton of an operator.

class MyOp:

    def __init__(self):
        pass
 
    def initialize(self, context):
        pass
 
    # You need to either implement this, the computeTile method or the computeTileStack method
    def doExecute(self, pm):
        pass

    # You need to either implement this, the doExecute method or the computeTileStack method 
    def computeTile(self, context, band, tile):
        pass
 
    # You either implement this, the doExecute method or the computeTile method
    def computeTileStack(self, context, target_tiles, target_rectangle):
        pass
 
    def dispose(self, context):
        pass

The __init__() can be dropped if you find it is not necessary. The meaning and use of the other methods is discussed in How to create a new operator and Operator Implementation Guidelines.

The context object you see as a parameter to all of the methods gives you to some general useful methods.

By extending the rectangle used with one of the getSourceTile() methods you can get data which is outside of the target region which is currently processed.

Operator Metadata

While for Java Operators the Metadata is set through Annotations, in Python an XML file serves this purpose. This file must start with the same name as the module in which the operator is implemented and must end with -info.xml. The file is used to define processing parameters, the source product(s) and some more metadata about the operator like an operator alias name, description, version etc.

<operator>
    <name>org.me.MyPyOp</name>
    <alias>my_py_op</alias>
    <operatorClass>org.esa.snap.python.gpf.PyOperator</operatorClass>
    <version>1.0</version>
    <authors>ACME Guys</authors>
    <copyright>(C) 2016 ACME</copyright>
    <description>
        A short description of the operator
    </description>
    <namedSourceProducts>
        <sourceProduct>
            <name>source</name>
        </sourceProduct>
    </namedSourceProducts>
    <parameters>
        <parameter>
            <name>factor</name>
            <description>Short description of the parameter</description>
            <dataType>double</dataType>
            <defaultValue>1.0</defaultValue>
        </parameter>
    </parameters>
</operator>

A full example for such an XML file can be found in the example repository. In the following, the meaning and the usage of the tags are described.

<namedSourceProducts>
    <sourceProduct>
        <name>myInput</name>
    </sourceProduct>
    <sourceProduct>
        <name>auxProduct</name>
    </sourceProduct>
</namedSourceProducts>

The following table shows the possible tags to configure a parameter (inside the <parameter> tag).

<unit>

Graphical UI for the Operator

Currently, it is not possible to define your own GUI in Python. To use the standard GUI see How to integrate an operator.

Service Registration

Like Java Operators, Python Operators need to be registered via the Java Service Provider Interface (SPI). For Python Operators, there exists a bridge via the PyOperatorSpi. To use this class, users need to create a file named 

# In order to publish the python operators in this plugin module to SNAP, they need to be listed in this file. On each
# line an operator class is specified by its fully qualified name.
# A fully specified name includes the Python package path and the class name both separated by dot characters ('.').
# For example:
#
# cloud_mask.CloudMaskOp
# water.mci.MciOp
# land.ndvi.NdviOp
# land_ops.FaparOp
#
# Following Python conventions, the last name in the package path must therefore either be subpackage or a Python
# file. For the 'water.mci.MciOp' entry above, the pysical representation could either be:
# (a)  water/mci.py  where mci.py defines the MciOp class
# (b)  water/mci/__init__.py  where __init__.py defines the MciOp class

ndvi_op.NdviOp

• ensure same Python configuration (used libraries) on the user system as the developer uses
• GPF.getDefaultInstance().getOperatorSpiRegistry().loadOperatorSpis() needs to be called
• Import-Vector can't be used (see forum thread)
• logging configuration might be changed by snappy (see forum thread)