Compound tools

In the Builder, compounds provide a way of grouping connected tools so that they together form a single tool. Compound tools serve a few important purposes:

Modularization
All well-designed software consist of independent modules that have clear roles and interfaces. The processing graph is not different. When the size of the graph increases, it soon becomes necessary to create a hierarchical structure. For this, (nested) compounds are a useful tool.
Reuse
If you find yourself repeating the same combination of tools, it makes sense to create compound that can be copied or saved as a custom tool to your tool library.
API functions
When you create API functions out of tools, each function maps to a single tool. Since a single native tool seldom makes up a useful application, the tools published as API functions are typically compounds. Creating a compound out of a single tool may also be useful if you want to change the names of the function's input and output parameters.

Creating a compound

Let us start with the simple processing graph shown in the picture below. The first step is to select the tools that will make up the compound by holding Ctrl and clicking the Binarize Adaptively and Detect Blobs tools. Once this is done, the "Create compound" action in the context menu (right-click) will be enabled. Select it.

Select tools with Ctrl+click and use the context menu to create a compound.

Select tools with Ctrl+click and use the context menu to create a compound.

The Builder will automatically create proxies for inputs and outputs that are connected to tools outside of the new compound. In this case, a proxy input will be created to the image coming from the Image Source.

To add a new input or output parameter, connect the parameter to the "+" symbol as shown in the picture below. The connection mode is activated by clicking the dot on the right side of the parameter.

Add new parameters to the compound's interface by connecting to "+".

Add new parameters to the compound's interface by connecting to "+".

By default, the names of the proxied input and output parameters will be the same as the parameters they are connected to. You can change this from the context menu. If you publish the compound as an API function, the names of the parameters will show up in the function declaration.

Compound's input and output parameters can be renamed.

Compound's input and output parameters can be renamed.

Once the names of the inputs and outputs have been defined, you can close the compound from the context menu.

Close a compound to make it appear as an ordinary tool.

Close a compound to make it appear as an ordinary tool.

The default name of a compound is, aptly, "Compound". You can change this from the tool's properties dialog.

The properties of any tool can be changed with the properties dialog that opens through the context menu.

The properties of any tool can be changed with the properties dialog that opens through the context menu.

If the compound has a well-defined functionality and interface, finding a good name for it is probably quite easy. If you find yourself struggling to find a name, you may need to revisit the structure. In this example, we made a blob detector that uses an adaptive binarization technique to separate background and foreground. "Detect blobs adaptively" thus quite closely tells what is happening.

The final processing graph.

The final processing graph.