Scripting of GTlab#

Scripting in GTlab makes it possible to automate tasks and extend the functionality of the application. It provides access to the Python Console, supports the creation of dynamic workflows, and allows integration of Python code into graph-based workflows.

Typical use cases include inspecting project data, writing custom calculators, implementing loops or conditional tasks, and embedding Python logic into graph nodes.

The Python Console#

GTlab provides an integrated Python Console that allows controlling GTlab and directly managing project data using Python code. The main features of the Python Console include:

Switching between sessions
Opening projects
Managing project data and hub-spoke workflows
Starting hub-spoke workflows

In addition, the Python Console enables direct interaction with the selected Python environment, making it possible, for example, to import Python modules or extend the sys.path list.

The Python Console is located in the Output Dock (Window → Dock Widgets → Output) under the Python Console tab.

Entering and Executing Code#

The Python Console displays the prompt GTlab>, which is ready to accept Python code input. Pressing Enter executes the code. print() outputs, return values, and error messages appear directly below the input. Using the shortcut Shift+Enter also allows entering multi-line Python code, for example to define functions.

The auto-completion feature assists with writing Python code and includes all objects, functions, classes, and modules available in the console scope.

Console content can be cleared by clicking the button in the lower-right corner.

Controlling GTlab#

The Python Console allows direct execution of core GTlab functions that control the application. Typical use cases include switching between sessions, opening projects, and accessing the currently opened project.

switchSession('My Session')
openProject('My Project')
project = currentProject()

These functions provide the entry point for interacting with GTlab from Python. A complete list of available functions, including their parameters and return types, is documented here.

Managing Project Data#

A GTlab project organizes all project data in a hierarchical data tree, which is visualized in the Project Explorer. The Python Console allows exploring this data tree, accessing individual objects, and modifying their properties using Python code.

To do so, the currentProject() function must be called, which returns the currently opened project as a Python object. This object corresponds to the highlighted project entry shown in the Project Explorer.

Using dot notation, all child objects of the project can be accessed and their properties can be read or modified.

proj = currentProject()
proj.<child_object_name>.<subchild_object_name>

Note

All data objects in GTlab, including tasks and calculators, are instances of GtObject. This base class provides methods to read and write the object’s properties.

The following animation demonstrates navigating the project data tree and accessing properties via the Python Console:

Demo of managing project data via Python Console

Managing and Starting hub-spoke Workflows#

A GTlab project includes not only the project data but also the hub-spoke workflows defined within the project. They are visualized in the Processes/Calculators Dock of the GTlab user interface. These workflows can be accessed and modified via the Python Console. In addition, it is possible to start workflows directly from the Python Console.

To access the project-specific workflows, the project object returned by currentProject() provides the child object Process Data. This subtree allows navigation through the project’s workflows, which consist of tasks and calculators, enabling their properties to be read and modified.

A specific workflow can be accessed using dot notation:

proj = currentProject()
my_task = proj.findGtChild('Process Data').<scope>.<workflow_group>.findGtChild('My Workflow')

Here, <scope> refers to the sub-area under Process Data where the workflows are organized (e.g., _user or _custom). <workflow_group> corresponds to the name of the workflow group, and My Workflow is the name of the desired workflow.

To start a workflow directly from the Python Console, the project object provides the method GtProject.runProcess(). It expects the name of a task that serves as the starting point of the workflow. In GTlab, each direct child of a <workflow_group> represents such a starting task. The names of these workflows are listed in the Processes/Calculators Dock, where each workflow appears as a top-level item in the tree view.

proj = currentProject()
proj.runProcess('My Workflow')

Note

Only workflows located in the workflow group that is currently selected and displayed in the Processes/Calculators Dock can be started via the Python Console.

Scripting of workflows#

GTlab offers several ways to integrate Python code directly into workflows. This makes it possible to combine standard workflow elements with custom scripts, add dynamic logic, or extend calculations. The following scripting options are available:

Calculators – embed custom Python code as a calculator within a workflow.
Tasks – define entire workflows dynamically using Python code.
Nodes – integrate Python logic into graph-based workflows.

