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.


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.


See API mode


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.

Since Ocean 2017, the command line mode accepts OCRAW files as input for reprocessing them.


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

A few format specifiers may be used for generating output file names automatically:

  • %f is replaced by the scene file name, without the extension

  • %o is replaced by the output name, and by an empty string if no output is defined

  • %i is replaced by the instrument name, and by an empty string if no output is defined

  • %x is replaced by the default file extension defined by the output

  • %.o is replaced by a dot followed by the output name, and by an empty string if no output is defined

  • %.i is replaced by a dot followed by the instrument name, and by an empty string if no output is defined

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


If you use the rawexr or rawhdr file extension, the file format will be exr / hdr, but the raw unprocessed output will be written:

-o result.rawexr

As of Ocean 2018R3, if you use the oclib extension, all the input files will be packed into an encrypted Ocean library:

-o result.oclib

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


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.


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


Start the program in API mode


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


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.


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"

--output [name]

Specifies the instrument output preset name for writing the results.

If the instrument has no output with that name, the first output will be selected as default.


All instrument outputs will be processed.

One result file per output will be written, using the %o pattern in the file name for differentiating output file names.


Replace the instrument’s outputs by those from an external ocraw file.

--setup [name]

Sets the active setup. A setup with that name must have been defined in the scene, or a default one will be selected instead.