Function Calling

Overview

This is a set of API endpoints allowing Python scripts to be executed in the current Designer session. The aim of this functionality is to allow users to automate highly repetitive tasks when creating stage objects and remove boiler plate tasks from the GUI.

This endpoint also introduces the support of user-defined python modules for Designer. Modules in this context are Python packages or modules that can be imported to extend the functionality of later script executions.

This API has not been optimised for performance related tasks such as executing on every frame or providing telemetry metrics, users are encouraged to use other tools such as the Live update API for these tasks.

Executing scripts

To execute a Python command or script the api/session/python/execute endpoint can be used. Commands executed through this endpoint are completely ephemeral and any class, function or variables definitions will be lost after the execution completes.

This endpoint allows for the following use cases:

“One-off” scripts which execute a few lines of code to do a repetitive task.
Support scripts which execute in the context of a pre-registered modules to call functions as a part of a larger system.

Note that calling this endpoint too frequently or during a show is not a supported workflow - this is intended for show programming tasks, not during production.

The request body is structured as follows:

{
  "moduleName": "string",
  "script": "string"
}

moduleName - This string refers to the registered module the script will be executed in. For one-off scripts, this field can be omitted or left blank.

script - This should contain the Python code to be executed. This needs to be valid Python code, using the correct indentation.

The response body is structured as follows:

{
  "status": {
    "code": 0,
    "message": "string",
    "details": [
      {
        "type_url": "string",
        "value": "string"
      }
    ]
  },
  "d3Log": "string",
  "pythonLog": "string",
  "returnValue": "string"
}

An example of using the execute endpoint is shown below using python:

import requests

response = requests.post(
    url="http://localhost/api/session/python/execute", 
    json={
        "script": "print('Hello Disguise Designer!')"
    }
)

print(response.json())

The response from this statement would look as follows:

{
    "status": {
        "code": 0,
        "message": "",
        "details": []
    },
    "d3Log": "Python script took 1.3439ms\n",
    "pythonLog": "",
    "returnValue": "'\"Hello Disguise Designer!\"'"
}

Code execution environment

The code in an execute request is executed in the context of a function body. This approach allows for some additional safety measures and allows values to be returned using the return statement.

However some statements are not valid in the context of a function body, such as from [package] import *. This is due to limitations in standard Python syntax. If the user has more complex scripting requirements, they should consider using the module registration API.

If moduleName is supplied, all global variables within that module are accessible to the execute call as if they were accessed from a function within that module.

If moduleName is not supplied, the execution will use a default environment. In this case some additional utility functions are available to provide access to useful values and functions.

Returning values

As mentioned above it is possible to return values from the Python endpoint. This can simply be done by adding a return statement to the end of the script. These return values will be converted to json using the Python json package, this means all objects that are returned must be able to be serialised to json.

An example of returning a value is shown below

import requests

response = requests.post(
    url="http://localhost/api/session/python/execute", 
    json={
        "script": "return {'a': [], 'b':2}"
    }
)

print(response.json())

Gives the response:

{
    "status": {
        "code": 0,
        "message": "",
        "details": []
    },
    "d3Log": "Python script took 3.1447ms\n",
    "pythonLog": "",
    "returnValue": "{\"a\": [], \"b\": 2}"
}

Logging

As always logging is important but it is even more crucial when running commands remotely. To help with this two logging fields are provided in the response.

d3Log - The D3 log field captures the console log for the time the Python script is executing, recording any output generated by running Python command, including the time taken to execute the Python command. As this captures the Designer console output it is possible other threads may write to this output during this period, and therefore additional, irrelevant output may appear meaning some interpretation of this log is required.
pythonLog - This output field is the pure Python output, recording any print statements or warnings occurring during the execution of the script. This output will also appear in the d3Log field however it maybe mixed with other application output.

Run time and timeouts

The execution of Python scripts through the execute occurs on the main application thread and will therefore pause the application whilst the script executes. To avoid cases where scripts run indefinitely or run longer than expected a timeout interrupt has been implemented. The length of this timeout is dictated by the experimental optionpythonApiExecutionTimeout which can be set through the D3Manager window. When a script exceeds this value, a KeyboardInterrupt is executed and the Python execution stops and returns a TimeoutError in the response.

The `d3` package