Together, these elements allow workflows to be customized, automated, and extended beyond predefined functionality.

Calculators#

A calculator, in general, is a workflow element that performs a specific, predefined operation, such as a mathematical computation or a transformation of data. The Python Script Calculator extends this concept by providing a flexible calculator whose behavior is not fixed. Instead, it executes a user-defined Python script.

Within the script, all child objects of the current project can be accessed directly by their names, allowing their properties to be read, modified, and used in custom calculations. This capability makes the Python Script Calculator ideal for prototyping new calculation methods, experimenting with alternative approaches, or integrating custom logic directly at runtime.

The Python Script Calculator provides a configuration dialog with an integrated script editor, where the Python script executed by the calculator can be created and edited.

Python Script Calculator configuration dialog

To check the script for errors, it can be evaluated using Ctrl+E. Evaluation also registers any newly defined variables, classes, or functions, making them immediately available via the editor’s auto-completion. Output messages from evaluation are displayed directly below the editor in the output console

It is important to note that changes made during evaluation are not applied to the data model immediately. They only take effect when the Python Script Calculator is executed as part of a workflow.

During execution as part of a workflow, output messages appear in the Python Console.

Tasks#

A task, in general, is the part of a workflow that controls the execution of its child elements. Typical tasks execute their child elements in a predefined manner, for example sequentially or within loops. The Python Task extends this concept by enabling entire workflows to be defined dynamically through Python code. It allows tasks and calculators to be executed conditionally, iteratively, or in any user-defined sequence.

Within the script, tasks and calculators can be instantiated and executed as Python objects. Additionally, all data model packages of the current project are accessible by their package name. This provides the ability to read and modify the data objects’ properties, as well as using the data when building the workflow. By combining these capabilities with Python features such as loops, conditions, and calculations, tasks and calculators can be scripted to form fully dynamic workflows.

The Python Task provides a configuration dialog with an integrated script editor, where the Python script executed by the Python Task can be created and edited.

The editor offers the same features as in the Python Script Calculator, including auto-completion and script evaluation. In addition, the Python Task editor supports creating, configuring, and executing calculators, and allows loading existing hub-spoke workflows from the project data into the script.

Configuring Calculators#

Within a Python Task dialog, calculators can be configured in three different ways:

Using the user interface

Calculators can be configured directly through their user interface. Any settings applied in this way are automatically translated into Python code and inserted into the script.

To configure a specific calculator, click the Add… button in the Python Task dialog. After selecting the desired calculator, its configuration dialog opens for setting it up. Once the configuration is completed by clicking Finish, the corresponding Python code is automatically inserted into the script. All calculator properties that differ from their default values are set accordingly. The calculator created in this way is then available as a Python object within the script.

Demo of configuring a calculator using the user interface

Using drag and drop

Calculators that are part of a workflow and listed in the Processes/Calculators Dock can be inserted directly into the script using drag & drop. The corresponding Python code is automatically generated, reflecting the calculator’s current configuration.

To insert a calculator this way, simply drag it from the Processes/Calculators Dock into the editor.

Note

Drag & drop only copies the configuration of the selected calculator into the Python script. The original calculator in the workflow remains unchanged.

In the script

Calculators can be created directly within the script by instantiating their corresponding class. The script editor’s auto-completion assists in finding and inserting the instantiation call for a calculator. It appears in the auto-completion list under either the calculator’s class name or the name under which the calculator appears in GTlab.

When a calculator is instantiated in this way, all of its properties are initially set to their default values. The properties can then be adjusted directly in the script, making the calculator fully configurable. Auto-completion helps with this by listing all available properties of the calculator object, making it easy to read and set their values.

All calculators instantiated in the script are based on the GtCalculator type, which provides methods for reading and writing properties. Properties can also be accessed directly using Python attribute access, though this only works for properties whose internal names do not contain spaces or special characters.

Once a calculator has been configured, it can be executed directly from the script using its GtCalculator.run() method.

Note

When evaluating the script in the Python Task configuration dialog, calls to GtTask.run() and GtCalculator.run() do not trigger execution. They always return True as a way to validate the script without running the workflow.

