How to integrate an external tool in SNAP

When having an executable file to make a certain operation, this execution can be integrated in SNAP in order to define an adapter that can be used multiple times, redistibuted and also chained with other operations from SNAP.

Step-by-step guide

There are two ways to create an adapter over an executable:

  1. Creating and running the adapter by using the SNAP application, which has user-friendly forms for this operations
  2. Creating the adapter files by using a text editor and a jar packager (for more experimented users/developers)

In order to use one of this two ways, it is necessary to know the format of the adapter's files. The adapter consists in a folder or a jar file; the name of the folder or jar file is the alias of the adapter. The folder/jar file should contain:

  • a file called <adapter_alias>-template.vm, which is a velocity template that contains the command line parameters of the execution, each parameter on a separate line
  • a subfolder called META-INF
  • a file called descriptor.xml under the META-INF subfolder

The xml descriptor file should have the format (tag hierarchy) :

  • the root tag is called operator. This tag contains the following children:
    • the tag name. This tag content coresponds to the unique name that the operator will be registered with in SNAP context
    • the tag operatorClass should contain the value org.esa.snap.framework.gpf.operators.tooladapter.ToolAdapterOp since this is the class of the adapters operators
    • the tag alias. The content of this tag should match the name of the operator's folder

Creating the adapter using the SNAP desktop application

Open the External Tool dialog clicking the menu entry:

The External Tools dialog will show you all the tools installed, create new, edit the existing or removing the one installed, to create a new one click on the "+" icon:

Once the "+" button clicked the New External Tool window appear, the first tab you have to configure is the Operator Descriptor panel where you define the operator name (Alias and Label) and other important information about the external tool, in the bottom is also possible to define where the operator will appear in the menus by selecting an existing category or creating a new one.

It is important the the Unique Name field respect the Java naming convention and that is really unique.

Than if you have a bundle package of your tool in your local filesystem or on a server your can specify the location to automatically install it when distributing the extension by configuring the Bundled Binaries panel. It is also possible to define different bundles for the different supported OS in order to make it correctly working. Note that the Target Folder will be the folder where the bundle will be installed.

It is now time to configure the Operator parameters that must be passed to your tool and that the user can change in the future operator dialog, the default parameters represent the input file and output file but you can add extra parameters such as product band and more in the Operator Parameter panel.

It is also possible to set system variables (also per OS) in the System Variables panel if necessary.

Another optional step is to configure a preprocessing step where the product can be converted in another format or processed with some other tool.

The configuration is done in the Processing panel.

Finally the external tool must be configuration by specifying the executable path and executable working directory (it could be a temporary folder) and finally defining the command line template where you can define the parameters to pass to the external tool in the Configuration Parameters panel.

In this panel it is also possible to define some regex pattern to parse the output of the external tool and use it to display the progress of the processing inside SNAP.