Macros are a way of controlling the tracking tree using a Python script. This can be used, for example, to automate the creation, connection and processing of nodes. Note that macros are separate from node scripting, the former being a way of modifying the structure of the tree and the latter being a way of modifying the data flowing through the tree.
We provide two example macro scripts which can be used as a starting point for customisation. 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. Note that this macro can only be executed when a single node is selected in the tree and that node is a Clip Input node.
User-written macro scripts can be placed in a
macros sub folder in the user's application preferences directory
$HOME/.pftrack/macros if they are applicable to just one user; or in a
macros sub-directory of the system directory
/Applications/The Pixel Farm/macros if they are applicable to everyone running the application. These directories are scanned on application startup.
Macros can either be executed in the GUI with the various scripts being listed in the M pulldown menu at the bottom right of the tree, or executed from the command line without invoking the GUI for automated processing, eg:
"C:\Program Files\The Pixel Farm\PFManager\PFManager.exe" pftrack 2018.08.28 -load_project /path/prj/prj.pfmp -run_macro /path/macro.py -exit
2018.08.28 is one of the installed versions of PFTrack.
A script starts with the following line to import the macro functionality:
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
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.
Minimal error handling is performed. For example if you try creating a node of unknown type an error message is popped up and execution of the script ceases.
In the 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
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 2.6).
If your macro wishes to utilise additional modules you can either
PIXELFARM_KEEP_PYTHONPATH environment variables to prevent PFTrack setting them and then ensure your local Python installation is picked up and useable.