Loading Hub-Spoke Workflows into Python Tasks#

Within a Python Task, it is possible to load entire hub-spoke workflows that are already part of the GTlab project into the Python script. This allows existing project workflows to be controlled and interconnected in a flexible way, enabling the creation of complex, dynamic workflows using Python code.

To load an existing workflow from the project data into the script, the Python Task provides the function findGtTask(). It takes the name of the desired workflow and returns a Python object representing that workflow. All hub-spoke workflows of the project are listed in the Processes/Calculators Dock, making it easy to identify the name of the workflow to be loaded.

The Python object returned by findGtTask() is a clone of the workflow from the project data. It contains all configuration settings as well as all subordinate tasks and calculators of the original workflow, which can be accessed through the hierarchical object tree.

This allows the workflow to be modified and executed within the Python Task without affecting the original workflow in the project data.

A cloned workflow can be started within the Python script using the GtTask.run() method. This executes the entire workflow, including all subordinate tasks and calculators, as defined in the workflow.

It is also possible to execute individual subordinate tasks or calculators separately. Using dot notation, child objects of the workflow can be directly accessed and configured. Tasks can be executed by calling GtTask.run(), and calculators by calling GtCalculator.run().

Important

In Python, objects are automatically deleted when they are no longer referenced, i.e., when they go “out of scope”. This also applies to task objects created with findGtTask(). Since a task object acts as the parent of a hierarchical object tree, all its subordinate tasks and calculators become invalid once the task object is deleted.

Therefore, the task object should remain referenced in the script as long as its child objects are accessed or executed.

Bad Practice:

def get_my_calculator():
    workflow = findGtTask('My Workflow')
    return workflow.MyCalculator

my_calc = get_my_calculator()
# my_calc is now invalid because the workflow object was deleted
my_calc.run()

To avoid this, the task object should be actively kept referenced while working with its subordinate elements:

workflow = findGtTask('My Workflow')
my_calc = workflow.MyCalculator
# the workflow remains referenced, my_calc is valid
my_calc.run()

Nodes#

Example of the usage of a scripting node

The scripting capabilities in GTlab can also be used in the graph-based workflow system. Individual nodes of the graphs can work with Python scripts to modify, generate, analyse or visualise data. As in the other accesses to the python interface in GTlab, any other python libraries installed in the python environment used can be used.

As for all other nodes, the Python nodes can also be added via the context menu of the graphs. They can be found in the Scripting category under the name Python Scripting Node.

The script that is called when the node is executed can be edited by clicking the Python button on the node to open the editor.

Input and output variables#

Corresponding ports can be created to make parameters available to a Python node within the graph system or to pass them on.

This can be done by opening the context menu of the node with a right-click or by adding new elements in the corresponding tabs in the properties using the plus sign. The properties of the ports can then be found in the corresponding tabs under properties.

It is important to give the ports a meaningful name here, as this identifier can be used to access the port in the Python script. The type can be used to specify what type of data can be transferred.

The port is made accessible in the Python script via the name. To access the value of the port, the .value() function must be called on this novh. Please note that error messages may occur for unconnected ports when analysing the Python script.

A simple assignment using an equals sign (=) is sufficient for setting output values.

If a data model object is to be accepted and processed, do not use the value() function but the object() function on the port object in the script. This makes the data model object available with all its queries and function calls available in Python, but in a read-only version only for queries, not for manipulations. If the object is to be manipulated in order to be passed on in a modified version, a copy can be made at the beginning using the cobined call object().clone(). The copy created in this way can be manipulated and then used further in the graph process by assigning it to an outport.

Another special case is the handling of the data type “intelli::ByteArrayData”. This is possible in its reference and when assigning the output values like the standard parameters via value(). The special feature here is the wide range of possible uses. All Python objects that can be picked can also be exchanged between nodes in this data type.

Plotting with Matplotlib#

The Python interface in the Python nodes allows direct access to a Matplotlib backend. If a Matplotlib plot is defined in a Python script of a node, a call to the function plt.show() is sufficient to generate the plot and store it in the system. If the property Plot enabled is true in the properties of the node, the plot is displayed directly on the node.