silhouette-2024.5 : Command-Line
Command-Line
Silhouette on the command-line allows you to execute projects with a variety of commands to control the rendering process. Further customization is accomplished via scripting as much of the Silhouette object model is exposed to the Python scripting language.
The Silhouette command-line program is named sfxcmd and is located in the following locations depending on your operating system.
Linux: Location determined by user at installation
Macintosh: /Applications/SilhouetteFX/Silhouette[version]/Silhouette.app/Contents/MacOS
Windows: C:\Program Files\SilhouetteFX\Silhouette[version]
To run the Silhouette command-line program, use the following commands in a shell window:
Mac: ./sfxcmd
Windows: .\sfxcmd.exe
Linux: ./sfxcmd
Go to the Command-Line tutorial to see how it works.
General Options
Command-line options are of the form: –option value, where value may be optional. Required arguments are in pointy brackets (< >) and optional arguments are in brackets ([ ]). If the value must be from a list of possible values, the available values are separated by |.
The basic form of the sfxcmd argument is: sfxcmd <projectname> [options]
where options are from the list below. By default, the project is rendered using the settings in the project unless changed by command-line options. Rendering can be disabled with the –render 0 option (see below). Certain options, such as format conversion, will implicitly disable rendering as well. The project name should either be the first or last command and if not, should be preceded by the -project flag.
-action <actionName>
Run the specified Action after the project is loaded, where actionName is an action class name for one of the actions found in Silhouette/resources/scripts/actions. When –action is used, rendering is implicitly disabled, unless the –render 1 option is also used. Any rendering done by the action itself is not disabled.
-all
Renders all output nodes in the active session.
-args <argument_list>
argument_list is a comma-separated list of arguments to pass as sys.argv to the script.
-info[project|session|node|outputs]
Print information about the overall project, the active session, active node or active session rendering information. Enabling this option loads the info.py script in the Silhouette scripts directory, and calls the appropriate function to dump basic information. This file can be modified by the user to alter how the information is presented. If just –info is used, the default is to display project information. Multiple options can be supplied, separated by commas, to print multiple types of information. For instance, –info session,outputs will print session and rendering information. When –info is used, rendering is implicitly disabled, unless the –render 1 option is also used.
The information displayed by –info can be customized by editing the info.py Python script located in Silhouette/resources/scripts.
-log
Enable log messages. For example, use –log to display module load messages and other non-critical informational messages.
-node <name>
Target the specified output node in the active session for output. By default, the selected output node is used. When specifying a particular node, the node label must be used and not the node type (i.e. Roto1), because there may be more than one. To print a list of nodes in the active session, use the –info session option.
-no_launcher
Prevents the launcher from appearing when Silhouette starts up without a project.
-no_modules
Modules are prevented from loading.
-no_splash
Prevents the splash screen from appearing when Silhouette starts up.
-open_project
Opens the project browser on launch.
-options <options file>
Load the options file and treat each line of the file as a command-line option. For instance, instead of writing this:
sfxcmd project.sfx –log –info project
You can write this:
sfxcmd project.sfx –options options.txt
Where options.txt contains:
–log
–info project
Note: Lines that start with # in the options file will be ignored, so you can use # to add comments.
-project <name>
Allows the project name to be positioned anywhere in the command chain instead of only at the beginning or end.
-render <0|1>
Rendering can be disabled by using –render 0. Use this if you only want to print information about the project or run a script that does other things with the project. Rendering is enabled by default if a project is specified.
Note that when –info or –action are used, –render 0 is implicitly set unless the –render 1 option is also set.
-script <scriptfile>
Run the specified Python script after the project is loaded. The script has access to the active project, session, and node, as specified by the –session and –node options. Scripts can walk the object model, manipulate the object state such as visibility, and print information, limited only by the Silhouette scripting API.
-script_after_args <scriptfile>
-script loads the project, runs the script and then does other command-line processing. However, this doesn’t help when the script itself is tasked with rendering. With the -script_after_args command-line flag, the script is executed after argument processing.
-session <name>
Make the specified session active in the project. This is only useful if the project contains more than one session. To print a list of sessions in the project, use the –info option.
-version
Print the sfxcmd version.
Rendering options
-write <0|1>
Disable frame writing by using –write 0. This is useful for doing test runs to verify that options are set properly.
-range <all|work|start#-end#x#>
Specifies the range of frames to render. A specific range is set by passing two numbers. A step factor can be introduced by using x# after the range. Some examples are:
range 1-10 renders frames 1, 2, 3, 4, 5, 6, 7, 8, 9, and 10.
range 1-10x2 renders frames 1, 3, 5, 7, and 9.
range 3 renders frame 3.
Multiple range arguments can be used to specify multiple ranges, for instance –range 1-50x1 –range 51-60x2 –range 60-100x3. You can also use commas to separate ranges in a single range option.
Frames are in the range of the session, and do not necessarily start at 1. If your session starts at frame 4000, to render the first 50 frames of the session, use –range 4000-4049.
-f
Same as range.
-step <number>
Specifies the number to add to get to the next frame. The default is 1. Note that step will override whatever step factor is used in range or f.
-start <number>
Use –start to override the starting frame number of the output frames. For example, if your session starts at 4000 and you want to render 50 frames, but you want the generated frame files to start at 1, use –range 4000-4049 –start 1.
-depth <8|float16|float32>
Sets the render depth.
-region <session,roi,dod>
Determines the rendered image size.
-roi <0|1>
Determines whether the region set in the ROI (Region of Interest) is used.
-resolution <full|half|third|quarter>
Override the output resolution to full resolution, half resolution, third resolution, quarter resolution.
Note: Half resolution is width/2*height/2, third resolution is width/3*height/3, and quarter resolution is width/4*height/4.
-fields <none|interlace>
Sets the field handling to one of the supported options. The two letter options assume 3:2 handling.
-dominance <even|odd>
Sets the field dominance when field handling is enabled.
-nogui
For Linux systems without X-Windows installed, –nogui allows Silhouette to not use X-Windows.
-threads
You can override the number of multi-processing threads Silhouette uses with –threads <n>.
-validate <0|1>
When enabled, rendering is aborted if a Paint node’s data can’t be found.