Standalone Tools Adapter Specification



Target release2.0.0
Epic SIITBX-7 - Getting issue details... STATUS
Document statusDRAFT
Document owner

Nicolas Ducoin (Unlicensed)

DesignerCosmin Cara
DevelopersCosmin Cara


#TitleUser StoryImportanceNotes

Stand-Alone Tools Adapter

In addition to the APIs, the S-2 Toolbox shall provide Stand-Alone Tools Adapter, i.e. a generic interface that allows for integrating external, stand-alone tools into the S-2 Toolbox. The aim is to provide users an easy and consistent access to existing or new tools or processors developed independently of the S-2 Toolbox that are of high value to the users. If the external tools only have a command-line interface, the Stand-Alone Tools Adapter shall be able to generate a graphical user interface that is consistent with other functions of the S-2 Toolbox.






Users of remote sensing data, may they be data end-users or scientists, usually make use of a variety of different software tools. BEAM already provides a large number of common tools for recurring tasks when working with remote sensing and correlative data. This will also be true for the Toolbox to be developed. However, users will always utilise other tools external to the Toolbox that either provide functionality not provided by the Toolbox or that implement a desired functionality in a different way, or are more performant. Frequently changing between used tools can be time consuming for users due to recurring configuration changes and data management. In many cases, it would be more comfortable and more effective if users could stay in one environment. We propose to achieve this a) by letting the user integrate his desired external tools into the Toolbox, and b) by adding external tools to the Toolbox standard configuration. Within this project we will provide integration of specific tools coming from the ORFEO Toolbox (see subsection below).

Background and strategic fit

This will allow senbox developers to easily integrate new tools and processors in the toolbox.

Use Cases

There is two use cases for the Stand-Alone Tools Adapter: First wrapping a tool, such as a data processor, as a GPF operator so that it can be used in GPF processing chains. Secondly, letting a user invoke an external tool from the Toolbox’ GUI menu and tool bars.

The Stand-Alone Tools Adapter is the glue between the Toolbox and the external tool’s user interface. The three major responsibilities for the Stand-Alone Tools Adapter both in GUI and GPF operator mode are:

  1. Provide the user’s inputs from the Toolbox context to the external tool;
  2. Invoke the tool so that a new process is created;
  3. Notify the user about the progress and eventually let her/him cancel the running process;
  4. Open the generated outputs in the Toolbox.

The points above are now explained in more detail:

Provide the user’s inputs: If the tool is invoked from the Toolbox GUI, the Stand-Alone Tools Adapter will have to take care of the current GUI context and state: opened product files, selected product file, available bands in selected product, the selected band, the displayed views, the selected view may serve as input to the tool. In case of the GPF operator, inputs are provided by standard mechanisms used by the GPT and are already implemented in BEAM: inputs can come from XML configuration files or from command-line parameters.

Notify the user: The output of the tool while it is running, for example logging information, shall be convertible to a progress indication for the user. In the case of invocation from the Toolbox GUI, the user should see a progress bar and shall have a cancel button for immediately terminating long-running processes;

Open the generated outputs: If the tool is invoked from the Toolbox GUI, and the output is readable by the Toolbox it should be opened so that the user can visualise the result. If the tool is invoked from a GPF operator, it shall be ensured that it can serve as input to a subsequent processing step.


Use cases diagrams can be foune here : Standalone Tool Adapter Use Cases

GPF/GPT Use Cases can be found here : Standalone Tool Adapter GPF/GPT Use Case

External tools we want to wrap via the Standalone Tools Adapter can be found here : Sample standalone tools


Proposed solution

From the requirements stated above, we derive the following design goals for the Stand-Alone Tools Adapter:

  • Invoke external tools from Toolbox main menu / tool bar or as GPF operators,
  • Reuse available BEAM VISAT RCP extension mechanism,
  • Extend the Toolbox by configuration, allow scripting, avoid but not forbid Java programming,
  • A dedicated GUI for the tool can be generated from its configuration,
  • Allow for flexible configuration of tool command-line and its arguments/parameters,
  • Support plain text / XML parameter files as input to the a tool,
  • Provide the tool a private working directory which the Toolbox can erase after tool completion,
  • Consider auxiliary datasets used by the tool,
  • Exploit the Toolbox GUI context / GPT context for parameterisation.

In order to meet these goals in a generic and flexible way, we propose to utilise a template engine which will be used to generate the tool’s command-line including the arguments and optionally any number of input parameter files, if a tool requires these. Apache Velocity might be used for this purpose. Velocity can transform plain text template files into plain text output files given a context that provides the template parameters. In our case the Toolbox is providing the context either from the GUI or the GPT. The context also contains the Toolbox global configuration settings and the environment variables of the Toolbox process. XML is often used to describe configuration and Velocity provides easy access to XML data, so extracting information from XML files and provide it on the command line and/or in the parameter files is also possible. The following figure explains the central role of the template engine within our proposed approach:

Schema Standalone Tools Adapter

The user invokes the external tool integration either from the GUI or the GPT (1). The Toolbox uses a tool descriptor providing metadata such as parameter descriptions for generating an appropriate user interface. The user interface initialises itself from the parameter default values in the descriptor and also uses the input parameters, alternatively it may use a dedicated user interface when the tool requires more advanced configuration. The template engine (2) is invoked which will generate the tools command-line and optionally input parameter files. Then the generated command-line script is executed (3) which will invoke the actual tool, given the parameter files, any extra resource files (plain text or binary) and any number of source products as input. While the tool process (4) executes, users will be informed about the progress and will also have the chance to cancel the process. If the tool execution is successful, the Toolbox will may open (5) the generated target product and display it in the GUI or read it as input for a successive processing step.

We will take special care that the default user interface generated in step (1) will look very similar to the ones used by native BEAM GPF processors. We will also allow for the development of dedicated user interfaces using the BEAM API, in the case that the generated default user interface is not satisfactory for a given tool. For example, we can easily generate user interface components for Boolean, numerical, enumeration, text, date and file path parameters. For more advanced components, a user interface will have to be programmed.