Mac Command Line Reference

From Planetside Software Wiki
Jump to: navigation, search

This is a mirror of the file 'mac_command_line.txt' in the Documentation folder in your copy of Terragen 3.

Updated 8/September/2012 (build 2.9.0.12)



Running Terragen 3 Mac From a Command Line


Terragen 3 Mac can be run from the command line. To access the command line on OS X you can use Terminal.app, which comes with OS X. It can be found in the Utilities folder inside your Applications folder.

To start Terragen 3 from the command line you need to access the executable directly. Terragen 3 is a bundled application which means the application you see in the Finder is really a special folder. The actual executable is inside the folder. To access it you need to do something like this :

   cd '<PATH TO TG3>/Terragen 3.app/Contents/MacOS/'

where <PATH TO TG3> is the path to where you have the Terragen 3 application on your system.

Notice that the first part of the path is "Terragen 3.app". This is name of the special application folder mentioned above, which is what you see in the Finder as the actual Terragen 3 application. The Finder hides the ".app" extension from you, but you need to add it when accessing the executable from the command line. The actual executable is inside the "MacOS" folder, which is inside the "Contents" folder of the special "Terragen 3.app" application folder.

The actual executable name is "Terragen 3". Once you have changed into the "MacOS" folder as described above you can run the executable like this :

   ./'Terragen 3'

N.B. You will need to use single quotes around paths (as I have above), because of the spaces in the "Terragen 3" name. Alternatively you could escape the spaces in the path, but if you know how to do that you don't really need these instructions.


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 3 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 3. Here are some examples:


Run Terragen 3 as normal:

   ./'Terragen 3'

Run Terragen 3 and load a project file:

   ./'Terragen 3' -p project.tgd

Run Terragen 3 and load a project file, without the GUIGraphical User Interface, a general term that refers to the interface of any program running in a modern graphical operating system and which does not operate exclusively from the commandline., render frame 42 and then close:

   ./'Terragen 3' -p project.tgd -hide -exit -r -f 42

Run Terragen 3 and load a project file, without the GUIGraphical User Interface, a general term that refers to the interface of any program running in a modern graphical operating system and which does not operate exclusively from the commandline., render frames 1,4,51,53,55,57,59 and then close:

   ./'Terragen 3' -p project.tgd -hide -exit -r -f 1,4,51-60/2


IMPORTANT: Currently (v2.4.20.0), Terragen automatically sets the -hide and -exit flags whenever -r 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 rendering has finished. Do not show any dialog boxes (because they may prevent exiting).


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


-no3dpreview
Do not open the 3D Preview automatically.


-nonetworkview
Do not open the Network View automatically (except in Node Network Layout).


-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.alpha.exr'
'~/frames/image.0023.surfrgb.exr'
'~/frames/image.0023.surfalpha.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


-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 nodeA single object or device in the node network which generates or modifies data and may accept input data or create output data or both, depending on its function. Nodes usually have their own settings which control the data they create or how they modify data passing through them. Nodes are connected together in a network to perform work in a network-based user interface. In Terragen 2 nodes are connected together to describe a scene. which has its "master" setting enabled, or the first render nodeA single object or device in the node network which generates or modifies data and may accept input data or create output data or both, depending on its function. Nodes usually have their own settings which control the data they create or how they modify data passing through them. Nodes are connected together in a network to perform work in a network-based user interface. In Terragen 2 nodes are connected together to describe a scene. in the project if none are masters. Another render nodeA single object or device in the node network which generates or modifies data and may accept input data or create output data or both, depending on its function. Nodes usually have their own settings which control the data they create or how they modify data passing through them. Nodes are connected together in a network to perform work in a network-based user interface. In Terragen 2 nodes are connected together to describe a scene. 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. <nodename> must be the name of a render nodeA single object or device in the node network which generates or modifies data and may accept input data or create output data or both, depending on its function. Nodes usually have their own settings which control the data they create or how they modify data passing through them. Nodes are connected together in a network to perform work in a network-based user interface. In Terragen 2 nodes are connected together to describe a scene. in the project. Projects loaded subsequently are not affected.


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


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


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


-w <filename>
The same as the -p option