Skip to content

Python Scripting API - Basic Usage

Warning

Use of the API is an advanced feature and should only be used by users with a working knowledge of both Tribli and the Python scripting language. In rare cases, use of the API may lead to corruption of the project data, so be sure to save any work prior to use. Operations completed through the scripting API cannot be undone.

Note

The Tribli scripting API was completely rewritten in Tribli version 5.5.0. As such, this documentation is applicable only to Tribli versions 5.5.0 and later.

Tribli provides a high level Python scripting API that enables users to control and automate some of Tribli's functionality via an in-built Python interpreter. The Python interpreter can be launched from the file menu.

The tribli application can be accessed via the app global variable made available within the scripting environment. The app variable provides access to an app_proxy instance that provides attributes and methods that can be used to interface with the current Tribli session.

Also made available as global variables within the scripting environment are current_level and selected. current_level provides access to the level_proxy instance representing the currently active level within the Tribli user interface. selected provides a list of objects representing the currently selected objects within the Tribli user interface.

Basic Usage

Tribli ships with a built-in Python interpreter that can be launched via the file menu. As of Tribli 5.5.0, Tribli ships with Python 3.10, though this will be upgraded in future.

The scripting dialog provides a rudimentary script editor than allows the user to save or load scripts as well as a python interpreter output window. Python Scripting Dialog

Once loaded into the code editor window, select the execute button to run the script. If any exceptions are encountered, they will be displayed in the console output, otherwise "Script Executed Successfully!" will be displayed if the script has been executed without any unhandled exceptions.

Available Modules

All Python base library modules are available for import within the scripting environment via the import keyword.

As the Python interpreter is built-in, it is not possible to install custom python packages into the scripting environment. Tribli does however ship with several pre-installed external libraries which are useful for general engineering tasks. Currently, these packages include:

  • ezdxf - For importing and exporting DXF drawings files
  • openpyxl - For importing and exporting Microsoft Excel (.xlsx) files.
  • shapely - A python module providing access to the open-source geometry library, GEOS. All object geometries must be passed to and from Tribli as shapely objects.
  • numpy - Matrix manipulation in python
  • scipy.optimize - Provides numerical optimisation functions for python

External python scripts can only be imported into a Tribli API script if they are saved in the Tribli plugin directory at C:\Users\YOUR USERNAME\AppData\Roaming\Tribli\Plugins.

Geometric Entities

All object geometries must be passed to and from Tribli as shapely objects.

Note

As of Tribli versions 5.6.0, geometric entities passed to the Tribli API no longer need to be inverted about the Y axis.

API Call Timeout

To avoid unhandled exceptions or infinite loops in executed scripts causing Tribli to freeze indefinitely, a time limit is placed on the execution time of each API call. By default this is 30 seconds, but can be modified in the 'General' tab of the Tribli settings.

In some large models, complex operations such as tributary area or load calculation may take longer than 30 seconds, in which case the API timeout value will need to be increased in order to prevent Tribli from terminating the API connection prematurely.

Exiting Scripts

Tribli provides an additional built-in function end_script in the scripting environment that allows scripts to cleanly exit. This function should be called from within the script when script execution is to be stopped and should be used in lieu of other built-in python functions.

Plugin Support

Tribli includes a simple plugin system that allows user to execute scripts without starting up the script editor dialog. A list of available plugins can be found in the file menu.

Python scripts to be used as plugins must be saved in the plugin folder with a '.plg' file extension. '.plg' python scripts can be imported into regular python scripts or other plugin scripts use per the usual python syntax with the import keyword.