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.
We provide two example macro scripts which can be used as a starting point for customization. These example scripts are:
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.
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.
A script starts with the following line to import the macro module called
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 displayed, and execution of the script ceases.
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
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_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