PFTrack Documentation

Please note: Macros and the macro API are only available to Enterprise customers.

Macros are a way of interacting with nodes on a workpage using a Python script. As an example, they can be used to automate the creation, connection and processing of nodes.

Macros are different from Python Nodes in that they can only modify the structure of the tree or execute commands to trigger operations available in PFTrack's node editors (such as initiating a camera solve). Python Nodes can be used to create custom node behaviour and modify the low-level data flowing through the node.

Finally, Compound Nodes can also be used to group multiple nodes into a single entity and create simple customization GUI elements.

Example scripts

We provide two example macro scripts which can be used as a starting point for customization. These example scripts are:

- Track and Solve - this macro adds an Auto Track and Camera Solver node to the currently selected Clip Input node, and then runs the tracking and solver.

- Process All - this macro processes all Auto Track and Camera Solver nodes present on the workpage.

- PySide2 Dialog - this macro shows how to use PySide2 to create Qt forms in your macros. It creates a form listing all nodes in your tree, and clicking on a node will adjust the tree viewport to display the node and open the node editor.

User-created macro scripts can be placed in a macros sub folder in the user's documents folder at macros, or in the macros sub-directory where the application is installed. These folders are scanned on application startup. A custom folder location can also be specified in the Preferences window.

Note: the Track and Solve macro can only be executed when a single Clip Input node is selected on the workpage.

Executing macros

The macros pulldown menu below the Tree View

Macros can either be executed in the GUI with the various scripts being listed in the pulldown menu (1) at the bottom right of the Workpage, or executed from the command line without invoking the GUI for automated processing:

 -load_project /path/to/projectFolder -run_macro /path/to/macro.py -exit

Further information about the command-line processing operations available in PFTrack are provides in the Command Line Usage section.

Script structure

A script starts with the following line to import the macro module called pfpym:

import pfpym

There must then be a pfMacroName function present which defines the name of the macro as it appears in the application:

def pfMacroName():
    return 'Build tree'

Optionally there may then be pfMacroNumSelectedNodes and pfMacroSelectedNodesType functions to define when the macro can be executed. In this following example a single clip node must be selected in the tree for the macro to be available:

def pfMacroNumSelectedNodes():
    return 1                

def pfMacroSelectedNodesType():
    return 'Clip Input'

Finally there is a main function which must be present and performs the work.

def main(tree):
    # macro functionality here

The argument to this function is a Python object, of class PyTree, for controlling the tree.

The macro can be hidden from appearing in the interface by defining:

def pfHiddenMacro():
    return 1

Such a macro though can be executed from the command line.

PySide2

PFTrack comes bundled with the PySide2 and shiboken2 Qt python modules (Enterprise only). These can be used to create more complex dialogs and execute additional tools to assist with pipeline and workflow integration.

The PySide2 modules can be imported using code similar to this:

import PySide2
from PySide2 import PySide2.QtWidgets
from PySide2.QtWidgets import QDialog

dlg = QDialog()
dlg.exec()

This will create an empty dialog in the same singleton QApplication that PFTrack is using, run the dialog in the event loop and wait for it to be closed.

Note: If you wish the user to interact with your widgets whilst the macro is running, they should be contained inside a QDialog or similar and ran using the exec() command. This command will block the main PFTrack event loop until the dialog is closed.

Error handling

Minimal error handling is performed. For example if you try creating a node of unknown type an error message is displayed, and execution of the script ceases.

Errors and thrown exceptions will appear in the application log, although it is also recommended to check your terminal window or command prompt for complete error information.

Loading additional site-packages

If you wish to load additional Python3.10 compatible site packages, you can set the PIXELFARM_PYTHON_SITEPACKAGES environment variable to the location of your site-packages folder before launching PFTrack.

This will call the Python function site.addsitedir() after Python is initialised.

Note: Linux users should also set their LD_LIBRARY_PATH environment variable to ensure PFTrack is able to locate any additional dynamic loaded libraries that may be needed by the site-packages.

Using a local Python installation

PFTrack distributed with a Python 3.10 installation and sets the PYTHONPATH and PYTHONHOME environment variables to its internal install location when launching.

If you wish to use a custom Python installation instead of the one distributed with PFTrack, you can set the PIXELFARM_KEEP_PYTHONPATH and/or PIXELFARM_KEEP_PYTHONHOME environment variables to any value to prevent PFTrack setting this itself, thereby ensuring your local Python 3.10 installation is used instead. When doing this, you will need to make sure your PYTHONPATH environment variable is set correctly to point to required locations in your local Python installation folder.

If you do not wish to set the entire PYTHONPATH yourself, you can also use PIXELFARM_APPEND_PYTHONPATH instead of PIXELFARM_KEEP_PYTHONPATH. Using this variable will append your specified path(s) to PFTrack's existing PYTHONPATH.

Note: Windows users should use a semicolon ; to separate multiple directories whilst setting paths, and Linux or macOS users should use a colon :

Setting environment variables

Environment variables can be difficult to specify on certain operating systems, and to help with this environment variables can be read from an environment.txt file located either in the directory where the application is installed (so that it applies to all users) or in a specific user's documents directory:

environment.txt

For example:

PYTHONPATH=/usr/lib64/python3.10
PIXELFARM_KEEP_PYTHONPATH=1

Nomenclature

In the following API documentation, if a parameter is optional it is enclosed in square brackets.

← CLIP MODULE API

TREE API (PYTREE CLASS) →

Python Macro API