Updated 10/June/2024 (build 4.8.12)


--------------------------------------------
Running Terragen 4 Linux From a Command Line
--------------------------------------------


Terragen 4 for Linux is a command line render node which doesn't have a GUI. Apart from rendering frames, it also supports additional commands such as exporting VDB files.


SETUP
-----

If Terragen is not in the current working directory, it will probably make lots of complaints when it starts. It's not enough just to pass the full path of the Terragen 4 command when you run it. Terragen needs to know where it can find other related files.

To fix this, you can set the TERRAGEN_PATH environment variable. For example you can set TERRAGEN_PATH to your user directory like this if you use bash :

    export TERRAGEN_PATH=~/

If you use tcsh:

    setenv TERRAGEN_PATH ~/

In other shells you would use the appropriate syntax.

IMPORTANT: If you set the TERRAGEN_PATH variable you modify the behaviour of all instances of Terragen within the scope of the variable, and this may cause problems if you have multiple versions installed. You can avoid using the TERRAGEN_PATH variable if you 'cd' to the directory before calling the executable.


EXECUTION
---------

Once you have changed into the executable folder, you can run Terragen 4. Here are some examples:


Run Terragen 4 as normal:

    ./terragen

Run Terragen 4 and load a project file:

    ./terragen -p project.tgd

Run Terragen 4 and load a project file, render to a file and then close:

    ./terragen -p project.tgd -exit -r -o test.tif

Run Terragen 4 and load a project file, render frame 42 and then close:

    ./terragen -p project.tgd -exit -r -f 42

Run Terragen 4 and load a project file, render frames 1,4,51,53,55,57,59 and then close:

    ./terragen -p project.tgd -exit -r -f 1,4,51-60/2


Note: Currently Terragen automatically sets the -hide and -exit flags whenever -r or -exportvdb is set, but you should always set -hide and -exit if you don't want this behaviour to change in future versions.


ALL COMMAND LINE OPTIONS
------------------------


-exit

Exit Terragen after all rendering and other commands have finished.


-f <frameRange|commaSeparatedFrameRanges>

Set the frame range or list of frame ranges to render when -r is also used. If -r is not used, the current frame is set to the first in the range/list.
The list can contain any combination of frames or frame ranges separated by commas without any whitespace.


Example: -f 34

Set the frame to render to 34.


Example: -f 1-100

Set the frame range to render from 1 to 100 (inclusive).


Example: -f 1-100/5

Set the frame range to render from 1 to 100 with a step size of 5. This produces the sequence 1, 6, 11, 16, ... , 96.
Note that frame 100 is not rendered because 96 + 5 = 101 which is outside the specified range.


Example: -f 34,37,38

Set the list of frames to render to 34, 37, 38


Example: -f 1-50,66,71-100/10

Set the list of frames to render from 1 to 50 (inclusive) followed by 66 followed by 71, 81, 91.
Note that frame 100 is not rendered because 91 + 10 = 101 which is outside the specified range.


-hide

Hide the graphical user interface. Do not show any dialog boxes. This is not relevant to the Linux render node as it doesn't have a GUI.


-no3dpreview

Do not open the 3D Preview automatically. This is not relevant to the Linux render node as it doesn't have a GUI.


-nonetworkview

Do not open the Network View automatically (except in Node Network Layout). This is not relevant to the Linux render node as it doesn't have a GUI.


-o <filename>

Set the renderer's output image filename to <filename> before rendering.
C-style format strings can be used to automatically insert the frame number,
eg. '~/frames/image.%04d.IMAGETYPE.exr'
Supported image extensions are .bmp, .rgb, .sgi, .exr, .tif, .tiff


-ox <filename>

Set the renderer's "extra output images" filename to <filename> before rendering.
Extra output images should contain the string "IMAGETYPE" (not including quotes).
When a render element is written, "IMAGETYPE" is automatically replaced by the name of the element.
By default the only element is "tgAlpha", but additional elements can be enabled using a Render Layer.


For example:

'~/frames/image.0023.IMAGETYPE.exr'

may result in:

'~/frames/image.0023.tgAlpha.exr'
'~/frames/image.0023.tgSurfRgb.exr'
'~/frames/image.0023.tgSurfAlpha.exr'
etc.

or, if "create subfolders" option is enabled (in project or command line), may result in:

'~/frames/tgAlpha/image.0023.tgAlpha.exr'
'~/frames/tgSurfRgb/image.0023.tgSurfRgb.exr'
'~/frames/tgSurfAlpha/image.0023.tgSurfAlpha.exr'
etc.


C-style format strings can be used to automatically insert the frame number. Example:

