Scripting in Composite

Scripts can be powerful tools for eliminating the need to perform repetitive, tedious, and time-consuming tasks manually, thereby improving the efficiency of a facility. For example you can use scripts to manage projects, import media, perform rendering, etc.

Composite ships with a number of sample scripts for performing common tasks. These sample scripts are located in the resources/scripts/examples subfolder of the Composite installation directory.

Note: Example Python scripts are provided with no guarantee of effectiveness or efficiency.

There are also scripts that Composite itself invokes to perform some of its tasks (archiving, rendering, pre-comp import, etc) in the resources/scripts subfolder of the Composite installation directory. You may find these scripts helpful both as examples and as starting points for your own scripts.

In some cases the script command that Composite launches to accomplish a given task is specified in the project preferences. For example, the "Render Actions" tab in the project preferences contains the "Render Executable" setting that specifies the Python command line executed each time you render a composition in Composite. By default, that command line launches the "render.py" script. You can edit the command line to launch a different script or change the "render.py" script (located in "resources/scripts") to modify the default rendering behavior; like performing post-render tasks for example.

How To Execute a Composite Python Script

To successfully run a Python script that makes use of the Composite Python API (or more specifically, a script that imports Composite Python modules), it is important to run it in the right environment, for the Python interpreter to find the Composite Python modules and libraries, and for the Composite code to execute properly afterwards.

The Composite Python modules are located in the following directory (where <INSTALL_DIR> refers to the path of the Composite installation directory):

On Windows:

 <INSTALL_DIR>/python/lib/site-packages/autodesk_toxik

On Linux:

 <INSTALL_DIR>/lib/python2.6/site-packages/autodesk_toxik

On Mac OS:

 <INSTALL_DIR>/Contents/Frameworks/Python.framework/Versions/Current/lib/python2.6/site-packages/autodesk_toxik

There are two contexts in which a script can be run. First, in the Composite embedded Python interpreter, i.e. within the Composite process ("composite.exe" executable). And secondly, in an external Python interpreter, i.e. within a Python process, typically from a shell ("python.exe" executable).

Setting Up The Environment

Embedded

In the case of the embedded interpreter, the environment is already set up by Composite for a Python script to run properly.

External

