Headless

From The Foundry MODO SDK wiki
Revision as of 12:16, 7 June 2016 by Jangell (Talk | contribs) (Logging to the Console)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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

Preface

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.

License

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.

modo_cl.exe

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

modo.app/Contents/MacOS/modo_cl

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.

app.quit
@exit
ok

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.

modo_cl.exe "-prompt:ready: "

modo.app/Contents/MacOS/modo_cl "-prompt:ready: "

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

@start  modo [xxxxx]  Luxology LLC
John Smith
ready: 

Formatting

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 command, and each is executed in turn, similar to 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.

modo_cl.exe < commands.txt

modo.app/Contents/MacOS/modo_cl < commands.txt

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.

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

 #python 
 #-------------------------------------------------------------------------
 #vs9841 2013-10-23 Add Edit
 #The python script running on python v3.3.2,and the test in modo v701 sp2. 
 #This script does not need the built- in modo python environment to run , 
 #I was using the operating system installed python v3.3.2 tested. 
 #------------------------------------------------------------------------- 
 import subprocess modocl = "D:\\Program Files\\Luxology\\modo\\701_sp2\\modo_cl.exe" 
 modosc = 'scene.open "H:\\modo\\Study\\zx.lxo"\n' 
 p = subprocess.Popen(modocl,
         	stdin = subprocess.PIPE,
 		stdout = subprocess.PIPE,
  		stderr = subprocess.PIPE,
  		universal_newlines=True,
 		shell = False)
 print(p.stdout.readline())
 p.stdin.write(modosc)
 p.stdin.write('query sceneservice scene.name ? current\n')
 p.stdin.write('app.quit\n')
 print(p.stdout.read())

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. The log.toConsole command will cause entries that would normally appear in the Event Log Viewport to go to the console. log.toConsoleRolling does the same for rolling log entries that would normally appear in the Feedback Viewport. 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. This will also enable the messageDialogs output, which contains the human-readable output of various dialogs that would open in the full version of modo, but which are suppressed in headless mode.

Another example might be dialogs created with the dialog.??? commands. Output of the most recent dialog is always logged to the messageDialogs rolling log. For example, the following loginfo.py shows the modo version in a dialog:

#python
 
import lx
 
x = lx.eval('query platformservice appversion ?')
if x > 401:
	lx.eval('dialog.setup info')       
	lx.eval("dialog.title {Version...}")   
	lx.eval("dialog.msg {Your modo version is %d}" % x)
	lx.eval("dialog.open")

Dialogs will not open in headless mode, but they are still logged. After executing log.toConsoleRolling command, you will see the following in the console:

@start  modo_cl [xxxxx]  Luxology LLC
>log.toConsoleRolling true
+ ok
>@loginfo.py
! (messageDialogs) [Info] - Version... | Your modo version is 701
+ ok
>

What Gets Output

By default, all enabled log subsystems are output to the console (and displayed in the Log View). Subsystems are enabled and disabled with log.subEnable. Many subsystems are enabled by default, but some of the more esoteric ones aren't.

Rather than outputting all enabled subsystems, you can choose a specific subset with the following commands:

  • log.subToConsole makes it possible to output just a specific subsystem or set of subsystems to the console. Once this is called with true, only that one subsystem will be output. Calling it with true again for other subsystem will output that subsystem's entries as well. Calling it again with false for all of those subsystems will reset it back to showing all enabled log subsystems. You can think of it as the "when nothing is selected, everything is selected" behavior that modo normally uses.
  • log.consoleReset turns back on all log subsystem console output, and is equivalent to calling log.subToConsole with false for all subsystems..
  • log.subToConsoleOnly can be used to stop outputting all log subsystems except for one specific one. This is the same as calling log.consoleReset followed by log.subToConsole for the one system you want enabled.

Saving Logs to Disk

One-Time Saving

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 -- meaning, only entries from subsystems that were enabled at the time they were added, not at the time of saving the log .

Note that 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"

Saving On The Fly

log.subToFile and log.subToFileRolling can be used to write log entries to disk as they come in. The master log (meaning, all enabled subsystems, instead of a single specific subsystem) can also be saved by passing an empty string or master as the subsystem. log.subToFileCloseAll stops writing to all open files and closes them.

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

-console

The -console switch determines how headless handles input. The default is to use the command parser, like the one used at the bottom of the Command History viewport. The other option is to treat input as Python instructions, thus allowing it to behave as a Python shell.

modo_cl.exe -console:python

modo.app/Contents/MacOS/modo_cl -console:python

In older versions of modo, 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 in that way; 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.

-prompt

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.

modo_cl.exe "-prompt:ready: "

modo.app/Contents/MacOS/modo_cl "-prompt:ready: "

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.

modo_cl.exe "-cmd:@myrender.pl {path range}"

modo.app/Contents/MacOS/modo_cl "-cmd:@myrender.pl {path range}"

Executing a Late Initial Command: -cmdlate

-cmdlate is identical to -cmd, except for when it is executed. -cmd commands are executed immediately after the config-based startup commands, but before licensing and networking are started. -cmdlate commands are executed well after those systems are started up, and are basically the last thing that is done before control is given over to the user.

The main use for this is to open Telnet or Preview Socket listeners on startup from a script. Using conventional startup commands this is not possible, as they would all run before networking is available.

modo_cl.exe "-cmdlate:@mytelnet.py"

modo.app/Contents/MacOS/modo_cl "-cmdlate:@mytelnet.py"


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.

modo_cl.exe "-config:c:\myUserConfigDir" modo_cl.exe "-config:c:\myUserConfig.cfg"

modo.app/Contents/MacOS/modo "-config:/Volumes/Macintosh HD/Users/myusername/myUserConfigDir" modo.app/Contents/MacOS/modo "-config:/Volumes/Macintosh HD/Users/myusername/myUserConfigDir.cfg"

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.

modo_cl.exe "-license:c:\Licenses"

modo.app/Contents/MacOS/modo "-license:/Volumes/Macintosh HD/Users/myusername/Licenses"

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.

modo_cl.exe "-path:temp=c:\temp"

modo.app/Contents/MacOS/modo "-path:temp=/Volumes/Macintosh HD/Users/myusername/temp"

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.

modo.exe -slave

modo.app/Contents/MacOS/modo -slave

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_cl.exe -telnet:12357 modo_cl.exe -telnet:telnet@12357 modo_cl.exe -telnet:raw@12357 modo_cl.exe -telnet:pipe@myPipeName

modo.app/Contents/MacOS/modo -telnet:12357 modo.app/Contents/MacOS/modo -telnet:telnet@12357 modo.app/Contents/MacOS/modo -telnet:raw@12357 modo.app/Contents/MacOS/modo -telnet:pipe@myPipeName


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, note that on OS X, all paths must be absolute; relative paths, including the home (~) path, are not supported.

modo_cl.exe "c:\MyScene.lxo"

modo.app/Contents/MacOS/modo "/Volumes/Macintosh HD/Users/myusername/MyScene.lxo"

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.

-dblog

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.

modo_cl.exe "-dblog:C:\modolog.txt"

modo.app/Contents/MacOS/modo "-dblog:/Volumes/Macintosh HD/Users/myusername/modolog.txt"

-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.

modo_cl.exe -dbon:noconfig

modo.app/Contents/MacOS/modo -dbon:noconfig

-debug

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.

modo_cl.exe -debug:normal

modo.app/Contents/MacOS/modo -dbon:normal

More Information