'~/frames/image.%04d.IMAGETYPE.exr'


Supported image extensions are .bmp, .rgb, .sgi, .exr, .tif, .tiff


-oxsubfolders

Create and use subfolders when outputting render elements (extra output images).
This overrides the "create subfolders" option in the project's render node.


For example:

'~/frames/image.0023.exr'

may result in:

'~/frames/tgAlpha/image.0023.exr'
'~/frames/tgSurfRgb/image.0023.exr'
'~/frames/tgSurfAlpha/image.0023.exr'
etc.


It can be combined with the use of "IMAGETYPE" in the filename, so the following is possible:

'~/frames/tgAlpha/image.0023.tgAlpha.exr'
'~/frames/tgSurfRgb/image.0023.tgSurfRgb.exr'
'~/frames/tgSurfAlpha/image.0023.tgSurfAlpha.exr'
etc.


If the command line contains both -oxsubfolders and -oxsubfolders=no then the behaviour is undefined.


-oxsubfolders=no

Prevent the creation or use of subfolders when outputting render elements (extra output images).
This overrides the "create subfolders" option in the project's render node, which is usually enabled.
If the command line contains both -oxsubfolders and -oxsubfolders=no then the behaviour is undefined.


-ocio

Enable "Use OCIO" in Project Settings at startup and after loading a project.
For this to be useful there must be an environment variable named OCIO pointing to a valid OCIO config file.
Terragen will default to roles which work well with ACES 1.0.3 but might not be compatible with your OCIO configuration.
We recommend testing this feature in the GUI first to see if the default settings are suitable.
Please send us feedback if you think our defaults could be better or you need more controls.


-ocio=no

Disable "Use OCIO" in Project Settings at startup and after loading a project.


-p <filename>

Open the project specified by <filename> before doing anything else.


-r

Render current frame (or frame range with -f) using the "master" renderer; save output image and extra output images (if enabled).
The -hide and -exit flags are set automatically in the current version.
The "master" renderer is the render node which has its "master" setting enabled,
or the first render node in the project if none are masters.
Another render node can be made the master by using the -rendernode command line option.


-rendernode <nodename>

Make <nodename> the "master" renderer after autoloading the project at startup.
Projects loaded subsequently are not affected.
<nodename> must be the name or full path of a render node in the project,
and it must be surrounded by quotes if it contains any spaces (quotes are optional if there are no spaces).


-renderlayer <renderLayer>

Connect <renderLayer> to the "master" renderer after autoloading the project at startup.
Projects loaded subsequently are not affected.
<renderLayer> must be the name or full node path of a Render Layer node in the project,
and it must be surrounded by quotes if it contains any spaces (quotes are optional if there are no spaces).
The "master" renderer is the render node which has its "master" setting enabled,
or the first render node in the project if none are masters.
Another render node can be made the master by using the -rendernode command line option
(-rendernode is applied before -renderlayer regardless of their order in the command line).


-threads <numberOfThreads>

Override the number of threads used for rendering and other multithreaded tasks.
When used, this command line override takes priority over the min/max thread settings in the render node and the cores override in Preferences.


-tilex <minx> <maxx>

Limit the rendered region to a fraction of the image or crop region to be rendered.
minx and maxx should be numbers between 0 and 1, where minx < maxx.
For example, "-tilex 0 0.5" renders only the left half of the image or the left half of whatever crop region was already set.
You can use both -tilex and -tiley simultaneously to define a rectangular region.


-tiley <miny> <maxy>

Limit the rendered region to a fraction of the image or crop region to be rendered.
miny and maxy should be numbers between 0 and 1, where miny < maxy.
For example, "-tiley 0 0.5" renders only the bottom half of the image or the bottom half of whatever crop region was already set.
You can use both -tilex and -tiley simultaneously to define a rectangular region.


-cropoutput

Crop the output image(s) to the dimensions of the rendered region (defined by "crop region" and/or -tilex, -tiley), i.e. do not pad to the full image dimensions.


-exportvdb <cloudLayerNode> <outputFilename>

Generate a voxel buffer from the density of the specified cloud layer and export it to an OpenVDB file.

Example:
    ./terragen -p project.tgd -exportvdb "Easy cloud 01" cloud.vdb -threads 8

The cloud name needs to be in quotes if there are spaces in its name (usually there are). Similarly for filenames. The use of the -threads command line option is optional, and can be inserted anywhere in the command line as long as it is followed by an integer number and doesn't break apart any other argument groups.

For information about voxel resolution and other considerations visit https://planetside.co.uk/wiki/index.php?title=VDB_Export


-w <filename>

The same as the -p option
