From The Foundry MODO SDK wiki
Revision as of 19:54, 15 May 2012 by Jangell (Talk | contribs) (Formatting)

Jump to: navigation, search

modo 302 introduced "'headless'" operation, allowing modo to act as a command line program with no graphical user interface.


Various command line switches are also used in this article. Many of these switches also work with the full GUI mode as well. You should be comfortable with the MS-DOS prompt in Windows and the Terminal in OS X to use headless mode. The MS-DOS prompt and Terminal will henceforth be referred to as the command line or console.


The headless mode still requires a normal modo license to operate, and will fail with a license not found error if none is present.

Config File

Console mode uses its own config file. For modo 501 on Windows, this is modo_cl501.cfg, while on OS X this would be com.luxology.modo_cl501.

Telnet vs. Headless

Telnet operates very similar to headless mode, except that telnet can also be used from the GUI. The way commands are sent to and output is received from modo is identical for both telnet and headless.

Headless Basics

Running Headless

Headless modo is a separate executable. On Windows, it is modo_cl.exe, and is run just like any other command line program through the MS-DOS prompt.


On OS X, modo_cl is inside the application bundle, and can be run from the Terminal.


After modo finishes stating up, you’ll be greeted with the following lines, which include a start message containing the build number, followed by a line showing the registered name associated with the license modo is using.

@start  modo [xxxxx]  Luxology LLC
John Smith

modo is now ready to start accepting commands. You can type any normal, non-UI command here and it will execute normally, with its results returned through stout.

Exiting Headless Mode

You can quit headless mode just like you can in GUI mode, by executing the app.quit command. You may also be able to use ctrl-C to immediately terminate modo, but using app.quit ensures a proper shutdown.


Changing the Prompt

By default, modo shows an greater than symbol (>) when it is read for you to enter commands. You can use the -prompt switch to set the prompt to any character sequence you’d like. The following replaces the standard prompt with the string ready: and a space.


After modo finishes starting up, you’ll see this:

@start  modo [xxxxx]  Luxology LLC
John Smith


Headless mode conveys information to the user by prefixing certain lines with special characters. As of modo 501, all lines will start with a prefix. These were further standardized in 601.

Prefix Description
> Prompt, indicating that you can enter more commands. The prompt can be replaced with a custom one via the -prompt: command line switch.
+ The last command executed successfully
- The last command returned an error
 : A result from a query. There is one result per line, with each line starting with a colon.
# A comment line output by modo, which can be ignored
 ! Output from the log system
@ System message

This is an example of a system message.

@start  modo [xxxxx]  Luxology LLC

This is an example of the prompt, a series of queried results, and a success message.

> query platformservice "" ?
: licensedto
: iseval
: expiresin
: serialnumber
: numlicenses
: appname
: appversion
: appbuild
: isheadless
: ostype
: osname
: osversion
: paths
: path.path
: importpaths
: isapp64bit
: alias
+ ok

Lines beginning with an exclamation point (!) are from the log system. The exclamation point is immediately followed by the name of the subsystem that issued the event wrapped in parentheses, followed by a space and the logged event itself. This output is otherwise identical to what is shown in the Event Log Viewport or the Feedback Viewport (for rolling messages). Log system output can be toggled with the Log.toConsole and Log.toConsoleRolling commands, and is disabled by default. See Logging to the Console for more information.

Executing and Querying Commands

Commands are executed just like they are from the full Command History Viewport of the modo GUI. You can think of the headless prompt as being like the Command History's Command Entry. This includes executing commands and scripts and querying. Results of command executions and queries go right to stdout and appear in the console.

From the Console

When you see the prompt, you can enter a new command to execute or query. The command syntax is exactly the same as it is from within modo. The formatting described above is about the only real difference.

Obviously, no commands requiring a GUI will work from headless mode, including dialogs. Most commands that open dialogs also include arguments that can be used in lieu of the dialogs, so no functionality is lost by running in headless mode.

> select.item Camera
+ ok
> item.channel focalLen ?
: 0.05
+ ok
> item.channel focalLen 0.1
+ ok
> item.channel focalLen ?
: 0.1
+ ok

Redirected From a File

You can pass a list of commands from a file directly into modo on startup via redirection. Redirection is a standard feature of the console. Each line of a file is processed as a separate separate command, and each is executed in turn, similar a macro. Once all lines are processed, modo will quit.

It is important to note the the redirection syntax is a feature of the console, not a feature of modo. This means that it is unlikely to work from a scripting language or another program that doesn't also emulate console behaviors like redirection. In those cases, you should use one of the other methods, such as stdio pipe redirection or Telnet, to pass commands into modo.


From a Pipe

The real power of the headless mode comes from piping commands into it by redirecting stdio (specifically, stdin and stdout) to your application. This allows scripts and external programs to have direct control over modo by emulating the input and output provided by a console. For example, Perl has a standard syntax for opening a one-way pipe. Once the connection has been established, perl’s print() function can be used to send commands to modo. When you are finished you can call App.quit to close modo.

open (MODOCMD, "| modo_cl");
print MODOCMD "scene.open $myscene\n";
print MODOCMD "render.animation\n";

Two way pipes can be opened from other programs and scripts. This permits full two way communication with modo, allowing commands to be sent and results to be received. Programs can also capture stdin and stdout and handle input and output that way. See the documentation for your scripting language or platform API for more information on using stdin, stdout, pipes and controlling command line programs.

Logging to the Console

By default, the logged messages are not output in the console. This can be toggled with the Log.toConsole command for entries that would normally appear in the Event Log Viewport, and Log.toConsoleRolling for entries that would normally appear in the Feedback Viewport. When passed true, all future logged events will be sent straight to the console. These events are prefixed with an exclamation point and the subsystem name in parentheses.

