PFTrack has a set of command line arguments to script the building of projects, loading of media, and processing of macro scripts.
Running from the command line
PFTrack can be ran from the command line using the Windows Command Prompt tool.
To run PFTrack, enter a command such as:
"C:\Program Files\The Pixel Farm\PFTrack\PFTrack.exe" -help
Specifying command line arguments can be tricky on Windows and macOS, where launching the application from the Start Menu or Finder is more
common, rather than using a terminal command. To help with this situation, command line arguments can also be specified using the
PFTRACK_COMMAND_LINE_ARGS as well as on the command line itself.
Environment variables themselves can also be difficult to specify on certain operating systems, and to help with this they 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
The contents of this file should as follows:
PFTRACK_COMMAND_LINE_ARGS= -command1 -command2
command2 are commands to be executed when the application starts.
Note though without a terminal to observe any information or errors executing the command line arguments generate, specifying them like this can be of limited use. However, an important exception would be for specifying the command port to allow remote control of PFTrack which is described below.
List of commands
A full list of command line arguments can be found by running PFTrack from the terminal with the "-help" command, i.e.:
"C:\Program Files\The Pixel Farm\PFTrack\PFTrack.exe" -help
The terminal output from running "-help" is copied below for your reference:
Project: -create_project /path/to/project/projectName -load_project /path/to/project/projectName -set_default_import_path /path/to/media/ -set_default_export_path /path/to/exports/ -set_default_export_name exportName -set_default_export_format formatName -set_default_export_format formatName#version -save_project -close_project Media: -load_clip /path/to/footage.001.ext -load_photos /path/to/footage.001.jpg -load_spherical /path/to/footage.mov Processing: -run_macro /path/to/macro.py Miscellaneous: -dont_save_settings -retry -remote -command_port number -exit
GUI or no GUI
Command line arguments can be used to control whether PFTrack launches a GUI or not. Consider the following 2 instantiations of the application:
"C:\Program Files\The Pixel Farm\PFTrack\PFTrack.exe" -command1 -command2
"C:\Program Files\The Pixel Farm\PFTrack\PFTrack.exe" -command1 -command2 -exit
The first processes the two commands and starts up the GUI showing the results. The second processes the two commands and then exits without showing the GUI.
PFTrack writes information to the terminal in the normal course of it operations regardless of whether or not it launches a GUI or command line arguments are present. To help filter this background information from items pertinent to command line arguments the words INFO: or ERROR: proceed terminal output which relate to command line arguments - INFO: for general information, such as the confirmation of a successful command or processing progress, and ERROR: for a fatal error which stop further command line argument processing.
Running multiple instances of PFTrack
Only a single instance of PFTrack can run on a given machine at any one time. If you try to launch PFTrack from the command line while another copy is already running you will see this error message:
ERROR: already running
and the application will immediately exit. If you specify the
-retry command line argument then rather than immediately exiting
PFTrack will wait until the other running copy completes and then
The commands related to project handling are:
-create_project /path/to/project/projectName -load_project /path/to/project/projectName -set_default_import_path /path/to/media/ -set_default_export_path /path/to/exports/ -set_default_export_name exportName -set_default_export_format formatName -set_default_export_format formatName#version -save_project -close_project
-create_project command creates a new project at the named location. For example:
"C:\Program Files\The Pixel Farm\PFTrack\PFTrack.exe" -create_project C:\Projects\myProject
will create a project folder called myProject stored on disk at C:\Projects\
-load_project command will load an existing project from disk (Note that this command requires the name of the project directory to be given as the argument):
"C:\Program Files\The Pixel Farm\PFTrack\PFTrack.exe" -load_project C:\Projects\myProject
When creating or loading projects, the default import and export paths can also be specified on the command line. The following commands are available:
-set_default_import_path: This command adds a default path to the project which will be available in the File Browser allowing the project to be initialised to quickly locate the correct media files on disk.
-set_default_export_path: This command will set the default export path for the project to a specific directory. This is the default path which will be used when creating new Scene Export or Footage Export nodes.
-set_default_export_format: This command can be used to set the default export format for new Scene Export nodes. The
formatName must match the name of one of the exports available in the Scene Export node. For example:
-set_default_export_format "Nuke Python Script" -set_default_export_format "Autodesk FBX#2010" -set_default_export_format "Autodesk FBX (Ascii)#2019"
For Autodesk FBX, an additional version number can be added using the # separator to specify which version of FBX to use.
If project parameters have been updated, the
-save_project command can be used to ensure the project is saved. The
-close_project command can also be used to close the active project and return to the Project Manager.
Finally, if the
-exit command is present at the end of the command line arguments, PFTrack will quit after executing all other commands. If the
-exit command is not present, PFTrack will continue to run in GUI mode, allowing further interaction with the project.
The commands related to loading media are:
-load_clip /path/to/footage/footage.ext -load_photos /path/to/footage/footage.ext -load_spherical /path/to/footage/footage.ext
-load_clip command will create a new Clip Input node and load the clip specified as the command argument. Similarly, the
-load_spherical commands will create either a Photo Input or Spherical Input node.
"C:\Program Files\The Pixel Farm\PFTrack\PFTrack.exe" -create_project C:\Projects\myProject -load_clip C:\Footage\Shot1\clip.0001.exr
will first create a new project called myProject and then create a Clip Input node and attempt to load the media.
The two command line arguments to run Python macro scripts are:
-run_macro /path/to/macro.py -run_macro_force /path/to/macro.py
See the Macros and Python API chapter for more information. The
force variant ignores certain conditions that would normally prevent a macro from running, such as when the application is busy processing, and it should be used sparingly!
The following are miscellaneous commands:
-dont_save_settings -retry -remote -command_port number -exit
-dont_save_settings command prevents the settings file being updated. Amongst other things, the settings file holds the list of projects displayed in the Project Manager. This command is typically
used when you want to create a new temporary PFTrack project and don't
want that project appearing in the Project Manager.
-retry command is described in the Running multiple
instances of PFTrack section.
-command_port commands are
described in the Remote control section.
-exit command is described in the GUI or no GUI
PFTrack has the ability to execute commands sent to it from an external process, basically allowing you to remotely control the application.
To enable this feature PFTrack needs to be started with the command line argument:
to enable it for remote control operation and to listen for incoming commands on the port number specified.
Only one external process can connect to PFTrack on this port at any one time and the connection maybe refused if PFTrack is busy (typically when the application is processing rather than sitting idle).
Command are sent to PFTrack as a plain text string in the form of command line arguments separated with space-triple-dash-space, e.g.
-new_project /path/to/wherever -close_project
This scheme reduces any ambiguity is separating each command and allows for command parameters with dashes in. N.B. a trailing " --- " is needed to terminate the command set.
PFTrack will process these commands and transmit back the terminal output they generate.
Any number of individual commands can be concatenated into a single command set to be sent to the application in one go. However, the application will only process one set of commands at a time and will close the connection when the set of commands has been processed. You need to open a new connection to send additional commands.
A simple Python script is supplied in the
remote sub-directory of
where the application is installed which acts as a basic remote
control client to PFTrack. The Python script connects to PFTrack,
send a set of commands to it, and prints the received reply. The
commands and their parameters are read from the command line (the
script takes care of the space-triple-dash-space issue). See the
comments in that script for more information.
Alternatively you can use a second instance of PFTrack, started
-remote command, to remotely control an already
running instance. Start the second instance using something like:
-remote -command_port PORT_NUMBER -command1 -command2
to make the first instance run
FBX is a registered trademarks of Autodesk Inc. in the USA and other countries.
Nuke is a trademark of The Foundry Visionmongers Ltd.