Standalone Tool Adapter - Editing adapters

Creating a new adapter or modifying an existing one

The form for creating a new adapter is reused for editing an existing adapter and for duplicating an adapter.

The form is structured into multiple areas:

• descriptor details
• system variables
• pre-processing
• configuration
• tool output patterns
• parameters

For details about the operator structure and what is the use of each member, see here.

Descriptor details

This area consists in the following fields:

• Alias: a short name for the adapter to distinguish from the rest of the adapters, this alias will be used to name the folder on disk where the operator resides, so special characters should not be used (for example, on windows, the following characters are not allowed when defining a folder name: <>:"/\|?*). This is a required field.
• Unique Name: this name is a name which registers the adapter in the toolbox. It must be unique. This is a required field.
• Label: is the user-friendly name. This field is not required.
• Version:
• Copyright:
• Authors:
• Description:
• Menu Location: this represents the path to the menu where the tool shortcut will be placed. The user can choose between placing the adapter action in one of the already existing menus, or to create a new menu.

System variables

System variables are values that must be set when the tools is executed. Such a variable may or may not be a system-wide variable (eg. one set in Environment Variables on Windows OS). If the latter case, the system value will always replace the user-defined value. The value of a system variable (in the context of Standalone Tool Adapter) can be shared across adapters, with the condition it is defined in each such adapter. For example, if two adapters declare the same $VAR variable, it is enough to edit its value in one of the adapters, and it will be automatically reflected in the other adapter.

There are two types of variables:

• Simple variables, that only have one value;
• System-dependent variables, that allow setting values for the three operating systems supported (Windows, Linux and MacOSX). This kind of variables is necessary, for example, when you'd like to create a single adapter that can be used on either OS, but there are just a few elements that are different among OSes (like, for example, the shell script extension: .bat on Windows, .sh on Linux and MacOSX).

Pre-processing area contains 2 field, each one with a checkbox and a combobox:

• Pre-processing tool: when this option is checked and an already defined tool is chosen in the combobox, that tool is executed with the same input parameters values as the current tool, as the first step of the execution of the current adapter.
• Write before pre-processing: when this option is checked and a writer is selected in the combobox, the product is written to disk as the second step of the execution of the current adapter. The path where the product is saved is given as the value of the parameter sourceProductFile

Configuration parameters includes:

• Tool location: location of the executable file corresponding to the tool. The location can be expressed in one of the following forms:
  • Just the executable name (and extension), with the condition that it is already added to system path;
  • A path expressed by means of one of the defined system variables and the executable name (and extension);
  • The full path of the executable (including its name and extension).
• Working directory: the place where the temporary files are saved. One can use one of the define system variables to set its value.
• Tool handles the output name: whether the tool needs the name of the output product, or it produces it by itself.
• Command line template: the velocity template to be executed, including the command line arguments of the tool, each one of them on a separate line. The content of the template is saved in a file called <operator_alias>_template.vm under the folder of the operator.
  To use parameters and system variables in the velocity template, you have to prepend their names with the dollar sign ('$'). To minimize the spelling errors when typing parameters, when pressing '$' a suggestion list will be displayed, containing all the parameter and variable names, lexicographically sorted:
  

Note: all the values of the parameters of type File (the tool location, the working directory, and any other File (or File List) type parameter that is marked as 'Not Null' or 'Not Empty' will be checked for pointing to existing files or folders when pressing the OK button.

Tool output patterns

Tool output patterns includes 2 defined patterns for determining the progress of the tool and also the error status. When the tool outputs something, the two patterns are checked and if one of them matches the output, this is registered in the log (in SNAP application, when the Console is active, the log messages will appear in the console view)

Operator parameters

This area consists in a table of parameters necessary for the processing of the velocity template. Each parameter can have the following properties:

• name
• description
• label
• data type
• default value

The data type of a parameter can be as follows:

Default (read-only) parameters

An adapter must have 3 parameters. If the descriptor of the adapter does not contain one or all of this parameters, they are added when the editing form is launched. Those parameters are:

• sourceProduct - represents the product(s) choosed by the user from the ones loaded in SNAP context on the time of the execution (see Executing an adapter for details about how to choose a product). When this parameter is used in the velocity template, for each product the method getFileLocation() is called, and the path returned by the method is passed to the velocity template. If there are multiple source products, each one is accessed by using the syntax sourceProduct[0], sourceProduct[1], ... This parameter cannot be edited or deleted.
• sourceProductFile - this is a File or a list of files corresponding to the source products chosed on execution. This is used only if 'Write product with' is checked and a writer is chosed. When this happens, all the source products are written on disk, in the temporary folder, and the absolute path of the file(s) is stored in this parameter, so it can be used in the velocity template. This parameter cannot be edited or deleted.
• targetProductFile - this is a File corresponding to the target product that will be loaded in SNAP context after the tool execution. This parameter cannot be deleted or edited, but his value can be edited (the default value and also the value on execution).

Regular parameters

All user-defined parameters that are not default parameters or template parameters are considered as regular parameters. The type of those parameters can be: Integer, Decimal, String, Boolean, List. Those parameters can be edited by pressing the corresponding 'Ellipsis' (...) button. This will open a new form, where the following properties of the parameter can be changed:

• Name
• Alias
• Type
• Default value
• Description
• Label
• Unit
• Interval
• Value set
• Condition
• Pattern
• Format
• Not null
• Not empty
• Alias
• Deprecated

Template parameters

The template parameters are parameters that represent a velocity template stored in a file on disk. So this is actually a parameter, having the type File, on which you can pass other regular parameters.

When editing this type of parameter, first a file must be chosed, and then the template gets loaded in the form and some new parameters can be defined for this template:

This template will be interpreted in 3 key moments of the execution:

• If the parameter type is Template Before, the template gets interpreted before any of the execution steps of the toll gets started.
• If the parameter type is Template Parameter, the template gets interpreted on strating the execution of the tool. In this case, the result is saved in the working directory, and the full path to the file gets saved in this parameter's value.
• If the parameter type is Template After, the template gets interpreted after the execution steps of the toll, as the final step. The result is also saved in the working directory.

Bundled Binaries

In this tab the user can integrate an installer in the adapter. When the adapter is downloaded/installed, the user can install also manually the tool. In case of a remote installer, installing the tool actually means downloading the installer from the given URL and copying it on a local address. After the tool is installed in the target folder (as configured in the adapter), all the adapter parameters and variables should be valid. The tool can be configured to be install on Windows, Linux and MaxOSX

This area consists in the following fields:

• Type: there are two options to choose, Zip archive (must be Self-Extracting Zip file) or installer.
• Location: if Local is selected, the Source File field should contain the local address of the installer or of the zip archive. Otherwise, if Remote is selected, the URL field should contain the address of the installer or the zip archive that will be downloaded.
• Arguments: the arguments used to install the Self-Extracting archive.
• Target Location: the location where the user wants to install the tool.
• Reflect in Variable: the user can choose an already existing variable, which will have as value the location where the tool was installed.