log.toConsole true
log.toConsoleRolling true

Logging rolling log output to the console is most useful to get extended real-time render progress information while rendering.

Specific subsystems can be told to log (or not to log) events using the Log.subToConsole command. Log.subToConsoleOnly can be used to output only that specific subsystem's entries, effectively hiding all other logging to the console from other subsystems. Log.consoleReset turns back on all log subsystem console output.

Log.masterSave and Log.subSave can also be used to save the log to a file, wether or not Log.toConsole is enabled. These work in the same way that the Save popup in the Event Log viewport does, and will save the same information. Rolling log messages cannot currently be saved, since the previous message is discarded as soon as a new one comes in (hence the term "rolling").

log.masterSave "c:\masterLog.txt"

Specific log subsystems can be told to stop or start logging via Log.subEnable. When disabled, they will not send new entries to the event log, either in the GUI or to the console.

Other Command Line Switches

There are a few other command line switches used in modo. These can be used from both the headless and GUI modes, unless otherwise specified.

Headless mode: -console and -prompt

The -console switch was used in older versions of modo to launch the main modo application in headless mode on OS X. This switch is no longer used; instead, a separate modo_cl program (stored within the modo application bundle) is used in exactly the same way as its Windows counterpart, as described above.

The -prompt switch is also described above, and allows you to change the prompt modo uses to request input from the user in headless mode. This does nothing in GUI mode.


Executing an Initial Command: -cmd

It is possible to tell modo to run an intiial command at startup through the -cmd switch. This can be thought of as a single startup command, and is executed after all config-based startup commands.

This feature is most useful for render controllers, allowing them to launch modo and tell it to execute a specific script on startup while also passing arguments to that script. For example, this would pass two arguments with the values path and range to the @myrender.pl script on startup.

Note that the redirection method described above or Telnet might be better than using the -cmd switch, as redirection allows multiple commands to be passed and automatically quits modo when finished.


Changing the User Config Path: -config

The -config switch tells modo to use a different path for the user configuration file. This can be used by render nodes to load a specific config, or used in conjunction with -license to run modo off of a memory stick without requiring anything to be written to the local machine.

The path provided can either point to an actual config file, or to a directory containing a config file with the standard user config filename. The specified config will used in place of the default, which means that not only will initial settings be loaded from this config, but settings will also be saved to this file on quit.

Note that on OS X all paths must be absolute; relative paths, including the home (~) path, are not supported.


Changing the License Path: -license

The -license switch allows you to tell modo to search for the license file in a specific path. This must point to the directory containing the license, not the license file itself. When combined with the -config switch, this can be used to run modo off of a memory stick without needing to write anything to the system drive. -license is functionally identical to -path:license=<path>, as described below.

Note that on OS X all paths must be absolute; relative paths, including the home (~) path, are not supported.


Changing Other Standard Paths: -path

The -path parameter allows you to override many of modo's standard paths. The format is -path:<name>=<path>. The following names are currently defined.

Name Description
temp Directory for temporary files
license License directory containing license keys
resource Resource directory used to load default application resources
module Plug-in auto-search directory
prefs Location of the user config
help Directory containing help files
user User directory, used as a search path for user-specific resources, scripts and other extensions
content Location of installed content
asset Location of installed assets, usually a sub-directory of content

Note that on OS X all paths must be absolute; relative paths, including the home (~) path, are not supported.


Changing Paths through Environment Variables

Each of these paths can also be overridden through environment variables named NEXUS_ followed by the name to remap. For example, content can be redirected with the environment variable NEXUS_CONTENT.

Running in slave mode: -slave

The -slave switch forces modo to start up in slave mode for network rendering. This is the only way to force modo to open in slave mode at startup, as the Render.slave command cannot be executed as a startup command or through the -cmd switch. Furthermore, slave mode can only be run from the GUI version of modo, and will not work from the headless mode.


Telnet Server

The -telnet switch can be used to launch modo and automatically start the Telnet server. The argument is the port and if it should open in raw mode or Telnet, in the format of -telnet:mode@port The mode@ portion can be omitted to imply telnet mode. When running form the GUI, the telnet server will run in the background as normal. When used with headless mode, telnet is used in place of the normal console input, and you will not be able to enter commands through the console. See the Telnet article for more information on using telnet.

It is also possible to open telnet in named pipe mode, in which case the port number is replaced with the pipe name. Note that this pipe mode is simply a way of using raw mode telnet-style functionality from a named pipe, and is different from stdio pipe redirection.


Modo Socket comms wrapper, an example wrapper for 'raw' socket mode written in Python.

Loading an Initial Scene

Any scene can be loaded at startup by entering its path at the end of the argument list. There is no special argument name for this feature.

Once again, mote that on OS X, all paths must be absolute; relative paths, including the home (~) path, are not supported.


Debug Flags: -dblog, -dbon, -dboff and -debug

A few debugging flags exist in modo. These are generally only for internal use, but you may be asked by customer service to enable them to help track down an issue.


The -dblog switch instructs modo to write a log to the path provided. The exact contents of this log varies depending on which other debug flags are set.



-dbon and -dboff

The -dbon and -dboff switches toggle specific debugging operations on and off. Most of these are only useful for internal purposes, but there are a few that are useful to end users. For example, -dbon:noconfig will load your user config on startup, but will not save to it when the application quits.



This sets the verbosity of the debug output that is saved to the log. The options are quiet, error, normal, track and verbose. Note that turning on track or verbose can affect the performance of the application.


More Information