Command Line Usage
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
Environment variables
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
environment variable 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
where command1
and 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.
Terminal output
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
runs.
Project commands
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
The -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\
The -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.
Loading media
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
The -load_clip
command will create a new Clip Input node and load the clip specified as the command argument. Similarly, the -load_photos
and -load_spherical
commands will create either a Photo Input or Spherical Input node.
For example:
"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.
Running macros
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!
Miscellaneous commands
The following are miscellaneous commands:
-dont_save_settings
-retry
-remote
-command_port number
-exit
The -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.
The -retry
command is described in the Running multiple
instances of PFTrack section.
The -remote
and -command_port
commands are
described in the Remote control section.
The -exit
command is described in the GUI or no GUI
section.
Remote control
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:
-command_port PORT_NUMBER
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
with the -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 command1
and
command2
.
FBX is a registered trademarks of Autodesk Inc. in the USA and other countries.
Nuke is a trademark of The Foundry Visionmongers Ltd.