Environment Variables: In the case of a script ran in an external Python interpreter, the shell from which the Composite Python script is invoked must have the following environment variables set (except on Mac OS which doesn't require any):
On all operating systems (except Mac OS):
```
 DL_INSTALL_DIR = <INSTALL_DIR>
```
On Windows:
```
 PYTHONHOME = <INSTALL_DIR>/python
 PATH = <INSTALL_DIR>/program;<INSTALL_DIR>/plugins
```
On Linux:
```
 PYTHONHOME = <INSTALL_DIR>
 LD_LIBRARY_PATH = <INSTALL_DIR>/lib:<INSTALL_DIR>/plugins:<INSTALL_DIR>/lib/python2.5/site-packages/autodesk_toxik/libs
```
Automatic Setup: The following procedures automatically set up the environment required to run a Composite Python script from a shell:
On Windows, launch a "Composite Command Prompt":
```
 Windows Start menu > Programs > Autodesk > Autodesk Composite 2014 > Composite Command Prompt
```
On Linux, source the "composite-env" shell script:
```
 From csh:  source <INSTALL_DIR>/bin/composite-env.csh
 From bash: source <INSTALL_DIR>/bin/composite-env.sh
```
On Mac OS, no environment variables are required, so there's nothing to do prior to running a Composite Python script from a shell.

Running a Script

Embedded

To run a Python script in the Composite embedded Python interpreter do the following steps:

Locate the script in a Composite "File Browser" view ("Ctrl-I" to bring up a floating browser for example). Note that in order for Composite to recognize a file as a Python script, it must have the ".py" extension.
Right-click on the script.
To run the script with no parameter choose "Run".
To run the script with parameters choose "Run with Parameters" and type in the script arguments as you would in a shell.

External

To run a Composite Python script, it is strongly recommended to use the Python distribution shipped with Composite (deployed under the Composite installation directory). Running a Composite Python script with any other Python distribution might not work properly and is very likely to result in a crash.

On Windows:

 <INSTALL_DIR>/program/python.exe myScript.py

On Linux:

 <INSTALL_DIR>/bin/python myScript.py

On Mac OS:

 <INSTALL_DIR>/Contents/Frameworks/Python.framework/Versions/Current/bin/python myScript.py

Scripted Actions

Custom actions can be implemented as Python scripts that can be invoked from the UI in the same way as native Composite actions.

Action scripts can be located anywhere on the local file system or on the network. Two environment variables (and toxik.ini options) control the loading and searching of action scripts:

DL_SCRIPTED_ACTIONS_LOAD_ON_STARTUP (toxik::scripting::scriptedActionsLoadOnStartup):
Set to 1 or 0 to control whether to load and register the scripted actions during the Composite startup.

The default behavior is to register action scripts on startup.

Action scripts can be loaded (or reloaded) at any time through the (Re)Load Scripts entry of the Scripts top menu.
DL_SCRIPTED_ACTIONS_PATH (toxik::scripting::scriptedActionsPath):
Search path for action scripts; a list of directory paths separated by the character conventionally used by the operating system to separate search path components (":" on Linux and Mac OS, ";" on Windows).

By default, the search path is empty, but the following directory of the Composite installation is always searched for action scripts: resources/scripts/actions.

Each path in the specified list is searched recursively for Python script files based on their extensions (py, pyw, pyc and pyo). If a Python script has multiple file versions only one of them is picked up (optimized, compiled and source in that order of precedence). Symbolic links on directories are followed.

The procedure that finds the action scripts is actually a Python script itself; resources/scripts/findScriptedActions.py, which can be customized by modifying the getScriptFilePaths function to return the proper list of script paths.

Simple Action Script

The simplest action script is a normal Python script with no special API. Such an action script will only appear in the Scripts top toolbar menu and is named after the Python file without its extension. Also, such a scripted action will be available to the user regardless of the current state of the Composite interactive application.

It is important however that the action script does not execute its action on import, otherwise the action will be executed upon registration of the script. Also, it is recommended that the code ran on import be a light as possible. In particular, heavy Python modules on which the script depends should only be imported when they are actually needed.

In practice, the action execution code and module imports should only be run if the name of the interpreter's main module is equal to "__main__" as described in the Python documentation:

Consequently, the basic structure of an action script should look like:

 if __name__ == "__main__":
   import someModules
   excuteAction()

Advanced Action Script

To get control over the context in which a scripted action should be available to the user and where it should appear in the Composite UI, the script must implement a special API that Composite will query upon its registration.

First of all, the script should define a "getActions" global function which takes no parameter and returns a list of arbitrary Python objects each defining an action that the script implements. This allows for a single Python script to define many actions (most likely a set of related actions that may share some base code).

Secondly, each action object returned by "getActions" must support the following interface; that is, define the following methods, some of which are optional.

str getName()
Returns the name of the action as it will show in the Composite UI menus. This method is optional; the default action name is built from the script file name joined with the name of the action class.
bool isGlobal()
Returns a boolean indicating whether the scripted action shows up in the Scripts top toolbar menu. This method is optional; the default behavior is to add the action to the top menu if it's not specified to appear anywhere else.
bool isOnNode()
Returns a boolean indicating whether the scripted action shows up in the right-click menu of a composition node (anywhere in the application; schematic, composition browser, animation view, etc). This method is optional; by default a scripted action is not available on a node.
bool isInBrowser()
Returns a boolean indicating whether the scripted action shows up in the right-click menu of a Composite browser. This method is optional; by default a scripted action is not available in the browser.
bool isApplicable()
Returns a boolean indicating whether the scripted action is applicable in the current state of the application (for example, whether the selected node is of a certain tool type or whether the selected file has the expected extension).

The Workspace class from the ui module can be used to access the state of the Composite UI. If the action is not applicable, it will simply not be available in the Composite menu.

This method is optional; by default a scripted action is considered to be always applicable. Note that it is actually better not to define this method than having it simply return True, since Composite won't have to query the Python script to determine whether the action is applicable which makes it significantly faster.
list getSupportedFileExtensions()
This optional method returns a list of file extensions (without the dot) that are supported by the scripted action.

This method is only invoked for scripted actions present in Composite browsers (see isInBrowser method) and when defined, the current Composite browser selection is first tested against the returned extensions before invoking the isApplicable method. This is meant to avoid subsequent script invocations on unsupported file extensions.

The scripted action is considered to be potentially applicable when at least one of the selected files has a supported extension which implies that the action must be ready to handle unsupported files in its perform method if the isApplicable method is not defined.

Note that if an empty list is returned, Composite acts as if the method did not exist.
str getSupportedBrowserScheme()
This optional method returns the sole browser scheme for which the scripted action applies. See ui.Workspace.getBrowserScheme for a list of possible scheme string values.

This method is only invoked for scripted actions present in Composite browsers (see isInBrowser method) and when defined, the current Composite browser scheme is first tested against the returned value before invoking the isApplicable method. This is meant to avoid subsequent script invocations on unsupported browser schemes.

Note that if the empty string is returned, Composite acts as if the method did not exist.
perform()
Performs the action itself. The Workspace class from the ui module can be used to access the state of the Composite UI (currently selected node of file for example). This method is mandatory and must be defined.

The following example is an action script that adds a sphere layer to a Reaction tool node and sets its radius to a value entered by the user in a pop-up dialog. Since the isOnNode method returns True and the isApplicable method returns True only when the target node is a Reaction node, the "Add Sphere" action will only show up in the schematic right-click menu if the selected node is a Reaction tool.

Note that the class name "AddSphereAction" is totally arbitrary; the only hard requirements are for the method names and return types to respect the interface expected from an object returned by the getActions global function:

 class AddSphereAction(object):

   def getName(self):
     return "Add Sphere"

   def isOnNode(self):
     return True

   def isApplicable(self):
     from autodesk_toxik import ui, graph
     node = ui.Workspace.getTargetNode()
     return (node is not None and
             isinstance(node, graph.GroupNode) and
             node.getTool().getName() == "Reaction")

   def perform(self):
     from autodesk_toxik import ui, reaction
     values = ui.showSimpleDialog(
       "Sphere", [("TextField","rad","Radius","100")], 150)
     try:
       radius = int(values["rad"])
     except:
       radius = 100
     sLayer, sMat, sGeom = reaction.addLayer(
       ui.Workspace.getTargetNode(), "My Sphere", geomType="Sphere")
     sGeom["Radius"].setValue(radius)

 def getActions():
   return [AddSphereAction()]

For an example of a scripted action that acts on files selected in the Composite browser, take a look the script that implements the Import All Channels action, which imports all channels of an OpenEXR file sequence into multiple import nodes aggregated together by a group node with an output for each channel view: resources/scripts/actions/multiChannelImport.py under the Composite installation directory.

Submodules

admin: Administration module.
debug: Debugging utility module.
graph: Graph module.
init: Initialization module.
libs
media: Media module.
pimgr: Plug-in manager module.
precomp: Module for precomp import related functionality.
precompmodule: Defines a wrapper around a precomp module: the PrecompModule class.
reaction: This module provides convenient functions to modify nodes inside a Reaction node.
relocationbrowser: Relocation browser module.
tools: The tools module is the placeholder for classes that give access to the Composite tools, i.e.
txxml: Xml module.
ui: User Interface module.
utils
- utils.interp: The interp module contains utility functions related to the Python interpreter itself: starting a script in an existing interpreter, loading a specific file as a module, frame hack utilities, that sort of things.
- utils.utils: Common utilities.
wiretap: Wiretap module.