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:
- 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.
- 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.
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.
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
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.
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.
Once the names of the inputs and outputs have been defined, you can close the compound from the context menu.
The default name of a compound is, aptly, "Compound". You can change this from the tool's properties dialog.
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.