The d3 package provides access to many Designer object types and resources as well the current session state. A full breakdown of the different classes and function can be found here. There are many types available and to simplify execution scripts, these types are preloaded, meaning there is no need to add an import d3 statement to scripts. Some elements of the d3 package are not available through the plugin system, such as GUI elements, to prevent stability issues.

Writing out scripts

Scripts sent to the execute endpoint can be written out using the experimental pythonApiOutputRequestsToProject flag through D3Manager. When this is set to True all scripts sent to the execute endpoint will be written to the project internal\\PythonApiHistory directory. This can be useful for debugging issues as well as keeping a record of the scripts executed in a project. However this should be used with caution as executing many requests will cause the project size to grow quickly.

Python 2.7

Designer currently utilises Python 2.7, consequently some newer commands or packages maybe unavailable. Users are encouraged where possible to use syntax and methods that are compatible with both Python 2.7 and Python 3.

Undo

Undo is supported when executing scripts through the execute endpoint.

Plugin naming

As plugins are imported as Python modules, plugin names need to follow the same naming conventions:

Plugin names cannot be empty
Plugin names include alphanumeric and . - _ characters
Plugin names cannot start or end with . - or _

Registering Python modules

When creating more complex scripts, it is useful to be able to add additional Python classes and functions to the environment to avoid re-parsing code in the execute endpoint. These Python objects can be parsed to Designer before executing as Python modules to create Designer plugins using the registermodule endpoint.

A request to the registermodule endpoint takes the following structure:

{
  "moduleName": "string",
  "contents": "string",
}

moduleName - This is the name the plugin will be referred to in Python. This string will need to parsed in the execute request in the moduleName field in order to load the plugin.

contents - This is the contents of the Python module in a single string. Classes, functions and variables can be defined here to be used in the execute.

The response is structured as follows:

{
  "status": {
    "code": 0,
    "message": "string",
    "details": [
      {
        "type_url": "string",
        "value": "string"
      }
    ]
  }
}

An example of registering a Python module as a plugin using the registermodule endpoint is shown below:

import requests

response = requests.post(
    url="http://localhost/api/session/python/registermodule", 
    json={
        "moduleName": "screen_utils",
        "contents": """
def createLEDScreen():
    # Create a new LED screen resource
    screen = resourceManager.loadOrCreate(
        'objects/ledscreen/ledscreen_1.apx',
        LedScreen
    )

    # Set the physical size in meters
    screen.scale = Vec(1, 2, 0)

    # Set the resolution in pixels
    screen.resolution = Vec(1920, 1080)

    # Center the screen at origin
    screen.offset = Vec(0, 0, 0)

    return screen
"""
    }
)

print(response.json())

Giving the following response:

{
    "status": {
        "code": 0,
        "message": "",
        "details": []
    }
}

If errors are experienced whilst compiling the given module errors will be given in the message field.

Using a registered Python plugin in the `execute`

To use the above plugin in the execute, the plugin name must be passed into the moduleName field, the request would look as follows:

import requests

response = requests.post(
    url="http://localhost/api/session/python/execute", 
    json={
        "moduleName": "screen_utils",
        "script": "createLEDScreen()"
    }
)

print(response.json())

Reusing Python plugins

Registering a Python plugin adds the defined module to the internal Designer Python system, meaning these modules can be used inside other Python plugin modules. Modules when registered are prepended with user_name_ to protect core modules, to use a registered module in another module, this would need to be added to the module name.

Here’s an example of creating another plugin module:

import requests

response = requests.post(
    url="http://localhost/api/session/python/registermodule", 
    json={
        "moduleName": "serialise_helpers",
        "contents": """
def serialiseLED(ledScreen):
    return {'name':ledScreen.path , 'uid': ledScreen.uid}
"""
    }
)

print(response.json())

This could then be used when executing in another module namespace by importing the module:

import requests

response = requests.post(
    url="http://localhost/api/session/python/execute", 
    json={
        "moduleName": "screen_utils",
        "script": """
from user_module_serialise_helpers import serialiseLED
return serialiseLED(createLEDScreen())
"""
    }
)

print(response.json())

Loading plugins on startup

Another option for loading plugins is to have the plugins registered when the Designer application is started. This can be done by adding the plugins to the project {project_root}/plugins directory. These will be loaded using the following rules:

Any directory within the plugins directory with a __init__.py will be loaded as a plugin using the directory name as plugin name.
Any “.py” files within the plugins directory will be loaded using the file name as the plugin name.

Search

Designer Plugins