Command line syntax

Ocean may be used either with a Graphical User Interface (GUI) or in console mode. This is controlled via command line parameters, which offers various possibilities.

General command line interface

The command line syntax is the following:

> ocean.exe [input-files] [options]

GUI vs Console/API

If the -c, --console or --api option is given, the program will run in console mode. The API mode is a special mode for controlling Ocean from another application, see API mode for more details.

Otherwise, it will run in GUI mode.

GUI

In GUI mode, the working directory will be the one set in the preferences. The first input scene file will be opened, others will be ignored. Opening Ocean raw result files is possible as well.

API

See API mode

Console

In console mode, the working directory is the current command-line path. Each input scene file will be simulated sequentially. A halt condition must have been properly set in the file, otherwise the simulation will never finish and the result will not be saved. Ocean raw result files cannot be opened in console mode.

Input Files

Multiple input files may be passed using the * and ? wildcards. * matches a variable number of characters, and ? matches a single character.

Options

-o [output-file]

Output file name (Console only)

This parameter sets the output file name for the simulation. The file format is automatically chosen from the file extension, see file formats for more details. When multiple input files are given and simulated sequentially, setting this option to a file name will cause the result file to be overwritten when each simulation is done. You may use the * wildcard instead, it will be replaced by the input file name. For instance:

-o *.jpg.

If you use the auto file extension, the file format will be guessed by default, depending on the postprocessing type used. For instance:

-o result.auto
-s [port]

Server mode (Console/API/GUI)

This parameter starts Ocean in server mode. The optional port value is the network port to be opened, between 1 and 65535. If omitted, the value set in the preferences of GUI mode (11878 by default) is used. See network simulation for more details.

-sr [host1][,host2][,...]

Connect to remote Ocean servers (Console/API/GUI)

This parameter tells Ocean to connect to remote Ocean servers for network simulation. Multiple server hosts may be added by separating them with commas, or by adding multiple -sr arguments Host can be any valid network name or IP address. Port is specified in the [host]:[port] format. This option is ignored in server mode.

-sl

Connect to internal Ocean server (Console/API/GUI)

This parameter tells Ocean to create and connect to an internal server. This is the default behavior (non networked simulation), but this option must be used if remote servers were added and if the client should work too. This option is ignored in server mode.

-t
Set the number of working threads (Console/API/GUI)
-v or --verbose
Verbose mode (Console/API/GUI) Displays (much) more information in the log
-q or --quiet
Disable logging all messages (Console/API/GUI)
-m + arguments

Selects the messages to be displayed on the log (Console/API/GUI)

+ : enables the following message type letters

- : disables the following message type letters

V : verbose messages

I : information messages

W : warning messages

E : error messages

D : debug messages

P : time progression (Console only)

For instance, -m-VIP+WE shows warning and errors, but disables information, verbose and time progression.

-c or --console
Start the program in console mode
--api
Start the program in API mode
--showinputfiles

Just display the list of input files (Console only)

This option just prints a list of input scene files with their full path, and do not start any simulation. This is useful for solving issues related to input file wildcards (* or ?) and relative paths.

--program-stdout

Program friendly standard output (Console only)

Information sent to the standard output is optimized for parsing by another program, instead of being optimized for user reading.

--postcommand

Process output with an external command (Console only)

After each simulation is run in command-line mode, an external program is launched, with the output file as argument.

Example

ocean.exe -c *.ocxml -o *.png --postcommand c:\tools\watermark.cmd

Will render all ocxml scenes in the current directory to PNG images, and launch watermark.cmd on each image file.

Important remark : If the command contains arguments separated by spaces, the whole command should be passed as a single argument enclosed by double-quotes:

ocean.exe -c *.ocxml -o *.png --postcommand "c:\tools\watermark.cmd -s"

If the program itself contains spaces in its path, it must also be enclosed by escaped double quotes, so that it is not split both at Ocean startup and at command startup:

ocean.exe -c *.ocxml -o *.png --postcommand "\"c:\Program Files\tools\watermark.cmd\" -s"