Macro API
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.
Note that macros are separate 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 Match 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 Match and Camera Solver nodes present on the workpage.
Note that the Track and Solve macro can only be executed when a single Clip Input node is selected on the workpage.
User-created macro scripts can be placed in a macros
sub folder in the user's documents folder at /Users/USERNAME/Documents/The Pixel Farm/PFTrack/macros
, or in a macros
sub-folder of the system folder /Applications/The Pixel Farm/macros
. These folders are scanned on application startup. A custom folder location can also be specified in the Preferences window.
Executing macros
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:
"C:\Program Files\The Pixel Farm\PFTrack\PFTrack.exe" -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.
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.
Nomenclature
In the following API documentation, if a parameter is optional it is enclosed in square brackets.
Importing Python modules
PFTrack is distributed with the standard Python modules and sets the PYTHONHOME
and PYTHONPATH
environment variables to its internal install location to ensure that it does not attempt to use any locally installed version of Python which maybe incompatible (PFTrack is based on Python version 3.7).
If your macro wishes to utilise additional modules you can set the PIXELFARM_KEEP_PYTHONHOME
and PIXELFARM_KEEP_PYTHONPATH
environment variables (to any value) to prevent PFTrack setting them, thereby ensuring your local Python installation is picked up and useable.
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:
/Users/USERNAME/Documents/The Pixel Farm/PFTrack/environment.txt