Terragen Documentation from Planetside Software - User contributions [en]

OBJ Reader

2025-11-02T21:58:00Z

Matt: Minor edit to embolden 'Filename' in the descriptions of Sequence First and Sequence Last

[[File:OBJReader_00_GUI.png|none|470px|OBJ Reader]]
 
== Overview ==

The OBJ Reader node loads models from a Wavefront .OBJ file. The OBJ Reader can also load .mtl files specified by the OBJ containing texturing information. When you create an OBJ Reader it opens a file dialog allowing you to choose the file to load.

'''Node Type:''' Object 

'''Settings:''' 

<ul>
<li>
'''Population mode:''' This popup has two options:

[[File:OBJReader_01_PopulationMode.png|none|322px|Population mode parameters]]

<ul><li>Individual Object: This is the default for objects created individually, not part of a population. If you choose this option for objects that are part of a population the population instances will still render but the object itself will also show up at its original position. </li>
<li>Member of a Population: This is the default for objects created as part of creating a population. It means the objects only render as part of a population. If you choose this option for an individual object it won't render. If you create an object as part of a population and then decide to use it on its own you may need to change the popup to Individual Object to get it to render.</li></ul>

<li>'''Preview mode:''' This popup has five options to let you choose how the object should be displayed in the 3D Preview, and sets the most detailed mode that the object can be displayed in. The '''Object Display Mode''' button in the 3D Preview controls the mode for the preview as a whole. For example, if you set the '''Preview mode''' of the object to '''Wireframe''' but the 3D Preview object display mode is set to '''Show as bounding boxes''' then the object will only be drawn as a bounding box.</li>
[[File:OBJReader_02_PreviewMode.png|none|234px|Preview Mode parameters]]

<li>''' Preview Colour:''' Enabling this parameter causes the object to be drawn in the 3D preview using the preview colour when the object display mode is set to '''Show as bounding box''' or '''Show as wireframe'''. When set to '''Show as smooth shaded''' or '''Show as textured''' the preview colour tints the object’s textured surface. This is useful for making a particular object stand out in the 3D preview. Clicking on the colour swatch to the right of the parameter label opens the [[Colour_Picker|Colour picker pane]].
</li>
 </ul>
== File Read Tab ==
[[File:OBJReader_03_FileReadTab.png|none|460px|File Read Tab]]

'''Settings:'''
<ul><li>'''Filename:''' This parameter shows the path to the file used by the OBJ Reader. You can use the file button at right to load a different file but this isn't recommended as the materials for the new file won't be loaded. To use an OBJ file sequence you can use a limited set of C-style format strings to automatically insert the frame number, for example "MyObject_%04d.obj" may result in "MyObject_0023.obj" on frame 23, depending on the options on the Sequence tab.</li></ul>
 
== Sequence Tab ==
[[File:OBJReader_04_SequenceTab.png|none|460px|Sequence Tab]]
'''Settings:'''
<ul><li>'''Sequence first:''' When a supported frame insertion pattern is used in '''Filename''' to load a file sequence, '''Sequence first''' and '''Sequence last''' control the range of numbers that are allowed in the file sequence. For example, if you have files with names MyObject_0001.obj to MyObject_0010.obj and want your animation to use them all, you would set '''Sequence first''' and '''Sequence last''' to 1 and 10 respectively.</li>
<li><li>'''Sequence last:''' When a supported frame insertion pattern is used in '''Filename''' to load a file sequence, '''Sequence first''' and '''Sequence last''' control the range of numbers that are allowed in the file sequence. For example, if you have files with names MyObject_0001.obj to MyObject_0010.obj and want your animation to use them all, you would set '''Sequence first''' and '''Sequence last''' to 1 and 10 respectively.</li>
<li>'''Frame offset:''' This value provides a way to load files with sequential numbers that are different from the rendered frame numbers, to shift the timing of the animation or to account for differences in how the frames are numbered in the object filenames. Terragen adds '''Frame offset''' to the project's current frame number to determine which file number to load (with the actual file number being limited to the range defined by '''Sequence first''' and '''Sequence last''' with optional looping or ping-ponging). For example, if the '''Sequence first''' value is "1", the '''Sequence last''' value is "10", and the '''Offset''' value is "4", then MyObject_0005.obj would be loaded on frame 1, MyObject_0006.obj on frame 2, etc. Negative offsets can be used. For example, if the '''Offset''' value is "-1000" (negative), then MyObject_0001.obj would be loaded on frame 1001, MyObject_0002.obj on frame 1002, etc.</li>
<li>'''Loop or Ping Pong:''' After Terragen applies '''Offset''' to the current frame number, if the resulting frame number falls outside the range defined by '''Sequence first''' and '''Sequence last''' then '''Loop''' and '''Ping Pong''' are two different ways extend the cycle infinitely, both before the beginning and after the end of the sequence. Upon completion of the sequential object cycle determined by the '''Sequence first''' value and '''Sequence last''' value, the objects can either “loop” back to the '''Sequence first''' object and cycle through the objects as each frame advances, or “ping pong”, that is, reverse the object sequence order until the '''Sequence first''' object is encountered. If neither '''Loop''' nor '''Ping Pong''' are checked then the object will be held at the first or last file in the sequence when the requested frame number falls outside the defined range.</li>
[[File:OBJReader_45_OBJSequence.gif|none|400px|Object sequence options.]]
</ul>

 

== Mesh Modifiers Tab ==
[[File:OBJReader_12_MeshModifiersTab3.png|none|460px|Mesh Modifiers Tab]]
'''Settings:'''

<ul>
<li>'''Read MDD file (motion):''' Terragen can apply Motion Designer or “MDD” files created in third-party 3D software packages to an object within the project. The MDD file contains the position of every vertex in an object, for each frame of an animation. After an object is animated or otherwise deformed in the third-party 3D software, its vertex positions are “baked”, or saved in the MDD file format. This allows for complex animation to exist within a Terragen project, that otherwise could not.</li>
{|
|-
| [[File:OBJReader_52_MDD_Flag.gif|none|400px|MDD file cloth simulation.]] || [[File:OBJReader_51_MDD_Bat.gif|none|400px|MDD animated flap cycle.]]
|} 
<li>'''Reverse Z (right handed): ''' If the MDD file is facing in the wrong direction, you can reverse the Z axis in order to point it in the right direction.</li>
[[File:OBJReader_47_ReverseZ_Bat.gif|none|400px|Effect of enabling the Reverse Z (right handed) parameter.]] 
<li>'''Mesh displacer:''' The shader assigned to this parameter displaces the object’s vertices (mesh). For example, a power fractal shader can be used to displace the vertices of the 3D object or a population. The denser the object’s geometry, or more vertices it has, allows for more subtle deformations to be visible.</li>
{|
|-
| [[File:OBJReader_15_MeshModifiersTab_MeshDisplacer_Cattail.gif|none|400px|Animated parameters on a power fractal to deform a single 3D object.]] || [[File:OBJReader_16_MeshModifiersTab_MeshDisplacer_Population.gif|none|400px|Animated parameters on a power fractal to deform a population.]]
|-
| [[File:OBJReader_48_MeshDisplacer_NonShadered.PNG|none|400px|Displacement applied to non-shadered objects.]] || [[File:OBJReader_18_MeshModifiersTab_MeshDisplacer_TexturedLeafs2.PNG|none|400px|Displacement applied to textured objects.]]
|}
 

<li>'''Recalculate Normals: ''' This popup has provides four options because of the many different ways in which 3D software applications, exporters and modeling techniques are used to create geometry and MDD files. The MDD files and shaders assigned to the '''Read MDD file (motion)''' and '''Mesh displacer''' parameters change the base 3D object’s normals, requiring them to be recomputed in order to render correctly. The '''Recalculate Normals''' parameter instructs Terragen how to recompute the normals.</li>
[[File:OBJReader_41_MeshModifiersTab_RecalcNormalsParams.png|none|378px|Recalculate Normal options.]]
<ul>
<li>No: The normals are unchanged and left as they were in the original Wavefront OBJ, Lightwave LWO, or Terragen TGO formatted object.</li>
<li>Conservative Update: Only the existing normals are updated. In other words, it relies on the normals to have been mapped to faces in a meaningful way in the original object. Each recalculated normal is the average of the normals of the faces that use the normal. The benefits to this method is it is fast and preserves creases where edges use per-face normals in the original scene. The drawbacks are that this method cannot create a smooth surface if the normals are not shared between faces, and it cannot create normals where they didn't previously exist.</li>
<li>Smooth + preserve creases: Similar to "Conservative update" except that it preprocesses the model to merge any duplicate normals. After doing this it recalculates each normal using the average of the normals of the faces that use the normal. The benefits of this method is that it preserves creases where edges used per-face normals in the original model. The drawbacks are that this method cannot create normals where they didn't previously exist.</li>
<li>Smooth everything: All the prior normals are cleared. A new normal is created for every vertex. Each normal is the average of the normals of the faces that use the vertex, therefore it creates a smooth appearance across faces that share vertices with other faces. The benefits to this method is that it works with models that didn't define any normals beforehand. The drawbacks are that this method does not produce sharp edges unless the faces use separate vertices.</li>

{|
|-
|[[File:OBJReader_MeshModifier_RecalcNormals_SmoothPreserveCreases.png|none|400px|Normals recalculated with Smooth + Preserve creases.]] || [[File:OBJReader_MeshModifier_RecalcNormals_SmoothEverything.png|none|400px|Normals recomputed with Smooth Everything.]]
|}

</ul> 
== Surface Shaders Tab ==
[[File:OBJReader_19_SurfaceShadersTab.png|none|460px|Surface Shaders Tab]]

This tab lets you assign a surface shader to texture the object. If there was a .mtl file associated with the OBJ file, a Parts Shader with its associated nodes will be created and assigned to the Surface shader input.

'''Settings:''' 
<ul>
<li>'''Surface shader:''' Use this parameter to assign a surface shader to the object. </li>

<li>'''Displacement tolerance''' If you find that rough or spikey surfaces are showing problems at bucket edges, for example spikes having cut off tops, or gaps in ray traced shadows then increasing this value may help. However this can greatly increase render times. Relatively flat surfaces may render more quickly with smaller values. The default value is 1. However this is an advanced setting and you should not change it unless you have specific problem you need to address. If you are having problems try starting with 2 and then increase it by small increments until they're resolved. A value of 4 would be considered a high value. </li>

<li>'''Smooth polygons at terminator:''' This fixes self-shadow artifacts at the lighting terminator of polygonal objects where the smooth normals are inconsistent with the geometric normal. This parameter is enabled by default.</li>

<li>'''Darken bumps at terminator:''' This parameter approximates self-shadow of bump maps at the lighting terminator to reduce the chance of seeing a sharp line where the surface falls into shadow. This parameter is enabled by default.</li>
</ul>

{|
|-
| [[File:OBJReader_49_SmoothPolysAtTerminator.jpg|none|400px|Smooth polygon at terminator comparison.]] || [[File:OBJReader_50_DarkenBumpsAndSmoothPolys.jpg|none|400px|Darken bumps at terminator comparison. ]]
|}
 

== Rendering Tab ==
[[File:OBJReader_24_RenderingTab.png|none|461px|Rendering Tab]]

'''Settings:''' 
<ul>
<li>'''Render mode:''' An object's render state can be set to Visible, Invisible or Holdout. When set to Holdout, an object is visible in the rendered image as a black shape with an alpha value of zero. When using render layers the object's render state is combined with the group visibility parameter to determine its least visible setting. Invisible is less visible than Holdout, which is less visible than Visible. </li>
[[File:OBJReader_25_RenderingTab_RenderType.png|none|148px|Object's render types.]]

<li>'''Visible to other rays:''' When enabled, the object will be taken into account by all the rays determined by the renderer including those from the camera, direct and indirect lighting, etc. In the example below, a 100% reflective 3D object has been placed behind three coloured spheres in order to mirror the effect of the calculated rays.
 

<li>'''Cast shadows:''' This should be checked if you want the object to cast shadows.

<li>'''Double-sided surface:''' If this is checked object surfaces are double sided. A single sided surface is only visible from the "front", which is the direction the surface normal is pointing. If you look at it from the other direction the surface isn't visible. Double sided surfaces are visible from all directions.</li>

<li>'''Use smooth normals:''' If this is checked the object normals are interpolated to make the surface appear smooth. If it's unchecked the surface will look faceted.</li>

<li>'''Flip normals:''' Check this to flip or reverse the object normals. You might want to use this on an imported object if it has gaps or strange dark patches when rendered.</li>

<li>'''Render method''' This popup has three options.
[[File:OBJReader_36_RenderingTab_RenderMethod.png|none|340px|Render method options]]</li>
<ul>
<li>Default: Ray Tracing is the default rendering method for an object. Typically it results in higher quality and faster rendering. When displacement is applied to a 3D object the render method should be changed to Force Displacement. When the object's render method is set to Default, the object is rendered according to the '''Ray trace objects''' setting in the render node.</li>
<li>Force Displacement: When enabled for the object, its surfaces will be subdivided into micropolygons at render time, which allows the 3D geometry to be displaced correctly but at the expense of slightly longer render times.
It is useful when you have some objects you want to render with displacement but you don't want to change how all the rest of your objects are rendered, i.e. Ray traced. </li>
<li>Force Ray Trace: When enabled for the object, its surfaces will be ray traced at render time, even if '''Ray trace objects''' is disabled in the Renderer settings. This can be useful when '''Ray trace objects''' is disabled in the Renderer in order for other 3D objects to use displacement, but you want this object to use ray tracing for the highest quality rendering and it has not been displaced. </li>
</ul>

<li>'''Sorting bias (metres)''' This parameter gives you control over the order in which objects are rendered when using the micropolygon renderer. This does not apply to objects being rendered with the ray tracer.
A large positive value, e.g. 10,000,000 (or 1e7) will usually force the object to render first. A large negative value, e.g. -10,000,000 (or -1e7) will usually force the object to render last, or after the terrain. This can be useful when rendering large objects with displacement, such as a lake object that lies mostly below the displaced terrain. By setting the lake object’s '''Sorting bias (metres)''' value to something like -10,000,000 forces it to render after the terrain.</li>
</ul>
{|
|-
| [[File:OBJReader_60_RenderingTab_VisibleToOtherRays.gif|none|400px|Visible to other rays comparison.]] || [[File:OBJReader_61_RenderTab_CastShadows.gif|none|400px|Cast shadows comparison.]]
|}
 

== Transform Tab ==
[[File:OBJReader_37_TransformTab.png|none|455px|Transform tab.]]

'''Settings:''' 
<ul>
<li>'''Translate:''' This sets the position of the object.</li>
<li>'''Rotate:''' This rotates the object about its origin. The order of the values is heading, pitch then bank.</li>
<li>'''Scale:''' You can use this parameter to scale the object in the X, Y and Z directions. </li>
</ul>
 

== Angular Position Tab ==
[[File:OBJReader_38_AngularPositionTab.png|none|455px|Angular Position Tab.]]

This tab has settings which use angles and distance to set the position of the rock relative to the scene origin. These settings are an alternative to using the Translate setting in the Transform tab. The diagram below shows how all the parameters relate to each other and the origin.

'''Settings:''' 
<ul>
<li>'''Heading:''' This angle sets the rotation of the object around the scene origin, in the XY plane, increasing as you turn clockwise. </li>
<li>'''Elevation:''' This angle sets the vertical part of the position. You could think of it as the angle above or below the horizon. 90 is straight up, -90 is straight down. </li>
<li>'''Distance:''' This sets the distance from the origin, in metres. </li>
</ul>

[[File:Angular_position.gif|none|218px|Angular positions]]
 

== Import Tab ==
[[File:OBJReader_39_ImportTab.png|none|455px|Import Tab.]]

These parameters apply to .chan/.mov and FBX import.

'''Settings:'''
<ul>
<li>'''Import offset:''' This setting allows you to offset the positions imported from the file. As an example, you might want the positions imported from the file to be moved 10 metres in the X direction. To do that enter 10 for the X coordinate and import the file. </li>
<li>'''Import scale:''' You can use this setting to scale values imported from the file. </li>
<li>'''Import Chan file:''' This param specifies the file to be imported. When you a choose a new file you will be prompted to import the file. If you choose not to import it immediately you can click the Import chan File button to perform the import. </li>
</ul>
 

== OBJ Options Tab ==
[[File:OBJReader_40_OBJOptionsTab.png|none|455px|OBJ Options Tab.]]

This tab contains settings which are specific to loading OBJ files.

'''Settings:'''
<ul>
<li>'''Source in cm:''' If this is checked then Terragen interprets the measurement units in the OBJ file as being in centimetres. That's the theory, but there is currently a bug which means the units are interpreted as 10cm (decimetre) rather than 1cm. You may still need to scale the object using the Transform tab to make it the correct size. </li>
<li>'''Source Z up:''' Check this if you know the OBJ file uses Z up as opposed to Y up, which Terragen uses. This will cause the coordinates to be swapped when read from the file to match Terragen's coordinate system. If the model seems to be laying over on its side when imported you probably need to check this setting. </li>
</ul>

OBJ Reader

2025-11-02T21:52:29Z

Matt: Minor correction to my previous edit of Sequence first/last parameters

[[File:OBJReader_00_GUI.png|none|470px|OBJ Reader]]
 
== Overview ==

The OBJ Reader node loads models from a Wavefront .OBJ file. The OBJ Reader can also load .mtl files specified by the OBJ containing texturing information. When you create an OBJ Reader it opens a file dialog allowing you to choose the file to load.

'''Node Type:''' Object 

'''Settings:''' 

<ul>
<li>
'''Population mode:''' This popup has two options:

[[File:OBJReader_01_PopulationMode.png|none|322px|Population mode parameters]]

<ul><li>Individual Object: This is the default for objects created individually, not part of a population. If you choose this option for objects that are part of a population the population instances will still render but the object itself will also show up at its original position. </li>
<li>Member of a Population: This is the default for objects created as part of creating a population. It means the objects only render as part of a population. If you choose this option for an individual object it won't render. If you create an object as part of a population and then decide to use it on its own you may need to change the popup to Individual Object to get it to render.</li></ul>

<li>'''Preview mode:''' This popup has five options to let you choose how the object should be displayed in the 3D Preview, and sets the most detailed mode that the object can be displayed in. The '''Object Display Mode''' button in the 3D Preview controls the mode for the preview as a whole. For example, if you set the '''Preview mode''' of the object to '''Wireframe''' but the 3D Preview object display mode is set to '''Show as bounding boxes''' then the object will only be drawn as a bounding box.</li>
[[File:OBJReader_02_PreviewMode.png|none|234px|Preview Mode parameters]]

<li>''' Preview Colour:''' Enabling this parameter causes the object to be drawn in the 3D preview using the preview colour when the object display mode is set to '''Show as bounding box''' or '''Show as wireframe'''. When set to '''Show as smooth shaded''' or '''Show as textured''' the preview colour tints the object’s textured surface. This is useful for making a particular object stand out in the 3D preview. Clicking on the colour swatch to the right of the parameter label opens the [[Colour_Picker|Colour picker pane]].
</li>
 </ul>
== File Read Tab ==
[[File:OBJReader_03_FileReadTab.png|none|460px|File Read Tab]]

'''Settings:'''
<ul><li>'''Filename:''' This parameter shows the path to the file used by the OBJ Reader. You can use the file button at right to load a different file but this isn't recommended as the materials for the new file won't be loaded. To use an OBJ file sequence you can use a limited set of C-style format strings to automatically insert the frame number, for example "MyObject_%04d.obj" may result in "MyObject_0023.obj" on frame 23, depending on the options on the Sequence tab.</li></ul>
 
== Sequence Tab ==
[[File:OBJReader_04_SequenceTab.png|none|460px|Sequence Tab]]
'''Settings:'''
<ul><li>'''Sequence first:''' When a supported frame insertion pattern is used in the filename parameter to load a file sequence, '''Sequence first''' and '''Sequence last''' control the range of numbers that are allowed in the file sequence. For example, if you have files with names MyObject_0001.obj to MyObject_0010.obj and want your animation to use them all, you would set '''Sequence first''' and '''Sequence last''' to 1 and 10 respectively.</li>
<li><li>'''Sequence last:''' When a supported frame insertion pattern is used in the filename parameter to load a file sequence, '''Sequence first''' and '''Sequence last''' control the range of numbers that are allowed in the file sequence. For example, if you have files with names MyObject_0001.obj to MyObject_0010.obj and want your animation to use them all, you would set '''Sequence first''' and '''Sequence last''' to 1 and 10 respectively.</li>
<li>'''Frame offset:''' This value provides a way to load files with sequential numbers that are different from the rendered frame numbers, to shift the timing of the animation or to account for differences in how the frames are numbered in the object filenames. Terragen adds '''Frame offset''' to the project's current frame number to determine which file number to load (with the actual file number being limited to the range defined by '''Sequence first''' and '''Sequence last''' with optional looping or ping-ponging). For example, if the '''Sequence first''' value is "1", the '''Sequence last''' value is "10", and the '''Offset''' value is "4", then MyObject_0005.obj would be loaded on frame 1, MyObject_0006.obj on frame 2, etc. Negative offsets can be used. For example, if the '''Offset''' value is "-1000" (negative), then MyObject_0001.obj would be loaded on frame 1001, MyObject_0002.obj on frame 1002, etc.</li>
<li>'''Loop or Ping Pong:''' After Terragen applies '''Offset''' to the current frame number, if the resulting frame number falls outside the range defined by '''Sequence first''' and '''Sequence last''' then '''Loop''' and '''Ping Pong''' are two different ways extend the cycle infinitely, both before the beginning and after the end of the sequence. Upon completion of the sequential object cycle determined by the '''Sequence first''' value and '''Sequence last''' value, the objects can either “loop” back to the '''Sequence first''' object and cycle through the objects as each frame advances, or “ping pong”, that is, reverse the object sequence order until the '''Sequence first''' object is encountered. If neither '''Loop''' nor '''Ping Pong''' are checked then the object will be held at the first or last file in the sequence when the requested frame number falls outside the defined range.</li>
[[File:OBJReader_45_OBJSequence.gif|none|400px|Object sequence options.]]
</ul>

 

== Mesh Modifiers Tab ==
[[File:OBJReader_12_MeshModifiersTab3.png|none|460px|Mesh Modifiers Tab]]
'''Settings:'''

<ul>
<li>'''Read MDD file (motion):''' Terragen can apply Motion Designer or “MDD” files created in third-party 3D software packages to an object within the project. The MDD file contains the position of every vertex in an object, for each frame of an animation. After an object is animated or otherwise deformed in the third-party 3D software, its vertex positions are “baked”, or saved in the MDD file format. This allows for complex animation to exist within a Terragen project, that otherwise could not.</li>
{|
|-
| [[File:OBJReader_52_MDD_Flag.gif|none|400px|MDD file cloth simulation.]] || [[File:OBJReader_51_MDD_Bat.gif|none|400px|MDD animated flap cycle.]]
|} 
<li>'''Reverse Z (right handed): ''' If the MDD file is facing in the wrong direction, you can reverse the Z axis in order to point it in the right direction.</li>
[[File:OBJReader_47_ReverseZ_Bat.gif|none|400px|Effect of enabling the Reverse Z (right handed) parameter.]] 
<li>'''Mesh displacer:''' The shader assigned to this parameter displaces the object’s vertices (mesh). For example, a power fractal shader can be used to displace the vertices of the 3D object or a population. The denser the object’s geometry, or more vertices it has, allows for more subtle deformations to be visible.</li>
{|
|-
| [[File:OBJReader_15_MeshModifiersTab_MeshDisplacer_Cattail.gif|none|400px|Animated parameters on a power fractal to deform a single 3D object.]] || [[File:OBJReader_16_MeshModifiersTab_MeshDisplacer_Population.gif|none|400px|Animated parameters on a power fractal to deform a population.]]
|-
| [[File:OBJReader_48_MeshDisplacer_NonShadered.PNG|none|400px|Displacement applied to non-shadered objects.]] || [[File:OBJReader_18_MeshModifiersTab_MeshDisplacer_TexturedLeafs2.PNG|none|400px|Displacement applied to textured objects.]]
|}
 

<li>'''Recalculate Normals: ''' This popup has provides four options because of the many different ways in which 3D software applications, exporters and modeling techniques are used to create geometry and MDD files. The MDD files and shaders assigned to the '''Read MDD file (motion)''' and '''Mesh displacer''' parameters change the base 3D object’s normals, requiring them to be recomputed in order to render correctly. The '''Recalculate Normals''' parameter instructs Terragen how to recompute the normals.</li>
[[File:OBJReader_41_MeshModifiersTab_RecalcNormalsParams.png|none|378px|Recalculate Normal options.]]
<ul>
<li>No: The normals are unchanged and left as they were in the original Wavefront OBJ, Lightwave LWO, or Terragen TGO formatted object.</li>
<li>Conservative Update: Only the existing normals are updated. In other words, it relies on the normals to have been mapped to faces in a meaningful way in the original object. Each recalculated normal is the average of the normals of the faces that use the normal. The benefits to this method is it is fast and preserves creases where edges use per-face normals in the original scene. The drawbacks are that this method cannot create a smooth surface if the normals are not shared between faces, and it cannot create normals where they didn't previously exist.</li>
<li>Smooth + preserve creases: Similar to "Conservative update" except that it preprocesses the model to merge any duplicate normals. After doing this it recalculates each normal using the average of the normals of the faces that use the normal. The benefits of this method is that it preserves creases where edges used per-face normals in the original model. The drawbacks are that this method cannot create normals where they didn't previously exist.</li>
<li>Smooth everything: All the prior normals are cleared. A new normal is created for every vertex. Each normal is the average of the normals of the faces that use the vertex, therefore it creates a smooth appearance across faces that share vertices with other faces. The benefits to this method is that it works with models that didn't define any normals beforehand. The drawbacks are that this method does not produce sharp edges unless the faces use separate vertices.</li>

{|
|-
|[[File:OBJReader_MeshModifier_RecalcNormals_SmoothPreserveCreases.png|none|400px|Normals recalculated with Smooth + Preserve creases.]] || [[File:OBJReader_MeshModifier_RecalcNormals_SmoothEverything.png|none|400px|Normals recomputed with Smooth Everything.]]
|}

</ul> 
== Surface Shaders Tab ==
[[File:OBJReader_19_SurfaceShadersTab.png|none|460px|Surface Shaders Tab]]

This tab lets you assign a surface shader to texture the object. If there was a .mtl file associated with the OBJ file, a Parts Shader with its associated nodes will be created and assigned to the Surface shader input.

'''Settings:''' 
<ul>
<li>'''Surface shader:''' Use this parameter to assign a surface shader to the object. </li>

<li>'''Displacement tolerance''' If you find that rough or spikey surfaces are showing problems at bucket edges, for example spikes having cut off tops, or gaps in ray traced shadows then increasing this value may help. However this can greatly increase render times. Relatively flat surfaces may render more quickly with smaller values. The default value is 1. However this is an advanced setting and you should not change it unless you have specific problem you need to address. If you are having problems try starting with 2 and then increase it by small increments until they're resolved. A value of 4 would be considered a high value. </li>

<li>'''Smooth polygons at terminator:''' This fixes self-shadow artifacts at the lighting terminator of polygonal objects where the smooth normals are inconsistent with the geometric normal. This parameter is enabled by default.</li>

<li>'''Darken bumps at terminator:''' This parameter approximates self-shadow of bump maps at the lighting terminator to reduce the chance of seeing a sharp line where the surface falls into shadow. This parameter is enabled by default.</li>
</ul>

{|
|-
| [[File:OBJReader_49_SmoothPolysAtTerminator.jpg|none|400px|Smooth polygon at terminator comparison.]] || [[File:OBJReader_50_DarkenBumpsAndSmoothPolys.jpg|none|400px|Darken bumps at terminator comparison. ]]
|}
 

== Rendering Tab ==
[[File:OBJReader_24_RenderingTab.png|none|461px|Rendering Tab]]

'''Settings:''' 
<ul>
<li>'''Render mode:''' An object's render state can be set to Visible, Invisible or Holdout. When set to Holdout, an object is visible in the rendered image as a black shape with an alpha value of zero. When using render layers the object's render state is combined with the group visibility parameter to determine its least visible setting. Invisible is less visible than Holdout, which is less visible than Visible. </li>
[[File:OBJReader_25_RenderingTab_RenderType.png|none|148px|Object's render types.]]

<li>'''Visible to other rays:''' When enabled, the object will be taken into account by all the rays determined by the renderer including those from the camera, direct and indirect lighting, etc. In the example below, a 100% reflective 3D object has been placed behind three coloured spheres in order to mirror the effect of the calculated rays.
 

<li>'''Cast shadows:''' This should be checked if you want the object to cast shadows.

<li>'''Double-sided surface:''' If this is checked object surfaces are double sided. A single sided surface is only visible from the "front", which is the direction the surface normal is pointing. If you look at it from the other direction the surface isn't visible. Double sided surfaces are visible from all directions.</li>

<li>'''Use smooth normals:''' If this is checked the object normals are interpolated to make the surface appear smooth. If it's unchecked the surface will look faceted.</li>

<li>'''Flip normals:''' Check this to flip or reverse the object normals. You might want to use this on an imported object if it has gaps or strange dark patches when rendered.</li>

<li>'''Render method''' This popup has three options.
[[File:OBJReader_36_RenderingTab_RenderMethod.png|none|340px|Render method options]]</li>
<ul>
<li>Default: Ray Tracing is the default rendering method for an object. Typically it results in higher quality and faster rendering. When displacement is applied to a 3D object the render method should be changed to Force Displacement. When the object's render method is set to Default, the object is rendered according to the '''Ray trace objects''' setting in the render node.</li>
<li>Force Displacement: When enabled for the object, its surfaces will be subdivided into micropolygons at render time, which allows the 3D geometry to be displaced correctly but at the expense of slightly longer render times.
It is useful when you have some objects you want to render with displacement but you don't want to change how all the rest of your objects are rendered, i.e. Ray traced. </li>
<li>Force Ray Trace: When enabled for the object, its surfaces will be ray traced at render time, even if '''Ray trace objects''' is disabled in the Renderer settings. This can be useful when '''Ray trace objects''' is disabled in the Renderer in order for other 3D objects to use displacement, but you want this object to use ray tracing for the highest quality rendering and it has not been displaced. </li>
</ul>

<li>'''Sorting bias (metres)''' This parameter gives you control over the order in which objects are rendered when using the micropolygon renderer. This does not apply to objects being rendered with the ray tracer.
A large positive value, e.g. 10,000,000 (or 1e7) will usually force the object to render first. A large negative value, e.g. -10,000,000 (or -1e7) will usually force the object to render last, or after the terrain. This can be useful when rendering large objects with displacement, such as a lake object that lies mostly below the displaced terrain. By setting the lake object’s '''Sorting bias (metres)''' value to something like -10,000,000 forces it to render after the terrain.</li>
</ul>
{|
|-
| [[File:OBJReader_60_RenderingTab_VisibleToOtherRays.gif|none|400px|Visible to other rays comparison.]] || [[File:OBJReader_61_RenderTab_CastShadows.gif|none|400px|Cast shadows comparison.]]
|}
 

== Transform Tab ==
[[File:OBJReader_37_TransformTab.png|none|455px|Transform tab.]]

'''Settings:''' 
<ul>
<li>'''Translate:''' This sets the position of the object.</li>
<li>'''Rotate:''' This rotates the object about its origin. The order of the values is heading, pitch then bank.</li>
<li>'''Scale:''' You can use this parameter to scale the object in the X, Y and Z directions. </li>
</ul>
 

== Angular Position Tab ==
[[File:OBJReader_38_AngularPositionTab.png|none|455px|Angular Position Tab.]]

This tab has settings which use angles and distance to set the position of the rock relative to the scene origin. These settings are an alternative to using the Translate setting in the Transform tab. The diagram below shows how all the parameters relate to each other and the origin.

'''Settings:''' 
<ul>
<li>'''Heading:''' This angle sets the rotation of the object around the scene origin, in the XY plane, increasing as you turn clockwise. </li>
<li>'''Elevation:''' This angle sets the vertical part of the position. You could think of it as the angle above or below the horizon. 90 is straight up, -90 is straight down. </li>
<li>'''Distance:''' This sets the distance from the origin, in metres. </li>
</ul>

[[File:Angular_position.gif|none|218px|Angular positions]]
 

== Import Tab ==
[[File:OBJReader_39_ImportTab.png|none|455px|Import Tab.]]

These parameters apply to .chan/.mov and FBX import.

'''Settings:'''
<ul>
<li>'''Import offset:''' This setting allows you to offset the positions imported from the file. As an example, you might want the positions imported from the file to be moved 10 metres in the X direction. To do that enter 10 for the X coordinate and import the file. </li>
<li>'''Import scale:''' You can use this setting to scale values imported from the file. </li>
<li>'''Import Chan file:''' This param specifies the file to be imported. When you a choose a new file you will be prompted to import the file. If you choose not to import it immediately you can click the Import chan File button to perform the import. </li>
</ul>
 

== OBJ Options Tab ==
[[File:OBJReader_40_OBJOptionsTab.png|none|455px|OBJ Options Tab.]]

This tab contains settings which are specific to loading OBJ files.

'''Settings:'''
<ul>
<li>'''Source in cm:''' If this is checked then Terragen interprets the measurement units in the OBJ file as being in centimetres. That's the theory, but there is currently a bug which means the units are interpreted as 10cm (decimetre) rather than 1cm. You may still need to scale the object using the Transform tab to make it the correct size. </li>
<li>'''Source Z up:''' Check this if you know the OBJ file uses Z up as opposed to Y up, which Terragen uses. This will cause the coordinates to be swapped when read from the file to match Terragen's coordinate system. If the model seems to be laying over on its side when imported you probably need to check this setting. </li>
</ul>

OBJ Reader

2025-11-02T21:47:29Z

Matt: Updated explanations of Sequence parameters, and added mention of C-style format strings for the filename parameter.

[[File:OBJReader_00_GUI.png|none|470px|OBJ Reader]]
 
== Overview ==

The OBJ Reader node loads models from a Wavefront .OBJ file. The OBJ Reader can also load .mtl files specified by the OBJ containing texturing information. When you create an OBJ Reader it opens a file dialog allowing you to choose the file to load.

'''Node Type:''' Object 

'''Settings:''' 

<ul>
<li>
'''Population mode:''' This popup has two options:

[[File:OBJReader_01_PopulationMode.png|none|322px|Population mode parameters]]

<ul><li>Individual Object: This is the default for objects created individually, not part of a population. If you choose this option for objects that are part of a population the population instances will still render but the object itself will also show up at its original position. </li>
<li>Member of a Population: This is the default for objects created as part of creating a population. It means the objects only render as part of a population. If you choose this option for an individual object it won't render. If you create an object as part of a population and then decide to use it on its own you may need to change the popup to Individual Object to get it to render.</li></ul>

<li>'''Preview mode:''' This popup has five options to let you choose how the object should be displayed in the 3D Preview, and sets the most detailed mode that the object can be displayed in. The '''Object Display Mode''' button in the 3D Preview controls the mode for the preview as a whole. For example, if you set the '''Preview mode''' of the object to '''Wireframe''' but the 3D Preview object display mode is set to '''Show as bounding boxes''' then the object will only be drawn as a bounding box.</li>
[[File:OBJReader_02_PreviewMode.png|none|234px|Preview Mode parameters]]

<li>''' Preview Colour:''' Enabling this parameter causes the object to be drawn in the 3D preview using the preview colour when the object display mode is set to '''Show as bounding box''' or '''Show as wireframe'''. When set to '''Show as smooth shaded''' or '''Show as textured''' the preview colour tints the object’s textured surface. This is useful for making a particular object stand out in the 3D preview. Clicking on the colour swatch to the right of the parameter label opens the [[Colour_Picker|Colour picker pane]].
</li>
 </ul>
== File Read Tab ==
[[File:OBJReader_03_FileReadTab.png|none|460px|File Read Tab]]

'''Settings:'''
<ul><li>'''Filename:''' This parameter shows the path to the file used by the OBJ Reader. You can use the file button at right to load a different file but this isn't recommended as the materials for the new file won't be loaded. To use an OBJ file sequence you can use a limited set of C-style format strings to automatically insert the frame number, for example "MyObject_%04d.obj" may result in "MyObject_0023.obj" on frame 23, depending on the options on the Sequence tab.</li></ul>
 
== Sequence Tab ==
[[File:OBJReader_04_SequenceTab.png|none|460px|Sequence Tab]]
'''Settings:'''
<ul><li>'''Sequence first:''' When a supported frame insertion pattern is used in the filename parameter to load a file sequence, '''Sequence first''' and '''Sequence last''' control the range of numbers that are allowed in the file sequence. For example, if you have files with names MyObject_0001.obj to object_0010.obj and want your animation to use them all, you would set '''Sequence first''' and '''Sequence last''' to 1 and 10 respectively.</li>
<li><li>'''Sequence last:''' When a supported frame insertion pattern is used in the filename parameter to load a file sequence, '''Sequence first''' and '''Sequence last''' control the range of numbers that are allowed in the file sequence. For example, if you have files with names MyObject_0001.obj to object_0010.obj and want your animation to use them all, you would set '''Sequence first''' and '''Sequence last''' to 1 and 10 respectively.</li>
<li>'''Frame offset:''' This value provides a way to load files with sequential numbers that are different from the rendered frame numbers, to shift the timing of the animation or to account for differences in how the frames are numbered in the object filenames. Terragen adds '''Frame offset''' to the project's current frame number to determine which file number to load (with the actual file number being limited to the range defined by '''Sequence first''' and '''Sequence last''' with optional looping or ping-ponging). For example, if the '''Sequence first''' value is "1", the '''Sequence last''' value is "10", and the '''Offset''' value is "4", then MyObject_0005.obj would be loaded on frame 1, MyObject_0006.obj on frame 2, etc. Negative offsets can be used. For example, if the '''Offset''' value is "-1000" (negative), then MyObject_0001.obj would be loaded on frame 1001, MyObject_0002.obj on frame 1002, etc.</li>
<li>'''Loop or Ping Pong:''' After Terragen applies '''Offset''' to the current frame number, if the resulting frame number falls outside the range defined by '''Sequence first''' and '''Sequence last''' then '''Loop''' and '''Ping Pong''' are two different ways extend the cycle infinitely, both before the beginning and after the end of the sequence. Upon completion of the sequential object cycle determined by the '''Sequence first''' value and '''Sequence last''' value, the objects can either “loop” back to the '''Sequence first''' object and cycle through the objects as each frame advances, or “ping pong”, that is, reverse the object sequence order until the '''Sequence first''' object is encountered. If neither '''Loop''' nor '''Ping Pong''' are checked then the object will be held at the first or last file in the sequence when the requested frame number falls outside the defined range.</li>
[[File:OBJReader_45_OBJSequence.gif|none|400px|Object sequence options.]]
</ul>

 

== Mesh Modifiers Tab ==
[[File:OBJReader_12_MeshModifiersTab3.png|none|460px|Mesh Modifiers Tab]]
'''Settings:'''

<ul>
<li>'''Read MDD file (motion):''' Terragen can apply Motion Designer or “MDD” files created in third-party 3D software packages to an object within the project. The MDD file contains the position of every vertex in an object, for each frame of an animation. After an object is animated or otherwise deformed in the third-party 3D software, its vertex positions are “baked”, or saved in the MDD file format. This allows for complex animation to exist within a Terragen project, that otherwise could not.</li>
{|
|-
| [[File:OBJReader_52_MDD_Flag.gif|none|400px|MDD file cloth simulation.]] || [[File:OBJReader_51_MDD_Bat.gif|none|400px|MDD animated flap cycle.]]
|} 
<li>'''Reverse Z (right handed): ''' If the MDD file is facing in the wrong direction, you can reverse the Z axis in order to point it in the right direction.</li>
[[File:OBJReader_47_ReverseZ_Bat.gif|none|400px|Effect of enabling the Reverse Z (right handed) parameter.]] 
<li>'''Mesh displacer:''' The shader assigned to this parameter displaces the object’s vertices (mesh). For example, a power fractal shader can be used to displace the vertices of the 3D object or a population. The denser the object’s geometry, or more vertices it has, allows for more subtle deformations to be visible.</li>
{|
|-
| [[File:OBJReader_15_MeshModifiersTab_MeshDisplacer_Cattail.gif|none|400px|Animated parameters on a power fractal to deform a single 3D object.]] || [[File:OBJReader_16_MeshModifiersTab_MeshDisplacer_Population.gif|none|400px|Animated parameters on a power fractal to deform a population.]]
|-
| [[File:OBJReader_48_MeshDisplacer_NonShadered.PNG|none|400px|Displacement applied to non-shadered objects.]] || [[File:OBJReader_18_MeshModifiersTab_MeshDisplacer_TexturedLeafs2.PNG|none|400px|Displacement applied to textured objects.]]
|}
 

<li>'''Recalculate Normals: ''' This popup has provides four options because of the many different ways in which 3D software applications, exporters and modeling techniques are used to create geometry and MDD files. The MDD files and shaders assigned to the '''Read MDD file (motion)''' and '''Mesh displacer''' parameters change the base 3D object’s normals, requiring them to be recomputed in order to render correctly. The '''Recalculate Normals''' parameter instructs Terragen how to recompute the normals.</li>
[[File:OBJReader_41_MeshModifiersTab_RecalcNormalsParams.png|none|378px|Recalculate Normal options.]]
<ul>
<li>No: The normals are unchanged and left as they were in the original Wavefront OBJ, Lightwave LWO, or Terragen TGO formatted object.</li>
<li>Conservative Update: Only the existing normals are updated. In other words, it relies on the normals to have been mapped to faces in a meaningful way in the original object. Each recalculated normal is the average of the normals of the faces that use the normal. The benefits to this method is it is fast and preserves creases where edges use per-face normals in the original scene. The drawbacks are that this method cannot create a smooth surface if the normals are not shared between faces, and it cannot create normals where they didn't previously exist.</li>
<li>Smooth + preserve creases: Similar to "Conservative update" except that it preprocesses the model to merge any duplicate normals. After doing this it recalculates each normal using the average of the normals of the faces that use the normal. The benefits of this method is that it preserves creases where edges used per-face normals in the original model. The drawbacks are that this method cannot create normals where they didn't previously exist.</li>
<li>Smooth everything: All the prior normals are cleared. A new normal is created for every vertex. Each normal is the average of the normals of the faces that use the vertex, therefore it creates a smooth appearance across faces that share vertices with other faces. The benefits to this method is that it works with models that didn't define any normals beforehand. The drawbacks are that this method does not produce sharp edges unless the faces use separate vertices.</li>

{|
|-
|[[File:OBJReader_MeshModifier_RecalcNormals_SmoothPreserveCreases.png|none|400px|Normals recalculated with Smooth + Preserve creases.]] || [[File:OBJReader_MeshModifier_RecalcNormals_SmoothEverything.png|none|400px|Normals recomputed with Smooth Everything.]]
|}

</ul> 
== Surface Shaders Tab ==
[[File:OBJReader_19_SurfaceShadersTab.png|none|460px|Surface Shaders Tab]]

This tab lets you assign a surface shader to texture the object. If there was a .mtl file associated with the OBJ file, a Parts Shader with its associated nodes will be created and assigned to the Surface shader input.

'''Settings:''' 
<ul>
<li>'''Surface shader:''' Use this parameter to assign a surface shader to the object. </li>

<li>'''Displacement tolerance''' If you find that rough or spikey surfaces are showing problems at bucket edges, for example spikes having cut off tops, or gaps in ray traced shadows then increasing this value may help. However this can greatly increase render times. Relatively flat surfaces may render more quickly with smaller values. The default value is 1. However this is an advanced setting and you should not change it unless you have specific problem you need to address. If you are having problems try starting with 2 and then increase it by small increments until they're resolved. A value of 4 would be considered a high value. </li>

<li>'''Smooth polygons at terminator:''' This fixes self-shadow artifacts at the lighting terminator of polygonal objects where the smooth normals are inconsistent with the geometric normal. This parameter is enabled by default.</li>

<li>'''Darken bumps at terminator:''' This parameter approximates self-shadow of bump maps at the lighting terminator to reduce the chance of seeing a sharp line where the surface falls into shadow. This parameter is enabled by default.</li>
</ul>

{|
|-
| [[File:OBJReader_49_SmoothPolysAtTerminator.jpg|none|400px|Smooth polygon at terminator comparison.]] || [[File:OBJReader_50_DarkenBumpsAndSmoothPolys.jpg|none|400px|Darken bumps at terminator comparison. ]]
|}
 

== Rendering Tab ==
[[File:OBJReader_24_RenderingTab.png|none|461px|Rendering Tab]]

'''Settings:''' 
<ul>
<li>'''Render mode:''' An object's render state can be set to Visible, Invisible or Holdout. When set to Holdout, an object is visible in the rendered image as a black shape with an alpha value of zero. When using render layers the object's render state is combined with the group visibility parameter to determine its least visible setting. Invisible is less visible than Holdout, which is less visible than Visible. </li>
[[File:OBJReader_25_RenderingTab_RenderType.png|none|148px|Object's render types.]]

<li>'''Visible to other rays:''' When enabled, the object will be taken into account by all the rays determined by the renderer including those from the camera, direct and indirect lighting, etc. In the example below, a 100% reflective 3D object has been placed behind three coloured spheres in order to mirror the effect of the calculated rays.
 

<li>'''Cast shadows:''' This should be checked if you want the object to cast shadows.

<li>'''Double-sided surface:''' If this is checked object surfaces are double sided. A single sided surface is only visible from the "front", which is the direction the surface normal is pointing. If you look at it from the other direction the surface isn't visible. Double sided surfaces are visible from all directions.</li>

<li>'''Use smooth normals:''' If this is checked the object normals are interpolated to make the surface appear smooth. If it's unchecked the surface will look faceted.</li>

<li>'''Flip normals:''' Check this to flip or reverse the object normals. You might want to use this on an imported object if it has gaps or strange dark patches when rendered.</li>

<li>'''Render method''' This popup has three options.
[[File:OBJReader_36_RenderingTab_RenderMethod.png|none|340px|Render method options]]</li>
<ul>
<li>Default: Ray Tracing is the default rendering method for an object. Typically it results in higher quality and faster rendering. When displacement is applied to a 3D object the render method should be changed to Force Displacement. When the object's render method is set to Default, the object is rendered according to the '''Ray trace objects''' setting in the render node.</li>
<li>Force Displacement: When enabled for the object, its surfaces will be subdivided into micropolygons at render time, which allows the 3D geometry to be displaced correctly but at the expense of slightly longer render times.
It is useful when you have some objects you want to render with displacement but you don't want to change how all the rest of your objects are rendered, i.e. Ray traced. </li>
<li>Force Ray Trace: When enabled for the object, its surfaces will be ray traced at render time, even if '''Ray trace objects''' is disabled in the Renderer settings. This can be useful when '''Ray trace objects''' is disabled in the Renderer in order for other 3D objects to use displacement, but you want this object to use ray tracing for the highest quality rendering and it has not been displaced. </li>
</ul>

<li>'''Sorting bias (metres)''' This parameter gives you control over the order in which objects are rendered when using the micropolygon renderer. This does not apply to objects being rendered with the ray tracer.
A large positive value, e.g. 10,000,000 (or 1e7) will usually force the object to render first. A large negative value, e.g. -10,000,000 (or -1e7) will usually force the object to render last, or after the terrain. This can be useful when rendering large objects with displacement, such as a lake object that lies mostly below the displaced terrain. By setting the lake object’s '''Sorting bias (metres)''' value to something like -10,000,000 forces it to render after the terrain.</li>
</ul>
{|
|-
| [[File:OBJReader_60_RenderingTab_VisibleToOtherRays.gif|none|400px|Visible to other rays comparison.]] || [[File:OBJReader_61_RenderTab_CastShadows.gif|none|400px|Cast shadows comparison.]]
|}
 

== Transform Tab ==
[[File:OBJReader_37_TransformTab.png|none|455px|Transform tab.]]

'''Settings:''' 
<ul>
<li>'''Translate:''' This sets the position of the object.</li>
<li>'''Rotate:''' This rotates the object about its origin. The order of the values is heading, pitch then bank.</li>
<li>'''Scale:''' You can use this parameter to scale the object in the X, Y and Z directions. </li>
</ul>
 

== Angular Position Tab ==
[[File:OBJReader_38_AngularPositionTab.png|none|455px|Angular Position Tab.]]

This tab has settings which use angles and distance to set the position of the rock relative to the scene origin. These settings are an alternative to using the Translate setting in the Transform tab. The diagram below shows how all the parameters relate to each other and the origin.

'''Settings:''' 
<ul>
<li>'''Heading:''' This angle sets the rotation of the object around the scene origin, in the XY plane, increasing as you turn clockwise. </li>
<li>'''Elevation:''' This angle sets the vertical part of the position. You could think of it as the angle above or below the horizon. 90 is straight up, -90 is straight down. </li>
<li>'''Distance:''' This sets the distance from the origin, in metres. </li>
</ul>

[[File:Angular_position.gif|none|218px|Angular positions]]
 

== Import Tab ==
[[File:OBJReader_39_ImportTab.png|none|455px|Import Tab.]]

These parameters apply to .chan/.mov and FBX import.

'''Settings:'''
<ul>
<li>'''Import offset:''' This setting allows you to offset the positions imported from the file. As an example, you might want the positions imported from the file to be moved 10 metres in the X direction. To do that enter 10 for the X coordinate and import the file. </li>
<li>'''Import scale:''' You can use this setting to scale values imported from the file. </li>
<li>'''Import Chan file:''' This param specifies the file to be imported. When you a choose a new file you will be prompted to import the file. If you choose not to import it immediately you can click the Import chan File button to perform the import. </li>
</ul>
 

== OBJ Options Tab ==
[[File:OBJReader_40_OBJOptionsTab.png|none|455px|OBJ Options Tab.]]

This tab contains settings which are specific to loading OBJ files.

'''Settings:'''
<ul>
<li>'''Source in cm:''' If this is checked then Terragen interprets the measurement units in the OBJ file as being in centimetres. That's the theory, but there is currently a bug which means the units are interpreted as 10cm (decimetre) rather than 1cm. You may still need to scale the object using the Transform tab to make it the correct size. </li>
<li>'''Source Z up:''' Check this if you know the OBJ file uses Z up as opposed to Y up, which Terragen uses. This will cause the coordinates to be swapped when read from the file to match Terragen's coordinate system. If the model seems to be laying over on its side when imported you probably need to check this setting. </li>
</ul>

Terragen Sky Early Access

2025-10-11T01:36:49Z

Matt: Moved sentence containing "Ctrl+Z"

==Overview==
This is the online documentation for the Early Release version of Terragen Sky.

As features are being added or updated on a daily basis, please consider this documentation to be a work-in-progress.

__TOC__

==Menu Bar==
'''File menu button'''

[[File:90_GUI_FileMenu.jpg|none|740px|File menu.]]

*'''New:''' Starts a new Terragen Sky project with the default values.
*'''Open:''' Opens a previously saved Terragen Sky project.
*'''Save As:''' Saves the current project as a Terragen Sky project.

'''Edit menu button'''

[[File:91_GUI_EditMenu.jpg|none|740px|Edit menu]]

* '''Undo:''' Undo the last operation.
*'''Redo:''' Redo the last operation

'''Dialog menu button'''

[[File:92_GUI_DialogMenu.jpg|none|740px|Dialog menu]]

*'''Reference image:''' Opens the Reference Images and Projections window. This allows you to load an image from disk and project it into the project for reference. Image visibility can be fully opaque, transparent or completely off. The image can be positioned in the project by setting the Altitude, Position, Rotation and Focal length parameters.
<ul>
[[File:94_GUI_ReferenceImage.jpg|none|900px|Reference Image and Projections window.]]
<ul> <br/n>
{|
|-
| [[File:96_GUI_ReferenceImage_Trans.jpg|none|800px|Reference Image set to transparent.]]
|-
| [[File:95_GUI_ReferenceImage_Opaque.jpg|none|800px|Reference Image set to opaque.]]
|-
| [[File:97_GUI_ReferenceImage_SkyPaint.jpg|none|800px|Adding and removing clouds to match the reference image using Sky Paint.]]
|}
</ul>
</ul> <br/n>
*'''Strokes:''' When the Sky Paint workspace is active, this option opens the Edit Mode window. In Edit Mode the size and opacity of brush strokes can be modified, and they can be assigned to different canvases. For more information, see the Sky Paint section below.

'''UI menu button'''
[[File:93_GUI_UIMenu.jpg|none|740px|UI menu. ]]<br/n>
The presets under this menu scale the user interface components accordingly, so that you can adjust the layout to best fit your display device or visual preference.
<ul>

[[File:01_UI_Scale90.jpg|none|800px|UI at 90% ]]<br/n>
[[File:02_UI_Scale300.jpg|none|800px|UI at 300% ]]<br/n>
</ul>

'''Help menu button'''
[[File:94_GUI_HelpMenu.jpg|none|740px|Help menu.]]

* '''Online Documentation:''' Opens the URL for the Terragen Sky documentation in your browser.

* '''SysInfo button''': Displays the system information including OpenGL Renderer and OpenGL Version. Click anywhere outside the information window to close it and return to the main interface.
<ul>
[[File:14_SysInfo.jpg|none|800px|SysInfo display.]]
</ul> <br/n>

* '''License button''': Displays the license information. One year of maintenance is included with the purchase of a perpetual license of Terragen. Click anywhere outside the information window to close it and return to the main interface.
<ul>
[[File:15_LicenseInfo.JPG|none|800px|LicenseInfo display.]]
</ul>

==Resizable Docks==
The left and right docks of the UI are resizable, with optional symmetry between the left and right docks. Dock symmetry can be toggled by holding '''Shift''' while dragging a dock resizer bar.
{|
|-
| [[File:TGSky_20251009_04_UI_Symetry_On.jpg|none|800px|Terragen Sky 2025-10-09 UI with Dock symmetry enabled.]]
|-
| [[File:TGSky_20251009_04_UI_Symetry_Off.jpg|none|800px|Terragen Sky 2025-10-09 UI with Dock symmetry disabled.]]
|}

==Lighting Panel==
{|
|-
| [[File:TGSky_20251009_01_SunDirection.png|none|468px|Terragen 2025-10-09 default Lighting Panel.]] || [[File:TGSky_20251009_05_SunDirection_MulitSuns.PNG|none|468px|Terragen 2025-10-09 Lighting Panel with multiple Sunlights.]]
|}

The lighting panel provides complete control over the Sunlights in your project by means of the Light Sources list, a Sun Direction dial, and parameters for each Sunlight.

You can easily add Sunlights to the project by clicking the “+” button below the Light Sources label. To remove a Sunlight from the list, select it and press the Delete key.

Selecting a Sunlight in the Light Sources list allows you to edit it and any changes are reflected immediately in the UI.

To change the position of a Sunlight, select it from the list then click and drag anywhere in the Sun Direction disk. As a Sunlight nears the edge of the dial its colour in the UI changes to reflect its proximity to the horizon. Note, you can also change the position and elevation of the Sunlight via its parameter rollers, and you can currently change Sunlight 01 by clicking anywhere in the Viewport when the Sky Viewport Tools is set to Sun Position.

The Sun Direction dial also includes a camera frame and viewport rectangle, represented as lighter-shaded areas with black lines.

''' List of Sunlights'''

*'''Light Sources +:''' Clicking the "'''+'''" button adds a new Sunlight to the project. The name of the newly added Sunlight is shown in a list below the button and a visual representation of the Sunlight appears in the Sun Direction disk. To remove a Sunlight from the list and project, select it and press the '''Delete''' key. If only one Sunlight exists in a project it can not be deleted. You can undo the creation and deletion of Sunlights via the Edit menu or by using '''Ctrl+Z''' on the keyboard.

'''Sun Direction Dial'''

*'''Orient to Camera/World:''' The Sun Direction dial can be displayed in camera or world orientation. When the '''Camera''' button is enabled, the camera’s field of view in the Sunlight dial remains facing forward and any Sunlights in the project rotate around the dial as the Camera is rotated or the Panorama Roller is dragged to the left or right. When the '''World''' button is enabled and the camera is rotated, its field of view in the Sun Direction dial rotates around the dial while any Sunlights remain fixed in their position.

*'''Look Up/Down:''' These buttons indicate the way in which you’re viewing the Sun Direction dial; from above it or below it. If you imagine the dial to be the sky '''Up''' indicates that you’re below the sky looking up at it, while '''Down''' indicates you’re above the sky looking down at it.

''' Sunlight Parameters'''

*'''Heading:''' This parameter sets the heading of the sun in degrees. You can think of 0° as North, +90° as East, +-180° as South, and -90° as West. The parameter can be used as a slider with a range of -180 to +180 degrees, or by clicking on the numerical value to directly input an amount.

*'''Elevation:''' This parameter sets the elevation of the sun in degrees. You can think of 0° being directly on the horizon, +90° being directly overhead, and -90° being on the underside of the planet. When negative values are used to simulate a night sky, you can compensate for the darkness by increasing the Exposure value. The parameter can be used as a slider with a range of -90 to +90 degrees, or by clicking on the numerical value to directly input an amount.

*'''Colour:''' This parameter sets the colour of the selected Sunlight. The input allows you to set the value for the individual red, green and blue components that make up the Sunlight’s colour. Negative values are allowed. In the Sun Direction dial, the colour of the Sunlight will change as the colour value is changed.

*'''Strength:''' This parameter sets the intensity of the Sunlight. The default strength value is 5.

*'''Diameter:''' This parameter sets the diameter of the selected Sunlight’s disk. As the value is changed, the Sun Direction dial will automatically update to show the size of the Sunlight disk. A visible Sunlight disk can be included or excluded from a rendered image by checking the “Save with sun” checkbox under the Renders tab and saving the rendered image.

*'''Soft shadow:''' When checked the renderer will calculate soft shadows for the selected Sunlight based on the Sunlight's diameter. This can take longer to render but is more accurate.
 

==Sky Viewport Tools==
[[File:04_SkyViewport.jpg|none|245px|Sky Viewport Tools.]]

*'''Sun Position:''' When active, clicking in the main viewport repositions the sun to that location, updating the Sun heading and elevation values.

*'''Exposure:''' When active, clicking and dragging in the main viewport changes the camera’s exposure value, simulating the response to light a real camera might have. Dragging to the right increases the exposure value and brightens up the image as more light reaches the film. Dragging to the left decreases the exposure value and darkens the image, much like stopping down the camera lens aperture from f/2 to f/4. Right-click the exposure button to open a context menu which has the option to reset the exposure value to default.
<ul>
[[File:16_SkyViewportTools_ExposureReset.jpg|none|450px|Exposure reset.]]
</ul>

*'''Camera Zoom:''' When active, clicking and dragging in the main viewport changes the camera’s focal length, which can also be seen in the Camera Focal length parameter.
<ul>
[[File:19_CameraZoom_Reset.JPG|none|549px|Right click on the Camera Zoom button to reset the camera zoom. ]] 
[[File:20_CameraZoomFocalLengths0001.jpg|none|800px|Various camera focal lengths.]]
</ul>

==Cloud Height Diagram==
The Cloud Height Diagram provides a visual and alternate way of positioning the cloud and haze layers, and camera. Moving an item within the diagram adjusts its altitude. When one item’s altitude overlaps with another their indicators appear side by side.

{|
|-
| [[File:21_CloudHeightDiagram_Default.jpg|none|266px|Default Cloud heights. ]] || [[File:22_CloudHeightDiagram_Overlap.jpg|none|266px|Overlapping Cloud heights. ]] || [[File:23_CloudHeightDiagram_Staggered.jpg|none|266px|Staggard Cloud heights. ]]
|}

==Camera==
[[File:05_UI_CameraeLens.jpg|none|470px|The Camera.]]

*'''Altitude:''' This parameter controls the height of the virtual camera. Dragging the slider to the right increases the altitude of the camera and updates the preview window and Cloud Height Diagram, while dragging to the left decreases the camera’s altitude.

*'''Position:''' This parameter controls the position of the virtual camera in the scene. XYZ position values may be modified by dragging the sliders to the left or right, or by directly clicking on a value and entering a new numeric value.

*'''Rotation phb:''' This parameter controls the rotation of the virtual camera in the scene. Pitch, heading, and bank values may be modified by dragging the sliders to the left or right, or by directly clicking on a value and entering a new numeric value.

*'''Focal length:''' This parameter controls the focal length of the virtual camera lens and is the equivalent to the focal length of a real camera lens. The parameter includes a slider ranging from 0 mm to 300 mm, and a numerical input field in which you can enter any value.

==Panorama and Panorama Roller==

The Panorama displays a “lat-long” (spherical) image or a cube map overview of the entire environment. The overlaid text provides information about the type and resolution of the environment map, whose resolution depends on the Terragen Sky mode selected. Dragging the grey roller below the Panorama rotates the environment from -180° to +180°. Clicking with the RMB resets the rotation value to 0. .

[[File:23_Panoramic_LatLong.jpg|none|800px|The Panorama view displaying LatLong information. ]] 
[[File:24_Panoramic_CubeMap.jpg|none|800px|The Panorama view displaying CubeMap information.]]

==Viewport==
The viewport is the main display of the UI. The Alt key + mouse buttons and dragging in the viewport will change the view. These are similar to the default bindings in Terragen 4.

Translate forwards/backwards (dolly): Alt+MMB, or Alt+Shift+LMB
Translate up/down/left right: Alt+RMB, or Alt+Ctrl+LMB

Pressing the Esc key resets the camera’s position and rotation to the values they had when the project was loaded, or created in the case of using New Project.

Below the viewport is the status bar, which displays helpful information, such as the name of the UI component that the mouse is currently pointed at.

[[File:26_MainViewport.JPG|none|800px|The Viewport.]]

*'''Filmic Tonemap:''' When checked, a tone map is applied to the viewport in much the same way as the Renderers Tonemap settings in Terragen 4. When unchecked, no tone mapping is applied and you may see clipping in the bright areas of the sky.
<ul>
{|
|-
| [[File:27_ToneMapOn.JPG|none|400px|Tonemap checked.]] || [[File:28_ToneMapOff.JPG|none|400px|Tonemap unchecked.]]
|}
</ul>

*'''Enviro map/sphere:''' Inset into the main viewport is an environment shader object.  This chrome sphere can be useful when rotating the environment map in order to see what's behind the camera position. You can drag the object around the viewport by clicking on it with the LMB, or resize it using the MMB.

<ul>

[[File:32_EnviroBall.JPG|none|627px|The chrome sphere.]]
</ul>

==Preview Modes (Camera, Camera+, 360+, 360)==
[[File:52_PreviewMode.jpg|none|602px|Preview modes.]]

'''Camera-Priority Modes:'''

*'''Camera:''' Use this mode when you want to preview the area you’re looking at as quickly as possible. In this mode, whatever you’re looking at is progressively refined up to an internal target resolution and quality.

*'''Camera+:''' In this mode, whatever you’re looking at is progressively refined up to an internal target resolution and quality, then the rest of the 360° view is updated and refined until everything is at the internal target resolution and quality.

'''360/Lighting-Priority Modes:'''

*'''360 +:''' Use this mode when you want an approximate 360° render as quickly as possible (e.g. for lighting) but you also want to refine the area within the camera’s view. In this mode, the entire 360° view is first updated to a minimum resolution, then whatever you’re looking at is refined to the internal target resolution and quality, and finally the rest of the 360° view is updated and refined until everything is at the internal target resolution and quality.

*'''360:''' Use this mode when you want a 360° view as quickly as possible (e.g. for lighting). In this mode, the entire 360° view is updated at a uniform resolution.

==Sky Parameters==
The Sky parameters consist of three cloud layers, a Haze layer and an Atmosphere control.

'''Cloud Layers'''


[[File:48_CloudLayer.jpg|597px|Cloud Layer parameters.]]

*'''Layer # (checkbox):''' When checked, the layer is active and will appear in the viewport and in renders.

*'''Presets menu (down chevron):''' When clicked, a list of cloud presets is displayed, allowing you to choose the type of clouds to assign to this cloud layer. See below.

*'''Advanced Settings (right chevron):''' When clicked, the advanced settings for the selected cloud, haze or atmosphere is displayed. This feature is not currently implemented.

*'''Seed:''' This value generates the random aspects of the cloud layer.

*'''Coverage:''' This setting controls the amount of clouds within the cloud layer. Low values reduce the amount of individual clouds and increase the amount of empty space between them. Increasing the value fills up the area with more individual clouds.

*'''Density:''' This setting controls the transparency or opaqueness of the clouds within the cloud layer. Low values make the clouds look thin and let more light pass through them. Higher values make the clouds look thicker and denser, as well as darker because less light passes through them.

*'''Thickness:''' This setting controls the height range of the cloud layer from top to bottom. This corresponds to “Cloud depth” in Terragen 4.

*'''Altitude:''' This setting controls the height of the cloud in metres above sea level. For some cloud types this corresponds to the base of the cloud and for others it corresponds to the mid-point between the base and the top.

'''Presets menu'''

[[File:61_SkyPresets.jpg|none|464px|Presets menu]]

Through the presets menu for Cloud and Haze layers, you have access to the cloud type presets available in Terragen, including Cloud Layer V2, Cloud Layer V3, and Easy Clouds.

*'''High-level:''' These cloud layers default to an altitude of 8,000 metres or more, and are based on Terragen’s Cloud Layer V2 or Easy Clouds presets. When an Easy Cloud preset is selected, you can further choose between Cumulus, Altocumulus Castellanus, and Stratocumulus cloud types under the cloud layer’s advanced settings.

*'''Mid-level:''' These cloud layers default to an altitude around 4,000 metres, and are based on Terragen’s Easy Cloud presets. Under the cloud layer’s advanced settings you can further choose between Cumulus, Altocumulus Castellanus, and Stratocumulus cloud types.

*'''Low-level:''' These cloud layers default to an altitude around 1,500 - 2,000 metres and are based on Terragen’s Easy Cloud presets. Under the cloud layer’s advanced settings you can further choose between Cumulus, Altocumulus Castellanus, and Stratocumulus cloud types.

*'''Haze:''' High-level, Mid-level, and Low-level haze layers are available based on Terragen’s Cloud Layer V2 without a Density shader, tapering or falloff. It provides a volumetric layer in which you can control the density, thickness and altitude.

'''Haze Layer'''

[[File:07_UI_SkyParams_Haze.JPG|none|567px|The Haze layer.]]

Haze is the appearance of moisture and particulates in the atmosphere. It can be used to simulate a broad range of phenomena such as fog, mist, or dry haze caused by dust and smoke. The Haze layer is a layer of uniform haze with a prescribed height range, whereas the Atmosphere is a layer of haze with exponential fall-off with respect to height above sea level.

*'''Haze layer:''' When checked, the haze layer is visible.

*'''Haze density:''' This is the opacity of the haze layer.

*'''Thickness:''' This is the height range of the Haze layer from top to bottom, measured in metres.

*'''Altitude:''' This is the altitude, specified in metres, at which the bottom of the Haze layer begins.

'''Atmosphere'''

[[File:08_UI_SkyParams_Atmo.JPG|none|567px|Atmosphere.]]

*'''Haze density:''' The exponential fall-off of haze in the atmosphere with respect to height above sea level.

'''Other buttons'''

[[File:31_SavePreset.JPG|none|602pox|Save presets button.]]

*'''Save Preset button:''' Clicking this button saves the current settings as a preset, which becomes available in the Presets tab.

==Presets Tab==
[[File:62_PresetsTab.jpg|none|599px|The Presets Tab.]]

The presets tab is a convenient way to access your favorite Terragen Sky settings.

To load a preset, simply click on the thumbnail image in the Presets tab, or right click it and select “Load Preset”.

To save a preset, simply press the Save Preset button located at the bottom of the Sky Parameters, and the new preset will be added to the Preset tab.

User presets and presets from third party sources show up under the User Presets or Unregistered categories.

The Planetside Software Presets category displays the presets that ship with Terragen Sky. You can download them by clicking on the Download button as shown in the image below.

[[File:63_PresetsTabDownloadBrowser.jpg|none|559px|Presets download button.]]

You can also navigate to their installation directory by clicking on the ellipsis button.

[[File:64_PresetsTabOpenFile.jpg|none|599px|Installation directory button]]

== Render Tab ==
[[File:TGSky_20251009_03_Render_AABloom.jpg|none|601px|The Render Tab.]]

The render tab provides controls for the rendered output, including size and quality settings.

*'''Current View & Spherical:''' These settings provide a dropdown menu of standard image resolutions to choose from. The width and height of the rendered image will be set to the chosen resolution.
<ul>
[[File:66_RenderTabResolutions.jpg|none|599px|Composit image of Current and Spherical view resolutions and aspect ratios.]]
</ul>

*'''Quality:''' The quality of the rendered image is governed by the four Q buttons. The higher the Q button value the better the quality of the rendered image, at the expense of a longer render time.

*'''Anti-aliasing bloom:''' When checked this produces a nicer edge on the sun discs in the rendered image. Note that it also increases render times.

*'''Render Image button:''' Click this button to start the render process. When the process is complete, a notification is displayed below the button indicating how long the render took.

*'''Save button:''' Click this button to save the rendered image.

*'''Save with sun:''' When checked, the sun disc is saved in the rendered image. Note that to turn the sun disc on or off, the image does not need to be re-rendered.

*'''Auto-save when finished:''' When checked, the image will automatically be saved upon render.

== Export Tab ==

[[File:67_ExportTab-JSON.jpg|none|599px|The Export Tab]]

The items on the Export tab allow you to save the project as a Terragen clip file or scene file for further use in Terragen 4. Additionally, with Live Send 360, you can immediately save the environment map to a file for access by third party software.

'''Export to Terragen 4'''
*'''Export Clip File:''' Saves the Sky Parameter settings as a clip file which can then be imported into Terragen 4 for further manipulation.

*'''Export Scene file:''' Saves the project, including Sky Parameters, sun and camera, as a scene file which can be opened in Terragen 4 for further manipulation.

'''Live Send 360:''' This feature allows you to export a 2k spherical image to a specific location which is based on the current render state of the viewport, eliminating the need to wait for a final rendered image.

*'''Set Output File:''' Clicking this button brings up a standard file requestor in which to set the filename and path for the Live Send 360 output.

*'''Send Now:''' Clicking this button immediately updates the image defined in Set Output File parameter.

*'''Send Image after loading a preset:''' When checked, the image is immediately updated as soon as a preset is loaded. When unchecked, you need to click the Send Now button.

*'''Send image every “n” seconds:''' When checked, the image is saved to the output file every “n” seconds that you specify.

*'''Send JSON when Sun moves or Env rotates:''' When checked, a JSON file located in the same folder as the output file, is updated with project information such as the Sun’s heading and elevation. Third party applications supporting dynamic updating, like Unreal Engine, can access the information and their project assets can be synced with Terragen Sky.

==Sky Paint Workspace==
The tools and features under the Sky Paint workspace give you precise control of the shapes and positions of your clouds.

[[File:83_AllSkyPaintTools.jpg|none|800 px |The tools and features of the Sky Paint workspace.]]

Clicking on the Sky Paint workspace tab brings up the viewport display menu.

[[File: 74_SkyPaintViewportMenu.jpg | none|470 px|Viewport display menu.]]

You can set the viewport display to side-by-side, top-and-bottom, or to display the painting viewport only.
{|
|-
| [[File: 85_SkyPaintViewportLeftRight.jpg|none|800px|Viewport split set to right and left.]]
|-
| [[File: 75_SkyPaintViewportTopBot.jpg|none|800px|Viewport split set to top and bottom.]]
|-
| [[ File: 76_SkyPaintViewportPaintOnly.jpg|none|800px|Viewport set to Paint only. ]]
|}

'''Canvases:''' 
A canvas is a 360-degree paintable volume which can be painted from multiple viewports. Each project contains multiple canvases.
[[File: 77_Canvas.jpg |none|900 px|When painting in a cloud or haze layer, the paint indicator turns red.]]
By default, the "Paint All" canvas is selected. Paint tools used in this canvas affect all cloud layers and haze layers in the project. This lets you start painting and see immediate results.

There are extra canvases for each cloud layer and haze layer, such as "Cloud 1", "Cloud 2", and "Haze Layer". When painting in these canvases, paint tools are limited to that specific layer.

When a canvas is selected, the “P” paint indicator and Sky parameters for the affected layer will be highlighted in red.

[[File: 78_Canvas_SkyParams.jpg| none|600 px|When painting in a cloud or haze layer, the layer’s Sky parameters are highlighted in red.]]

'''Sky Paint Tools:''' 
The Sky Paint Tools allow you to add, remove and modify the cloud and haze layers in your project. Painting is completely non-destructive and you can edit your strokes at any time. Everything is undoable.
[[File: 82_SkyPaintToolsAndSettings.jpg |none|700 px|Paint strokes are displayed in green when using the Cloud Add tool.]]

* '''Cloud Add''' and '''Cloud Remove''': Paint strokes created with the Cloud Add tool appear in green, while paint strokes created with the Cloud Remove tool are coloured purple. Both tools allow you to set the brush size and opacity. You can use the left “[“ and right “]” bracket keys to change the current tool’s brush size. Paint strokes are grouped together into a layer when their size and opacity are the same. A new layer is created whenever the size or opacity is changed and a new paint stroke is made. You can edit the size and opacity of a paint stroke layer by simply hitting the Space Bar to enter into the Edit mode. Within the Edit mode, you can move paint strokes from one canvas to another.
<ul>
[[File:89_Add-Remove_Cloud.jpg|none|800px|Brush strokes painted with the Cloud Add tool appear green. Strokes painted with the Cloud Remove tool are coloured purple.]]
</ul>

* '''Erase Points''': The Erase Points tool works like an eraser, allowing you to remove individual points of the curve that makes up the brush stroke. With the tool selected, simply left click and drag over the points you want to remove from the curve.
<ul>
[[File: 84_EraseTool.jpg | none|800 px |The Erase tool is used to remove points from the brush stroke.]]
</ul>

* '''Move''': The Move tool allows you to move entire paint stroke layers. Hovering the cursor over the paint strokes will highlight the current paint stroke layer to move.
<ul>
{|
|-
| [[ File: 86_Move_Cloud_Add.jpg |none|800 px |With the Move tool you can rearrange brush stroke curves. Here the Cloud Add curves have been moved.]]
|-
| [[File: 87_Move_Cloud_Remove.jpg |none|800 px |With the Move tool you can rearrange brush stroke curves. Here the Cloud Remove curves have been moved.]]
|}
</ul>

* '''Stir''': The Stir tool allows you to distort the shape of the paint stroke curve. When selected, the tool displays two dotted circles indicating the extent of the distortion effect upon points that fall within. Points of the curve within the inner circle are more intensely affected by the strength of the distortion, which gradually falls off by the outer circle. The “Tool Size” parameter allows you to increase or decrease the area affected by distortion.
<ul>
[[File: 88_Stir_Cloud_Add.jpg |none|800 px |The Stir tool displaces the points of the brush stroke curve.]]
</ul>

'''Edit Mode''': 
Hitting the Space Bar will bring up the Edit Mode. Any canvas having contained a paint stroke will be listed in the Canvas column. The Layers column lists the paint stroke layers for that canvas. You can select an individual layer or use the keyboard shortcuts [K] and [L] to select the previous or next layer. Pressing the [Delete] key will delete the paint stroke layer. If you delete a layer accidentally, you can undo the deletion via the main menu Edit dialog, or pressing Ctl-Z.
With a layer selected you can modify the size of the brush stroke and its opacity.
[[File: 79_EditMode.jpg | none|800 px|Edit mode]]

'''Painting Viewpoints''': 
You can paint from multiple viewpoints. Up to 10 different camera positions can be stored as a viewpoint, and each viewpoint has its own set of cube maps. These are projected into 3D space and intersect with one another to provide a merged solution to where clouds should be added and removed in 3D space.
Painting Viewpoints can be selected with the buttons at the top of the Viewport. You can hover over them to preview viewpoints temporarily without switching to them.
[[File:98_SkyPaint_Viewpoint1.jpg|none|800px|Sky Paint workspace viewed from Viewpoint 1.]]<br/n>
[[File:99_SkyPaint_Viewpoint2.jpg|none|800px|Sky Paint workspace viewed from Viewpoint 2.]]

OpenColorIO

2025-07-30T22:13:41Z

Matt: Replaced "skip forward to step 2" with "skip forward to "Restart Terragen...""

[[File:TG_OCIO_Project_Settings_Colour_Managment.PNG|None|500px|Terragen's Project Settings Colour Management interface]]

=== Overview ===

OpenColorIO (OCIO) is integrated into Terragen 4.5 Professional. It aims to allow you to work with colour spaces consistently with other applications in your pipeline.
{|
|-
| [[File:Wiki_TG45_OCIO_RenderRec709_ViewRec709.jpg|none|400px|Terragen default scene, rendered and viewed in Rec 709 colour space.]] || [[File:Wiki_TG45_OCIO_RenderRec709_ViewACEScg.jpg|none|400px|Terragen default scene, rendered in Rec 709 colour space, viewed in ACEScg colour space.]]
|-
| [[File:Wiki_TG45_OCIO_RenderACEScg_ViewRec709.jpg|none|400px|Terragen default scene, rendered in ACEScg colour space, viewed in Rec 709 colour space.]] || [[File:Wiki_TG45_OCIO_RenderACEScg_ViewACEScg.jpg|none|400px|Terragen default scene, rendered and viewed in ACEScg colour space.]]
|}
 

=== Requirements ===

'''1. Set up OCIO on your computer'''

If you're working at a company that uses OCIO, this has probably already been done for you. There should be an environment variable in your system called OCIO which points to a config.ocio file. If so, don't change the setup; skip forward to "Restart Terragen...".

If you don't have OCIO set up, follow these instructions:



# Download the Reference OCIO Configurations: [https://github.com/imageworks/OpenColorIO-Configs/zipball/master .zip] or [https://github.com/imageworks/OpenColorIO-Configs/tarball/master .tar.gz]. (You can also find them at https://github.com/imageworks/OpenColorIO-Configs)
# Extract the contents of the .zip or .tar.gz file to your computer.
# Decide which configuration you want to use. We recommend the '''aces_1.0.3''' configuration. You should see a file called '''config.ocio''' inside each of the configuration folders.
# Set an environment variable in your system called OCIO. The '''OCIO variable should be set to the full path and filename of the config.ocio file you want to use'''.

'''2. Restart Terragen after you change environment variables that affect OCIO'''

'''3. Enable OCIO in your Terragen project'''

In Terragen, OCIO is enabled or disabled on a ''per-project (per-scene) basis''. Click on '''Project Settings''' at the lower left of the main window, then turn on '''Use OCIO''' if it is not already on.

=== Command Line Arguments (Optional) ===

OCIO can be force-enabled with the command line argument "ocio" or "ocio=yes", as long as there is an environment variable named OCIO pointing to a valid OCIO config file. This command line argument causes Terragen to enable "Use OCIO" in Project Settings at startup and after a project is loaded. Terragen will default to roles which work well with ACES 1.0.3 but might not be compatible with your OCIO configuration, so 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 can be disabled with the command line argument "ocio=no". This causes Terragen to disable "Use OCIO" in Project Settings at startup and after a project is loaded.

=== First Tests ===

Toggling "Use OCIO" in Project Settings should cause the 3D Preview to refresh. If OCIO is configured correctly on your computer then you should also see the colours change in the 3D Preview. The difference may be subtle, but this depends on the OCIO configuration and the default choices for "Rendering space" and "Display space".

When "Use OCIO" is enabled, rendered images should also look different in the Render View.

When rendering with Path Tracer mode and viewing the 3D Preview in RTP mode, be sure to enable “Enable Path Tracing in the 3D Preview” button, above the 3D Preview pane.

[[File:TG_OCIO_RenderView_3DPreview_Settings_v002.jpg|None|867px|Terragen's 3D Preview pane and Render View pane using OCIO colour management and ACES colour space.]]

=== Choosing Colour Spaces ===

'''Rendering space'''

You can change the "Rendering space" but this should usually be "scene_linear" or "rendering". The former is more likely to be compatible with a wide range of OCIO configurations, and this is what Terragen chooses by default.

'''Display space'''

You can change the "Display space", but this should match your monitor. Terragen defaults to whichever display/view the OCIO configuration says is the default. Often this is "sRGB", but if you're unsure what to use then check with the person who set up your OCIO configuration.

'''Shader params (linear)'''

This allows you to choose the colour space that is used by the colour parameters in most shaders, with some exceptions. It doesn't apply to atmosphere parameters, and some other shaders have parameters which are locked to a raw colour space. We'll update this document soon with more details.

You should choose a linear colour space for "shader params (linear)". RGB values stored in Terragen scene files have always been linear, and Terragen automatically applies a gamma of 2.2 when editing colours with the colour picker.

By default, Terragen tries to find a colour space in your OCIO configuration which is linear and uses Rec.709 primaries, based on the name. If it finds a colour space that it thinks is suitable, it maps it to a special built-in role called "linear_rec709" which Terragen always add to the list if it doesn't find a role by that name in your OCIO config. By using this built-in role, our goal is for project files to be portable between different OCIO configurations that have this colour space even if there isn't a standardized name for it. If it makes the wrong choice you will need to choose something more appropriate. Please ensure that you choose a linear colour space for the shader params space.

If you want to change this to a colour space other than linear Rec.709, bear in mind that most assets generated by third parties will have been built assuming linear Rec.709.

'''8-bit textures'''

This allows you to choose the colour space that is used by Image Map Shaders which have "convert to linear" enabled in their options. It is also used by some of the images in the Default Shader.

By default, Terragen tries to find a colour space in your OCIO configuration which has the words "sRGB" and "texture" in its name. If it finds one it maps it to a special built-in role called "sRGB_texture" which Terragen always add to the list if it doesn't find a role by that name in your OCIO config. By using this built-in role, our goal is for project files to be portable between different OCIO configurations that have this colour space even if there isn't a standardized name for it. If it makes the wrong choice you will need to choose something more appropriate.

=== What's Supported in v4.5.43 ===

* You can choose the rendering/working space from the roles defined in the OCIO config. It defaults to "scene_linear", e.g. "scene_linear (ACES - ACEScg)".
* You can choose the display/view space from the displays/views defined in the OCIO config. It defaults to whichever display/view the OCIO config says is the default, e.g. "sRGB (ACES)".
* You can choose the colour spaces used by shader parameters (a linear colour space). It defaults to a special built-in role called "linear_rec709". If it doesn't find this in your OCIO config it tries to guess a suitable colour space by looking at the names of colour spaces in your config.
* You can choose the colour space to interpret 8-bit texture reads (usually sRGB). It defaults to a special built-in role called "sRGB_texture". If it doesn't find this in your OCIO config it tries to guess a suitable colour space using the words "sRGB" and "texture".
* 3D Preview refreshes when toggling OCIO checkbox or changing colour spaces in Project Settings.
* Render View refreshes when toggling OCIO checkbox or changing colour spaces in Project Settings.
* HDR renders are interpreted using whichever "Rendering space" is selected.
* LDR (display) version of the render is the result of tonemapping and transforming the HDR image using whichever "Display space" is selected.
* The Render View displays the LDR (display) version of the rendered image.
* Saving to an LDR file format (e.g. TIFF) saves the LDR (display) version of the image.
* Saving to EXR saves directly from the raw HDR render. Therefore you should interpret EXRs according to whichever "Rendering space" is selected, e.g. "scene_linear (ACES - ACEScg)". We presume this is what you want if you are using Terragen in a multi-app OCIO workflow.

=== Not Yet Supported ===

* Colour space for ''linear'' textures. At the moment, when you check "data is linear" it treats the image as raw data (in the rendering space).
* Choice of colour space per shader or node. In this version, conversion is done the same for all images that have "convert to linear" checked, and individual colour parameters on shaders are predefined to either be convertible or not.
* Independent choice of colour space for internal rendering and file output. Until we add this option, EXRs are output using the scene linear values that were generated by the renderer.

=== Examples ===
The following example uses Terragen's Colour Management with the Academy Color Encoding System (ACES) config profile. Special thanks to Bastien Muller for providing the rendered examples.

[[File:TG_OCIO_Comparision_FusionTerragenNuke_v002.jpg|None|867px|Side-by-side comparision of view-ports in Fusion, Terragen, and Nuke using ACES colour space.]]

OpenColorIO

2025-07-30T22:10:25Z

Matt: Elaborated on what to do if OCIO is already set up.

[[File:TG_OCIO_Project_Settings_Colour_Managment.PNG|None|500px|Terragen's Project Settings Colour Management interface]]

=== Overview ===

OpenColorIO (OCIO) is integrated into Terragen 4.5 Professional. It aims to allow you to work with colour spaces consistently with other applications in your pipeline.
{|
|-
| [[File:Wiki_TG45_OCIO_RenderRec709_ViewRec709.jpg|none|400px|Terragen default scene, rendered and viewed in Rec 709 colour space.]] || [[File:Wiki_TG45_OCIO_RenderRec709_ViewACEScg.jpg|none|400px|Terragen default scene, rendered in Rec 709 colour space, viewed in ACEScg colour space.]]
|-
| [[File:Wiki_TG45_OCIO_RenderACEScg_ViewRec709.jpg|none|400px|Terragen default scene, rendered in ACEScg colour space, viewed in Rec 709 colour space.]] || [[File:Wiki_TG45_OCIO_RenderACEScg_ViewACEScg.jpg|none|400px|Terragen default scene, rendered and viewed in ACEScg colour space.]]
|}
 

=== Requirements ===

'''1. Set up OCIO on your computer'''

If you're working at a company that uses OCIO, this has probably already been done for you. There should be an environment variable in your system called OCIO which points to a config.ocio file. If so, don't change the setup; skip forward to step 2.

If you don't have OCIO set up, follow these instructions:



# Download the Reference OCIO Configurations: [https://github.com/imageworks/OpenColorIO-Configs/zipball/master .zip] or [https://github.com/imageworks/OpenColorIO-Configs/tarball/master .tar.gz]. (You can also find them at https://github.com/imageworks/OpenColorIO-Configs)
# Extract the contents of the .zip or .tar.gz file to your computer.
# Decide which configuration you want to use. We recommend the '''aces_1.0.3''' configuration. You should see a file called '''config.ocio''' inside each of the configuration folders.
# Set an environment variable in your system called OCIO. The '''OCIO variable should be set to the full path and filename of the config.ocio file you want to use'''.

'''2. Restart Terragen after you change environment variables that affect OCIO'''

'''3. Enable OCIO in your Terragen project'''

In Terragen, OCIO is enabled or disabled on a ''per-project (per-scene) basis''. Click on '''Project Settings''' at the lower left of the main window, then turn on '''Use OCIO''' if it is not already on.

=== Command Line Arguments (Optional) ===

OCIO can be force-enabled with the command line argument "ocio" or "ocio=yes", as long as there is an environment variable named OCIO pointing to a valid OCIO config file. This command line argument causes Terragen to enable "Use OCIO" in Project Settings at startup and after a project is loaded. Terragen will default to roles which work well with ACES 1.0.3 but might not be compatible with your OCIO configuration, so 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 can be disabled with the command line argument "ocio=no". This causes Terragen to disable "Use OCIO" in Project Settings at startup and after a project is loaded.

=== First Tests ===

Toggling "Use OCIO" in Project Settings should cause the 3D Preview to refresh. If OCIO is configured correctly on your computer then you should also see the colours change in the 3D Preview. The difference may be subtle, but this depends on the OCIO configuration and the default choices for "Rendering space" and "Display space".

When "Use OCIO" is enabled, rendered images should also look different in the Render View.

When rendering with Path Tracer mode and viewing the 3D Preview in RTP mode, be sure to enable “Enable Path Tracing in the 3D Preview” button, above the 3D Preview pane.

[[File:TG_OCIO_RenderView_3DPreview_Settings_v002.jpg|None|867px|Terragen's 3D Preview pane and Render View pane using OCIO colour management and ACES colour space.]]

=== Choosing Colour Spaces ===

'''Rendering space'''

You can change the "Rendering space" but this should usually be "scene_linear" or "rendering". The former is more likely to be compatible with a wide range of OCIO configurations, and this is what Terragen chooses by default.

'''Display space'''

You can change the "Display space", but this should match your monitor. Terragen defaults to whichever display/view the OCIO configuration says is the default. Often this is "sRGB", but if you're unsure what to use then check with the person who set up your OCIO configuration.

'''Shader params (linear)'''

This allows you to choose the colour space that is used by the colour parameters in most shaders, with some exceptions. It doesn't apply to atmosphere parameters, and some other shaders have parameters which are locked to a raw colour space. We'll update this document soon with more details.

You should choose a linear colour space for "shader params (linear)". RGB values stored in Terragen scene files have always been linear, and Terragen automatically applies a gamma of 2.2 when editing colours with the colour picker.

By default, Terragen tries to find a colour space in your OCIO configuration which is linear and uses Rec.709 primaries, based on the name. If it finds a colour space that it thinks is suitable, it maps it to a special built-in role called "linear_rec709" which Terragen always add to the list if it doesn't find a role by that name in your OCIO config. By using this built-in role, our goal is for project files to be portable between different OCIO configurations that have this colour space even if there isn't a standardized name for it. If it makes the wrong choice you will need to choose something more appropriate. Please ensure that you choose a linear colour space for the shader params space.

If you want to change this to a colour space other than linear Rec.709, bear in mind that most assets generated by third parties will have been built assuming linear Rec.709.

'''8-bit textures'''

This allows you to choose the colour space that is used by Image Map Shaders which have "convert to linear" enabled in their options. It is also used by some of the images in the Default Shader.

By default, Terragen tries to find a colour space in your OCIO configuration which has the words "sRGB" and "texture" in its name. If it finds one it maps it to a special built-in role called "sRGB_texture" which Terragen always add to the list if it doesn't find a role by that name in your OCIO config. By using this built-in role, our goal is for project files to be portable between different OCIO configurations that have this colour space even if there isn't a standardized name for it. If it makes the wrong choice you will need to choose something more appropriate.

=== What's Supported in v4.5.43 ===

* You can choose the rendering/working space from the roles defined in the OCIO config. It defaults to "scene_linear", e.g. "scene_linear (ACES - ACEScg)".
* You can choose the display/view space from the displays/views defined in the OCIO config. It defaults to whichever display/view the OCIO config says is the default, e.g. "sRGB (ACES)".
* You can choose the colour spaces used by shader parameters (a linear colour space). It defaults to a special built-in role called "linear_rec709". If it doesn't find this in your OCIO config it tries to guess a suitable colour space by looking at the names of colour spaces in your config.
* You can choose the colour space to interpret 8-bit texture reads (usually sRGB). It defaults to a special built-in role called "sRGB_texture". If it doesn't find this in your OCIO config it tries to guess a suitable colour space using the words "sRGB" and "texture".
* 3D Preview refreshes when toggling OCIO checkbox or changing colour spaces in Project Settings.
* Render View refreshes when toggling OCIO checkbox or changing colour spaces in Project Settings.
* HDR renders are interpreted using whichever "Rendering space" is selected.
* LDR (display) version of the render is the result of tonemapping and transforming the HDR image using whichever "Display space" is selected.
* The Render View displays the LDR (display) version of the rendered image.
* Saving to an LDR file format (e.g. TIFF) saves the LDR (display) version of the image.
* Saving to EXR saves directly from the raw HDR render. Therefore you should interpret EXRs according to whichever "Rendering space" is selected, e.g. "scene_linear (ACES - ACEScg)". We presume this is what you want if you are using Terragen in a multi-app OCIO workflow.

=== Not Yet Supported ===

* Colour space for ''linear'' textures. At the moment, when you check "data is linear" it treats the image as raw data (in the rendering space).
* Choice of colour space per shader or node. In this version, conversion is done the same for all images that have "convert to linear" checked, and individual colour parameters on shaders are predefined to either be convertible or not.
* Independent choice of colour space for internal rendering and file output. Until we add this option, EXRs are output using the scene linear values that were generated by the renderer.

=== Examples ===
The following example uses Terragen's Colour Management with the Academy Color Encoding System (ACES) config profile. Special thanks to Bastien Muller for providing the rendered examples.

[[File:TG_OCIO_Comparision_FusionTerragenNuke_v002.jpg|None|867px|Side-by-side comparision of view-ports in Fusion, Terragen, and Nuke using ACES colour space.]]

OpenColorIO

2025-07-30T21:55:40Z

Matt: Using https for the links to zip and tar.gz

[[File:TG_OCIO_Project_Settings_Colour_Managment.PNG|None|500px|Terragen's Project Settings Colour Management interface]]

=== Overview ===

OpenColorIO (OCIO) is integrated into Terragen 4.5 Professional. It aims to allow you to work with colour spaces consistently with other applications in your pipeline.
{|
|-
| [[File:Wiki_TG45_OCIO_RenderRec709_ViewRec709.jpg|none|400px|Terragen default scene, rendered and viewed in Rec 709 colour space.]] || [[File:Wiki_TG45_OCIO_RenderRec709_ViewACEScg.jpg|none|400px|Terragen default scene, rendered in Rec 709 colour space, viewed in ACEScg colour space.]]
|-
| [[File:Wiki_TG45_OCIO_RenderACEScg_ViewRec709.jpg|none|400px|Terragen default scene, rendered in ACEScg colour space, viewed in Rec 709 colour space.]] || [[File:Wiki_TG45_OCIO_RenderACEScg_ViewACEScg.jpg|none|400px|Terragen default scene, rendered and viewed in ACEScg colour space.]]
|}
 

=== Requirements ===

'''1. Set up OCIO on your computer'''

If you're working at a company that uses OCIO, this has probably already been done for you.

If you don't have OCIO set up, follow these instructions:



# Download the Reference OCIO Configurations: [https://github.com/imageworks/OpenColorIO-Configs/zipball/master .zip] or [https://github.com/imageworks/OpenColorIO-Configs/tarball/master .tar.gz]. (You can also find them at https://github.com/imageworks/OpenColorIO-Configs)
# Extract the contents of the .zip or .tar.gz file to your computer.
# Decide which configuration you want to use. We recommend the '''aces_1.0.3''' configuration. You should see a file called '''config.ocio''' inside each of the configuration folders.
# Set an environment variable in your system called OCIO. The '''OCIO variable should be set to the full path and filename of the config.ocio file you want to use'''.

'''2. Restart Terragen after you change environment variables that affect OCIO'''

'''3. Enable OCIO in your Terragen project'''

In Terragen, OCIO is enabled or disabled on a ''per-project (per-scene) basis''. Click on '''Project Settings''' at the lower left of the main window, then turn on '''Use OCIO''' if it is not already on.

=== Command Line Arguments (Optional) ===

OCIO can be force-enabled with the command line argument "ocio" or "ocio=yes", as long as there is an environment variable named OCIO pointing to a valid OCIO config file. This command line argument causes Terragen to enable "Use OCIO" in Project Settings at startup and after a project is loaded. Terragen will default to roles which work well with ACES 1.0.3 but might not be compatible with your OCIO configuration, so 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 can be disabled with the command line argument "ocio=no". This causes Terragen to disable "Use OCIO" in Project Settings at startup and after a project is loaded.

=== First Tests ===

Toggling "Use OCIO" in Project Settings should cause the 3D Preview to refresh. If OCIO is configured correctly on your computer then you should also see the colours change in the 3D Preview. The difference may be subtle, but this depends on the OCIO configuration and the default choices for "Rendering space" and "Display space".

When "Use OCIO" is enabled, rendered images should also look different in the Render View.

When rendering with Path Tracer mode and viewing the 3D Preview in RTP mode, be sure to enable “Enable Path Tracing in the 3D Preview” button, above the 3D Preview pane.

[[File:TG_OCIO_RenderView_3DPreview_Settings_v002.jpg|None|867px|Terragen's 3D Preview pane and Render View pane using OCIO colour management and ACES colour space.]]

=== Choosing Colour Spaces ===

'''Rendering space'''

You can change the "Rendering space" but this should usually be "scene_linear" or "rendering". The former is more likely to be compatible with a wide range of OCIO configurations, and this is what Terragen chooses by default.

'''Display space'''

You can change the "Display space", but this should match your monitor. Terragen defaults to whichever display/view the OCIO configuration says is the default. Often this is "sRGB", but if you're unsure what to use then check with the person who set up your OCIO configuration.

'''Shader params (linear)'''

This allows you to choose the colour space that is used by the colour parameters in most shaders, with some exceptions. It doesn't apply to atmosphere parameters, and some other shaders have parameters which are locked to a raw colour space. We'll update this document soon with more details.

You should choose a linear colour space for "shader params (linear)". RGB values stored in Terragen scene files have always been linear, and Terragen automatically applies a gamma of 2.2 when editing colours with the colour picker.

By default, Terragen tries to find a colour space in your OCIO configuration which is linear and uses Rec.709 primaries, based on the name. If it finds a colour space that it thinks is suitable, it maps it to a special built-in role called "linear_rec709" which Terragen always add to the list if it doesn't find a role by that name in your OCIO config. By using this built-in role, our goal is for project files to be portable between different OCIO configurations that have this colour space even if there isn't a standardized name for it. If it makes the wrong choice you will need to choose something more appropriate. Please ensure that you choose a linear colour space for the shader params space.

If you want to change this to a colour space other than linear Rec.709, bear in mind that most assets generated by third parties will have been built assuming linear Rec.709.

'''8-bit textures'''

This allows you to choose the colour space that is used by Image Map Shaders which have "convert to linear" enabled in their options. It is also used by some of the images in the Default Shader.

By default, Terragen tries to find a colour space in your OCIO configuration which has the words "sRGB" and "texture" in its name. If it finds one it maps it to a special built-in role called "sRGB_texture" which Terragen always add to the list if it doesn't find a role by that name in your OCIO config. By using this built-in role, our goal is for project files to be portable between different OCIO configurations that have this colour space even if there isn't a standardized name for it. If it makes the wrong choice you will need to choose something more appropriate.

=== What's Supported in v4.5.43 ===

* You can choose the rendering/working space from the roles defined in the OCIO config. It defaults to "scene_linear", e.g. "scene_linear (ACES - ACEScg)".
* You can choose the display/view space from the displays/views defined in the OCIO config. It defaults to whichever display/view the OCIO config says is the default, e.g. "sRGB (ACES)".
* You can choose the colour spaces used by shader parameters (a linear colour space). It defaults to a special built-in role called "linear_rec709". If it doesn't find this in your OCIO config it tries to guess a suitable colour space by looking at the names of colour spaces in your config.
* You can choose the colour space to interpret 8-bit texture reads (usually sRGB). It defaults to a special built-in role called "sRGB_texture". If it doesn't find this in your OCIO config it tries to guess a suitable colour space using the words "sRGB" and "texture".
* 3D Preview refreshes when toggling OCIO checkbox or changing colour spaces in Project Settings.
* Render View refreshes when toggling OCIO checkbox or changing colour spaces in Project Settings.
* HDR renders are interpreted using whichever "Rendering space" is selected.
* LDR (display) version of the render is the result of tonemapping and transforming the HDR image using whichever "Display space" is selected.
* The Render View displays the LDR (display) version of the rendered image.
* Saving to an LDR file format (e.g. TIFF) saves the LDR (display) version of the image.
* Saving to EXR saves directly from the raw HDR render. Therefore you should interpret EXRs according to whichever "Rendering space" is selected, e.g. "scene_linear (ACES - ACEScg)". We presume this is what you want if you are using Terragen in a multi-app OCIO workflow.

=== Not Yet Supported ===

* Colour space for ''linear'' textures. At the moment, when you check "data is linear" it treats the image as raw data (in the rendering space).
* Choice of colour space per shader or node. In this version, conversion is done the same for all images that have "convert to linear" checked, and individual colour parameters on shaders are predefined to either be convertible or not.
* Independent choice of colour space for internal rendering and file output. Until we add this option, EXRs are output using the scene linear values that were generated by the renderer.

=== Examples ===
The following example uses Terragen's Colour Management with the Academy Color Encoding System (ACES) config profile. Special thanks to Bastien Muller for providing the rendered examples.

[[File:TG_OCIO_Comparision_FusionTerragenNuke_v002.jpg|None|867px|Side-by-side comparision of view-ports in Fusion, Terragen, and Nuke using ACES colour space.]]

OpenColorIO

2025-07-30T21:50:09Z

Matt: Linking directly to zipball/master (.zip) and tarball/master (.tar.gz), with the github.com/imageworks/OpenColorIO-Configs link as a backup

[[File:TG_OCIO_Project_Settings_Colour_Managment.PNG|None|500px|Terragen's Project Settings Colour Management interface]]

=== Overview ===

OpenColorIO (OCIO) is integrated into Terragen 4.5 Professional. It aims to allow you to work with colour spaces consistently with other applications in your pipeline.
{|
|-
| [[File:Wiki_TG45_OCIO_RenderRec709_ViewRec709.jpg|none|400px|Terragen default scene, rendered and viewed in Rec 709 colour space.]] || [[File:Wiki_TG45_OCIO_RenderRec709_ViewACEScg.jpg|none|400px|Terragen default scene, rendered in Rec 709 colour space, viewed in ACEScg colour space.]]
|-
| [[File:Wiki_TG45_OCIO_RenderACEScg_ViewRec709.jpg|none|400px|Terragen default scene, rendered in ACEScg colour space, viewed in Rec 709 colour space.]] || [[File:Wiki_TG45_OCIO_RenderACEScg_ViewACEScg.jpg|none|400px|Terragen default scene, rendered and viewed in ACEScg colour space.]]
|}
 

=== Requirements ===

'''1. Set up OCIO on your computer'''

If you're working at a company that uses OCIO, this has probably already been done for you.

If you don't have OCIO set up, follow these instructions:



# Download the Reference OCIO Configurations: [http://github.com/imageworks/OpenColorIO-Configs/zipball/master .zip] or [http://github.com/imageworks/OpenColorIO-Configs/tarball/master .tar.gz]. (You can also find them at https://github.com/imageworks/OpenColorIO-Configs)
# Extract the contents of the .zip or .tar.gz file to your computer.
# Decide which configuration you want to use. We recommend the '''aces_1.0.3''' configuration. You should see a file called '''config.ocio''' inside each of the configuration folders.
# Set an environment variable in your system called OCIO. The '''OCIO variable should be set to the full path and filename of the config.ocio file you want to use'''.

'''2. Restart Terragen after you change environment variables that affect OCIO'''

'''3. Enable OCIO in your Terragen project'''

In Terragen, OCIO is enabled or disabled on a ''per-project (per-scene) basis''. Click on '''Project Settings''' at the lower left of the main window, then turn on '''Use OCIO''' if it is not already on.

=== Command Line Arguments (Optional) ===

OCIO can be force-enabled with the command line argument "ocio" or "ocio=yes", as long as there is an environment variable named OCIO pointing to a valid OCIO config file. This command line argument causes Terragen to enable "Use OCIO" in Project Settings at startup and after a project is loaded. Terragen will default to roles which work well with ACES 1.0.3 but might not be compatible with your OCIO configuration, so 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 can be disabled with the command line argument "ocio=no". This causes Terragen to disable "Use OCIO" in Project Settings at startup and after a project is loaded.

=== First Tests ===

Toggling "Use OCIO" in Project Settings should cause the 3D Preview to refresh. If OCIO is configured correctly on your computer then you should also see the colours change in the 3D Preview. The difference may be subtle, but this depends on the OCIO configuration and the default choices for "Rendering space" and "Display space".

When "Use OCIO" is enabled, rendered images should also look different in the Render View.

When rendering with Path Tracer mode and viewing the 3D Preview in RTP mode, be sure to enable “Enable Path Tracing in the 3D Preview” button, above the 3D Preview pane.

[[File:TG_OCIO_RenderView_3DPreview_Settings_v002.jpg|None|867px|Terragen's 3D Preview pane and Render View pane using OCIO colour management and ACES colour space.]]

=== Choosing Colour Spaces ===

'''Rendering space'''

You can change the "Rendering space" but this should usually be "scene_linear" or "rendering". The former is more likely to be compatible with a wide range of OCIO configurations, and this is what Terragen chooses by default.

'''Display space'''

You can change the "Display space", but this should match your monitor. Terragen defaults to whichever display/view the OCIO configuration says is the default. Often this is "sRGB", but if you're unsure what to use then check with the person who set up your OCIO configuration.

'''Shader params (linear)'''

This allows you to choose the colour space that is used by the colour parameters in most shaders, with some exceptions. It doesn't apply to atmosphere parameters, and some other shaders have parameters which are locked to a raw colour space. We'll update this document soon with more details.

You should choose a linear colour space for "shader params (linear)". RGB values stored in Terragen scene files have always been linear, and Terragen automatically applies a gamma of 2.2 when editing colours with the colour picker.

By default, Terragen tries to find a colour space in your OCIO configuration which is linear and uses Rec.709 primaries, based on the name. If it finds a colour space that it thinks is suitable, it maps it to a special built-in role called "linear_rec709" which Terragen always add to the list if it doesn't find a role by that name in your OCIO config. By using this built-in role, our goal is for project files to be portable between different OCIO configurations that have this colour space even if there isn't a standardized name for it. If it makes the wrong choice you will need to choose something more appropriate. Please ensure that you choose a linear colour space for the shader params space.

If you want to change this to a colour space other than linear Rec.709, bear in mind that most assets generated by third parties will have been built assuming linear Rec.709.

'''8-bit textures'''

This allows you to choose the colour space that is used by Image Map Shaders which have "convert to linear" enabled in their options. It is also used by some of the images in the Default Shader.

By default, Terragen tries to find a colour space in your OCIO configuration which has the words "sRGB" and "texture" in its name. If it finds one it maps it to a special built-in role called "sRGB_texture" which Terragen always add to the list if it doesn't find a role by that name in your OCIO config. By using this built-in role, our goal is for project files to be portable between different OCIO configurations that have this colour space even if there isn't a standardized name for it. If it makes the wrong choice you will need to choose something more appropriate.

=== What's Supported in v4.5.43 ===

* You can choose the rendering/working space from the roles defined in the OCIO config. It defaults to "scene_linear", e.g. "scene_linear (ACES - ACEScg)".
* You can choose the display/view space from the displays/views defined in the OCIO config. It defaults to whichever display/view the OCIO config says is the default, e.g. "sRGB (ACES)".
* You can choose the colour spaces used by shader parameters (a linear colour space). It defaults to a special built-in role called "linear_rec709". If it doesn't find this in your OCIO config it tries to guess a suitable colour space by looking at the names of colour spaces in your config.
* You can choose the colour space to interpret 8-bit texture reads (usually sRGB). It defaults to a special built-in role called "sRGB_texture". If it doesn't find this in your OCIO config it tries to guess a suitable colour space using the words "sRGB" and "texture".
* 3D Preview refreshes when toggling OCIO checkbox or changing colour spaces in Project Settings.
* Render View refreshes when toggling OCIO checkbox or changing colour spaces in Project Settings.
* HDR renders are interpreted using whichever "Rendering space" is selected.
* LDR (display) version of the render is the result of tonemapping and transforming the HDR image using whichever "Display space" is selected.
* The Render View displays the LDR (display) version of the rendered image.
* Saving to an LDR file format (e.g. TIFF) saves the LDR (display) version of the image.
* Saving to EXR saves directly from the raw HDR render. Therefore you should interpret EXRs according to whichever "Rendering space" is selected, e.g. "scene_linear (ACES - ACEScg)". We presume this is what you want if you are using Terragen in a multi-app OCIO workflow.

=== Not Yet Supported ===

* Colour space for ''linear'' textures. At the moment, when you check "data is linear" it treats the image as raw data (in the rendering space).
* Choice of colour space per shader or node. In this version, conversion is done the same for all images that have "convert to linear" checked, and individual colour parameters on shaders are predefined to either be convertible or not.
* Independent choice of colour space for internal rendering and file output. Until we add this option, EXRs are output using the scene linear values that were generated by the renderer.

=== Examples ===
The following example uses Terragen's Colour Management with the Academy Color Encoding System (ACES) config profile. Special thanks to Bastien Muller for providing the rendered examples.

[[File:TG_OCIO_Comparision_FusionTerragenNuke_v002.jpg|None|867px|Side-by-side comparision of view-ports in Fusion, Terragen, and Nuke using ACES colour space.]]

Linux Command Line Reference (TG3)

2025-07-30T00:17:10Z

Matt: Added link to command line references for all versions, all platforms

This document is a mirror of the file 'linux_command_line.txt' in the Terragen 3 for Linux distribution.

See Also: [[Command_Line_Reference|Command Line References for All Versions, All Platforms]]

Updated 19/February/2013 (build 2.9.01.2 )

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

Terragen 3 for Linux is a command line render node which doesn't have a GUI.

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

Run Terragen 3 and load a project file:

./terragen -p project.tgd

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

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

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

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

Run Terragen 3 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

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.

-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 really relevant to the Linux render node as it doesn't have a GUI.

-no3dpreview

Do not open the 3D Preview automatically. This is not really 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 really 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.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 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.
<nodename> must be the name of a render node 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

Mac Command Line Reference (TG3)

2025-07-30T00:16:19Z

Matt: Added link to command line references for all versions, all platforms

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

See Also: [[Command_Line_Reference|Command Line References for All Versions, All Platforms]]

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 GUI, 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 GUI, 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 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.
<nodename> must be the name of a render node 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

Windows Command Line Reference (TG3)

2025-07-30T00:15:18Z

Matt: Added link to command line references for all versions, all platforms

This document is a mirror of win_command_line.txt in the 'docs' folder in the 'Terragen 3' folder.

See Also: [[Command_Line_Reference|Command Line References for All Versions, All Platforms]]

Updated 8/September/2012 (build 2.9.0.12)

-----------------------------------------------------------
Running Terragen 3 From a Command Line or Shell environment
-----------------------------------------------------------

Two executables are provided with TG3:

tgd.exe: Does not print anything to the console. Returns to the command prompt immediately while continuing to run in the background.

tgdcli.exe: Exactly the same as tgd.exe, except that it prints messages and warnings to the console and it only returns to the command prompt after execution has finished.

Both executables can be run either with or without a GUI, and both share the same command line options.

SETUP
-----

tgd or tgdcli can be launched from the command line in a number of different modes. However, before you try running them from the command line it's wise to set up some environment variables.

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 tgdcli 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, on the Windows command line or batch file:

set TERRAGEN_PATH=C:\Program Files\Planetside Software\Terragen 3

In other shells you would use the appropriate syntax (such as setenv).

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 the environment variable is set, you can run Terragen. Here are some examples at the Windows command prompt or in a batch file. In other shells you would probably replace %TERRAGEN_PATH% with $TERRAGEN_PATH.

Quotes are used to surround the executable path, because TERRAGEN_PATH may contains spaces.

Run Terragen as normal:

"%TERRAGEN_PATH%/tgdcli"

Run Terragen and load a project file:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd

Run Terragen without the GUI, render frame 42, then close:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd -hide -exit -r -f 42

Run Terragen without the GUI, render frames 1,4,51,53,55,57,59, then close:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd -hide -exit -r -f 1,4,51-60/2

IMPORTANT: Currently (v2.9.0.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.
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. 'C:\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:

'C:\frames\image.0023.IMAGETYPE.exr'

may result in:

'C:\frames\image.0023.alpha.exr' 
'C:\frames\image.0023.surfrgb.exr' 
'C:\frames\image.0023.surfalpha.exr' 
etc.

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

'C:\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 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.
<nodename> must be the name of a render node 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

Linux Command Line Reference (TG4)

2025-07-30T00:14:17Z

Matt: Added link to command line references for all versions, all platforms

This document is a mirror of the file 'linux_command_line.txt' in the Terragen 4 for Linux distribution.

See Also: [[Command_Line_Reference|Command Line References for All Versions, All Platforms]]

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

Mac Command Line Reference (TG4)

2025-07-30T00:13:09Z

Matt: Added link to command line references for all versions, all platforms

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

See Also: [[Command_Line_Reference|Command Line References for All Versions, All Platforms]]

Updated 10/June/2024 (build 4.8.12)

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

Terragen 4 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 4 from the command line you need to access the executable directly. Terragen 4 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 TG4>/Terragen 4.app/Contents/MacOS/'

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

Notice that the first part of the path is "Terragen 4.app". This is name of the special application folder mentioned above, which is what you see in the Finder as the actual Terragen 4 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 4.app" application folder.

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

./'Terragen 4'

N.B. You will need to use single quotes around paths (as I have above), because of the spaces in the "Terragen 4" 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 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 4'

Run Terragen 4 and load a project file:

./'Terragen 4' -p project.tgd

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

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

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

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

IMPORTANT: Currently 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.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.

-w <filename>

The same as the -p option

Windows Command Line Reference (TG4)

2025-07-30T00:11:59Z

Matt: Added link to command line references for all versions, all platforms

This document is a mirror of the file 'win_command_line.txt' in the Docs folder in the Terragen 4 folder.

See Also: [[Command_Line_Reference|Command Line References for All Versions, All Platforms]]

Updated 10/June/2024 (build 4.8.12)

-----------------------------------------------------------
Running Terragen 4 From a Command Line or Shell environment
-----------------------------------------------------------

Two executables are provided with TG4:

tgd.exe: Does not print anything to the console. Returns to the command prompt immediately while continuing to run in the background.

tgdcli.exe: Exactly the same as tgd.exe, except that it prints messages and warnings to the console and it only returns to the command prompt after execution has finished.

Both executables can be run either with or without a GUI, and both share the same command line options.

SETUP
-----

tgd or tgdcli can be launched from the command line in a number of different modes. However, before you try running them from the command line it's wise to set up some environment variables.

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 tgdcli 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, on the Windows command line or batch file:

set TERRAGEN_PATH=C:\Program Files\Planetside Software\Terragen 4

In other shells you would use the appropriate syntax (such as setenv).

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 the environment variable is set, you can run Terragen. Here are some examples at the Windows command prompt or in a batch file. In other shells you would probably replace %TERRAGEN_PATH% with $TERRAGEN_PATH.

Quotes are used to surround the executable path, because TERRAGEN_PATH may contains spaces.

Run Terragen as normal:

"%TERRAGEN_PATH%/tgdcli"

Run Terragen and load a project file:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd

Run Terragen without the GUI, render frame 42, then close:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd -hide -exit -r -f 42

Run Terragen without the GUI, render frames 1,4,51,53,55,57,59, then close:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd -hide -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. 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. 'C:\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:

'C:\frames\image.0023.IMAGETYPE.exr'

may result in:

'C:\frames\image.0023.tgAlpha.exr' 
'C:\frames\image.0023.tgSurfRgb.exr' 
'C:\frames\image.0023.tgSurfAlpha.exr' 
etc.

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

'C:\frames\tgAlpha\image.0023.tgAlpha.exr' 
'C:\frames\tgSurfRgb\image.0023.tgSurfRgb.exr' 
'C:\frames\tgSurfAlpha\image.0023.tgSurfAlpha.exr' 
etc.

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

'C:\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:

'C:\frames\image.0023.exr'

may result in:

'C:\frames\tgAlpha\image.0023.exr' 
'C:\frames\tgSurfRgb\image.0023.exr' 
'C:\frames\tgSurfAlpha\image.0023.exr' 
etc.

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

'C:\frames\tgAlpha\image.0023.tgAlpha.exr' 
'C:\frames\tgSurfRgb\image.0023.tgSurfRgb.exr' 
'C:\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:
tgdcli -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

Linux Command Line Reference (TG4)

2025-07-29T23:54:33Z

Matt: Updated for build 4.8.12: -renderlayer option

This document is a mirror of the file 'linux_command_line.txt' in the Terragen 4 for Linux distribution.

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

Mac Command Line Reference (TG4)

2025-07-29T23:50:56Z

Matt: Updated for build 4.8.12: -renderlayer option

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

Updated 10/June/2024 (build 4.8.12)

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

Terragen 4 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 4 from the command line you need to access the executable directly. Terragen 4 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 TG4>/Terragen 4.app/Contents/MacOS/'

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

Notice that the first part of the path is "Terragen 4.app". This is name of the special application folder mentioned above, which is what you see in the Finder as the actual Terragen 4 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 4.app" application folder.

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

./'Terragen 4'

N.B. You will need to use single quotes around paths (as I have above), because of the spaces in the "Terragen 4" 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 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 4'

Run Terragen 4 and load a project file:

./'Terragen 4' -p project.tgd

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

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

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

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

IMPORTANT: Currently 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.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.

-w <filename>

The same as the -p option

Windows Command Line Reference (TG4)

2025-07-29T23:42:06Z

Matt: Updated for build 4.8.12: -renderlayer option

This document is a mirror of the file 'win_command_line.txt' in the Docs folder in the Terragen 4 folder.

Updated 10/June/2024 (build 4.8.12)

-----------------------------------------------------------
Running Terragen 4 From a Command Line or Shell environment
-----------------------------------------------------------

Two executables are provided with TG4:

tgd.exe: Does not print anything to the console. Returns to the command prompt immediately while continuing to run in the background.

tgdcli.exe: Exactly the same as tgd.exe, except that it prints messages and warnings to the console and it only returns to the command prompt after execution has finished.

Both executables can be run either with or without a GUI, and both share the same command line options.

SETUP
-----

tgd or tgdcli can be launched from the command line in a number of different modes. However, before you try running them from the command line it's wise to set up some environment variables.

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 tgdcli 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, on the Windows command line or batch file:

set TERRAGEN_PATH=C:\Program Files\Planetside Software\Terragen 4

In other shells you would use the appropriate syntax (such as setenv).

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 the environment variable is set, you can run Terragen. Here are some examples at the Windows command prompt or in a batch file. In other shells you would probably replace %TERRAGEN_PATH% with $TERRAGEN_PATH.

Quotes are used to surround the executable path, because TERRAGEN_PATH may contains spaces.

Run Terragen as normal:

"%TERRAGEN_PATH%/tgdcli"

Run Terragen and load a project file:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd

Run Terragen without the GUI, render frame 42, then close:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd -hide -exit -r -f 42

Run Terragen without the GUI, render frames 1,4,51,53,55,57,59, then close:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd -hide -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. 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. 'C:\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:

'C:\frames\image.0023.IMAGETYPE.exr'

may result in:

'C:\frames\image.0023.tgAlpha.exr' 
'C:\frames\image.0023.tgSurfRgb.exr' 
'C:\frames\image.0023.tgSurfAlpha.exr' 
etc.

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

'C:\frames\tgAlpha\image.0023.tgAlpha.exr' 
'C:\frames\tgSurfRgb\image.0023.tgSurfRgb.exr' 
'C:\frames\tgSurfAlpha\image.0023.tgSurfAlpha.exr' 
etc.

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

'C:\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:

'C:\frames\image.0023.exr'

may result in:

'C:\frames\tgAlpha\image.0023.exr' 
'C:\frames\tgSurfRgb\image.0023.exr' 
'C:\frames\tgSurfAlpha\image.0023.exr' 
etc.

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

'C:\frames\tgAlpha\image.0023.tgAlpha.exr' 
'C:\frames\tgSurfRgb\image.0023.tgSurfRgb.exr' 
'C:\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:
tgdcli -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

File:83 AllSkyPaintTools.jpg

2024-12-06T21:48:10Z

Matt:

File:Test-upload reference-images-and-projections.png

2024-12-06T21:43:58Z

Matt:

Windows Command Line Reference (TG4)

2022-07-01T11:45:31Z

Matt: Minor edits, consistency with Linux command line docs (4.6.11)

This document is a mirror of the file 'win_command_line.txt' in the Docs folder in the Terragen 4 folder.

Updated 1/July/2022 (build 4.6.11)

-----------------------------------------------------------
Running Terragen 4 From a Command Line or Shell environment
-----------------------------------------------------------

Two executables are provided with TG4:

tgd.exe: Does not print anything to the console. Returns to the command prompt immediately while continuing to run in the background.

tgdcli.exe: Exactly the same as tgd.exe, except that it prints messages and warnings to the console and it only returns to the command prompt after execution has finished.

Both executables can be run either with or without a GUI, and both share the same command line options.

SETUP
-----

tgd or tgdcli can be launched from the command line in a number of different modes. However, before you try running them from the command line it's wise to set up some environment variables.

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 tgdcli 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, on the Windows command line or batch file:

set TERRAGEN_PATH=C:\Program Files\Planetside Software\Terragen 4

In other shells you would use the appropriate syntax (such as setenv).

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 the environment variable is set, you can run Terragen. Here are some examples at the Windows command prompt or in a batch file. In other shells you would probably replace %TERRAGEN_PATH% with $TERRAGEN_PATH.

Quotes are used to surround the executable path, because TERRAGEN_PATH may contains spaces.

Run Terragen as normal:

"%TERRAGEN_PATH%/tgdcli"

Run Terragen and load a project file:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd

Run Terragen without the GUI, render frame 42, then close:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd -hide -exit -r -f 42

Run Terragen without the GUI, render frames 1,4,51,53,55,57,59, then close:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd -hide -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. 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. 'C:\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:

'C:\frames\image.0023.IMAGETYPE.exr'

may result in:

'C:\frames\image.0023.tgAlpha.exr' 
'C:\frames\image.0023.tgSurfRgb.exr' 
'C:\frames\image.0023.tgSurfAlpha.exr' 
etc.

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

'C:\frames\tgAlpha\image.0023.tgAlpha.exr' 
'C:\frames\tgSurfRgb\image.0023.tgSurfRgb.exr' 
'C:\frames\tgSurfAlpha\image.0023.tgSurfAlpha.exr' 
etc.

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

'C:\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:

'C:\frames\image.0023.exr'

may result in:

'C:\frames\tgAlpha\image.0023.exr' 
'C:\frames\tgSurfRgb\image.0023.exr' 
'C:\frames\tgSurfAlpha\image.0023.exr' 
etc.

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

'C:\frames\tgAlpha\image.0023.tgAlpha.exr' 
'C:\frames\tgSurfRgb\image.0023.tgSurfRgb.exr' 
'C:\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.
<nodename> must be the name of a render node in the project.
Projects loaded subsequently are not affected.

-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:
tgdcli -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

Linux Command Line Reference (TG4)

2022-07-01T11:38:36Z

Matt: Minor corrections, consistency with Windows command line docs (4.6.11)

This document is a mirror of the file 'linux_command_line.txt' in the Terragen 4 for Linux distribution.

Updated 1/July/2022 (build 4.6.11)

--------------------------------------------
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.
<nodename> must be the name of a render node in the project.
Projects loaded subsequently are not affected.

-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

Windows Command Line Reference (TG4)

2022-07-01T11:20:33Z

Matt: Updated for build 4.6.08, documenting VDB export

This document is a mirror of the file 'win_command_line.txt' in the Docs folder in the Terragen 4 folder.

Updated 6/June/2022 (build 4.6.08)

-----------------------------------------------------------
Running Terragen 4 From a Command Line or Shell environment
-----------------------------------------------------------

Two executables are provided with TG4:

tgd.exe: Does not print anything to the console. Returns to the command prompt immediately while continuing to run in the background.

tgdcli.exe: Exactly the same as tgd.exe, except that it prints messages and warnings to the console and it only returns to the command prompt after execution has finished.

Both executables can be run either with or without a GUI, and both share the same command line options.

SETUP
-----

tgd or tgdcli can be launched from the command line in a number of different modes. However, before you try running them from the command line it's wise to set up some environment variables.

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 tgdcli 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, on the Windows command line or batch file:

set TERRAGEN_PATH=C:\Program Files\Planetside Software\Terragen 4

In other shells you would use the appropriate syntax (such as setenv).

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 the environment variable is set, you can run Terragen. Here are some examples at the Windows command prompt or in a batch file. In other shells you would probably replace %TERRAGEN_PATH% with $TERRAGEN_PATH.

Quotes are used to surround the executable path, because TERRAGEN_PATH may contains spaces.

Run Terragen as normal:

"%TERRAGEN_PATH%/tgdcli"

Run Terragen and load a project file:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd

Run Terragen without the GUI, render frame 42, then close:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd -hide -exit -r -f 42

Run Terragen without the GUI, render frames 1,4,51,53,55,57,59, then close:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd -hide -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. 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.
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. 'C:\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:

'C:\frames\image.0023.IMAGETYPE.exr'

may result in:

'C:\frames\image.0023.tgAlpha.exr' 
'C:\frames\image.0023.tgSurfRgb.exr' 
'C:\frames\image.0023.tgSurfAlpha.exr' 
etc.

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

'C:\frames\tgAlpha\image.0023.tgAlpha.exr' 
'C:\frames\tgSurfRgb\image.0023.tgSurfRgb.exr' 
'C:\frames\tgSurfAlpha\image.0023.tgSurfAlpha.exr' 
etc.

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

'C:\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:

'C:\frames\image.0023.exr'

may result in:

'C:\frames\tgAlpha\image.0023.exr' 
'C:\frames\tgSurfRgb\image.0023.exr' 
'C:\frames\tgSurfAlpha\image.0023.exr' 
etc.

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

'C:\frames\tgAlpha\image.0023.tgAlpha.exr' 
'C:\frames\tgSurfRgb\image.0023.tgSurfRgb.exr' 
'C:\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.
<nodename> must be the name of a render node in the project.
Projects loaded subsequently are not affected.

-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:
tgdcli -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

VDB Export

2022-06-10T05:51:09Z

Matt:

Beginning with Terragen 4.3, the Linux build of Terragen Professional can export cloud layers to VDB files from the command line. The exported VDBs are voxelised representations of cloud density.

'''NEW: Beginning with Terragen 4.6.11, VDBs can be exported in the UI from the Node Network. Open the right-click/context menu for a cloud node and select "Export VDB File...". This is currently limited to Terragen Creative and Terragen Professional.'''

VDBs can be exported from layers of type Cloud Layer V2, Cloud Layer V3 and Easy Cloud. The exporter works on whole cloud layers, but it can only export one layer at a time. If you want to export more than one cloud layer, export one VDB file for each layer.

===Versions and Platforms===

* Windows: Terragen Professional 4.6 and above, Terragen Creative 4.6 and above
* Linux: Terragen Professional 4.3 and above

===Exported Region===

The region to be exported is defined by the "localisation" parameters on the Main tab of the cloud layer.

Easy Clouds are always "localised" cloud layers. That means they are limited to a finite region of space which is controlled by the altitude, depth and "radius of localisation".

Cloud Layer V2 and Cloud Layer V3 do not need to be localised for rendering, but if you export them to a VDB file you need to pay attention to the localisation parameters. They define the region of space that will be exported, regardless of whether 'localise' is enabled.

We recommend that you only use the exporter for cloud layers which are localised, because exporting of non-localised layers is tested less often so there are more likely to be bugs related to this.

===Resolution===

The resolution of the voxel buffer is controlled on the Optimisation tab of your cloud layer, using the "millions of voxels" parameter. The main use of these settings is for optimising rendering, but the VDB exporter borrows these numbers when it generates the voxel buffer. The XYZ voxel buffer size shown below the "millions of voxels" parameter is just an approximation, because the curvature of the planet requires that the VDB exporter work slightly differently from the built-in voxel buffer for rendering. However, the approximation gives you a good idea of how much calculation needs to be done to generate the VDB file.

The export process takes some time to finish, and can produce very large files. The size of the VDB file of course depends on the voxel resolution you specify, but it's also affected by how much empty space there is in the volume.

===Export from the UI===

Right-click/context-click on a cloud node in the Node Network and select "Export VDB File...", choose an output filename and select "Save". The voxel generation process will begin and a progress window will appear. When it has completed generating the voxel buffer it will save the buffer to the file. This is currently limited to Terragen Creative and Terragen Professional.

===Command Line Export===

To export a cloud layer from the command line, use the following:

Windows:
tgdcli.exe -p project.tgd -exportvdb "Name of cloud layer" filename.vdb -threads numthreads
Linux:
./terragen -p project.tgd -exportvdb "Name of cloud layer" filename.vdb -threads numthreads

The cloud name needs to be in quotes if there are spaces in its name. Usually there are.

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. If you don't use the -threads option, Terragen will use as many logical cores as it thinks are available on your computer. Builds earlier than 4.3.16 can only use one thread to export.

===Multi-Threaded Performance===

At the time of writing (build 4.3.16) the exporter has not been fully optimised for multi-threading, but it works. We've noticed that performance drops off as the number of threads increases, and the fastest export times may be at a relatively low number of threads. Therefore we strongly recommend that you use the -threads option and experiment with different thread counts to see what works best for your scene and your hardware.

===What About Mac?===

We plan to add this feature to Mac builds in the near future.

===Send Us Feedback===

The VDB exporter is a relatively new feature. So please let us know how you are using it, and send us suggestions for how we can improve it.

VDB Export

2022-06-10T05:50:32Z

Matt: Added "Export from the UI"

Beginning with Terragen 4.3, the Linux build of Terragen Professional can export cloud layers to VDB files from the command line. The exported VDBs are voxelised representations of cloud density.

'''NEW: Beginning with Terragen 4.6.11, VDBs can be exported in the UI from the Node Network. Open the right-click/context menu for a cloud node and select "Export VDB File...". This is currently limited to Terragen Creative and Terragen Professional.'''

VDBs can be exported from layers of type Cloud Layer V2, Cloud Layer V3 and Easy Cloud. The exporter works on whole cloud layers, but it can only export one layer at a time. If you want to export more than one cloud layer, export one VDB file for each layer.

===Versions and Platforms===

* Windows: Terragen Professional 4.6 and above, Terragen Creative 4.6 and above
* Linux: Terragen Professional 4.3 and above

===Exported Region===

The region to be exported is defined by the "localisation" parameters on the Main tab of the cloud layer.

Easy Clouds are always "localised" cloud layers. That means they are limited to a finite region of space which is controlled by the altitude, depth and "radius of localisation".

Cloud Layer V2 and Cloud Layer V3 do not need to be localised for rendering, but if you export them to a VDB file you need to pay attention to the localisation parameters. They define the region of space that will be exported, regardless of whether 'localise' is enabled.

We recommend that you only use the exporter for cloud layers which are localised, because exporting of non-localised layers is tested less often so there are more likely to be bugs related to this.

===Resolution===

The resolution of the voxel buffer is controlled on the Optimisation tab of your cloud layer, using the "millions of voxels" parameter. The main use of these settings is for optimising rendering, but the VDB exporter borrows these numbers when it generates the voxel buffer. The XYZ voxel buffer size shown below the "millions of voxels" parameter is just an approximation, because the curvature of the planet requires that the VDB exporter work slightly differently from the built-in voxel buffer for rendering. However, the approximation gives you a good idea of how much calculation needs to be done to generate the VDB file.

The export process takes some time to finish, and can produce very large files. The size of the VDB file of course depends on the voxel resolution you specify, but it's also affected by how much empty space there is in the volume.

===Export from the UI===

Right-click/context-click on a cloud node in the Node Network and select "Export VDB File...", choose an output filename and select "Save." The voxel generation process will begin and a progress window will appear. When it has completed generating the voxel buffer it will save the buffer to the file. This is currently limited to Terragen Creative and Terragen Professional.

===Command Line Export===

To export a cloud layer from the command line, use the following:

Windows:
tgdcli.exe -p project.tgd -exportvdb "Name of cloud layer" filename.vdb -threads numthreads
Linux:
./terragen -p project.tgd -exportvdb "Name of cloud layer" filename.vdb -threads numthreads

The cloud name needs to be in quotes if there are spaces in its name. Usually there are.

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. If you don't use the -threads option, Terragen will use as many logical cores as it thinks are available on your computer. Builds earlier than 4.3.16 can only use one thread to export.

===Multi-Threaded Performance===

At the time of writing (build 4.3.16) the exporter has not been fully optimised for multi-threading, but it works. We've noticed that performance drops off as the number of threads increases, and the fastest export times may be at a relatively low number of threads. Therefore we strongly recommend that you use the -threads option and experiment with different thread counts to see what works best for your scene and your hardware.

===What About Mac?===

We plan to add this feature to Mac builds in the near future.

===Send Us Feedback===

The VDB exporter is a relatively new feature. So please let us know how you are using it, and send us suggestions for how we can improve it.

VDB Export

2022-06-10T05:44:38Z

Matt: Added Windows command line

Beginning with Terragen 4.3, the Linux build of Terragen Professional can export cloud layers to VDB files from the command line. The exported VDBs are voxelised representations of cloud density.

'''NEW: Beginning with Terragen 4.6.11, VDBs can be exported in the UI from the Node Network. Open the right-click/context menu for a cloud node and select "Export VDB File...". This is currently limited to Terragen Creative and Terragen Professional.'''

VDBs can be exported from layers of type Cloud Layer V2, Cloud Layer V3 and Easy Cloud. The exporter works on whole cloud layers, but it can only export one layer at a time. If you want to export more than one cloud layer, export one VDB file for each layer.

===Versions and Platforms===

* Windows: Terragen Professional 4.6 and above, Terragen Creative 4.6 and above
* Linux: Terragen Professional 4.3 and above

===Exported Region===

The region to be exported is defined by the "localisation" parameters on the Main tab of the cloud layer.

Easy Clouds are always "localised" cloud layers. That means they are limited to a finite region of space which is controlled by the altitude, depth and "radius of localisation".

Cloud Layer V2 and Cloud Layer V3 do not need to be localised for rendering, but if you export them to a VDB file you need to pay attention to the localisation parameters. They define the region of space that will be exported, regardless of whether 'localise' is enabled.

We recommend that you only use the exporter for cloud layers which are localised, because exporting of non-localised layers is tested less often so there are more likely to be bugs related to this.

===Resolution===

The resolution of the voxel buffer is controlled on the Optimisation tab of your cloud layer, using the "millions of voxels" parameter. The main use of these settings is for optimising rendering, but the VDB exporter borrows these numbers when it generates the voxel buffer. The XYZ voxel buffer size shown below the "millions of voxels" parameter is just an approximation, because the curvature of the planet requires that the VDB exporter work slightly differently from the built-in voxel buffer for rendering. However, the approximation gives you a good idea of how much calculation needs to be done to generate the VDB file.

The export process takes some time to finish, and can produce very large files. The size of the VDB file of course depends on the voxel resolution you specify, but it's also affected by how much empty space there is in the volume.

===Command Line Export===

To export a cloud layer from the command line, use the following:

Windows:
tgdcli.exe -p project.tgd -exportvdb "Name of cloud layer" filename.vdb -threads numthreads
Linux:
./terragen -p project.tgd -exportvdb "Name of cloud layer" filename.vdb -threads numthreads

The cloud name needs to be in quotes if there are spaces in its name. Usually there are.

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. If you don't use the -threads option, Terragen will use as many logical cores as it thinks are available on your computer. Builds earlier than 4.3.16 can only use one thread to export.

===Multi-Threaded Performance===

At the time of writing (build 4.3.16) the exporter has not been fully optimised for multi-threading, but it works. We've noticed that performance drops off as the number of threads increases, and the fastest export times may be at a relatively low number of threads. Therefore we strongly recommend that you use the -threads option and experiment with different thread counts to see what works best for your scene and your hardware.

===What About Mac?===

We plan to add this feature to Mac builds in the near future.

===Send Us Feedback===

The VDB exporter is a relatively new feature. So please let us know how you are using it, and send us suggestions for how we can improve it.

VDB Export

2022-06-10T05:42:09Z

Matt: Updated for 4.6.11 on Windows

Beginning with Terragen 4.3, the Linux build of Terragen Professional can export cloud layers to VDB files from the command line. The exported VDBs are voxelised representations of cloud density.

'''NEW: Beginning with Terragen 4.6.11, VDBs can be exported in the UI from the Node Network. Open the right-click/context menu for a cloud node and select "Export VDB File...". This is currently limited to Terragen Creative and Terragen Professional.'''

VDBs can be exported from layers of type Cloud Layer V2, Cloud Layer V3 and Easy Cloud. The exporter works on whole cloud layers, but it can only export one layer at a time. If you want to export more than one cloud layer, export one VDB file for each layer.

===Versions and Platforms===

* Windows: Terragen Professional 4.6 and above, Terragen Creative 4.6 and above
* Linux: Terragen Professional 4.3 and above

===Exported Region===

The region to be exported is defined by the "localisation" parameters on the Main tab of the cloud layer.

Easy Clouds are always "localised" cloud layers. That means they are limited to a finite region of space which is controlled by the altitude, depth and "radius of localisation".

Cloud Layer V2 and Cloud Layer V3 do not need to be localised for rendering, but if you export them to a VDB file you need to pay attention to the localisation parameters. They define the region of space that will be exported, regardless of whether 'localise' is enabled.

We recommend that you only use the exporter for cloud layers which are localised, because exporting of non-localised layers is tested less often so there are more likely to be bugs related to this.

===Resolution===

The resolution of the voxel buffer is controlled on the Optimisation tab of your cloud layer, using the "millions of voxels" parameter. The main use of these settings is for optimising rendering, but the VDB exporter borrows these numbers when it generates the voxel buffer. The XYZ voxel buffer size shown below the "millions of voxels" parameter is just an approximation, because the curvature of the planet requires that the VDB exporter work slightly differently from the built-in voxel buffer for rendering. However, the approximation gives you a good idea of how much calculation needs to be done to generate the VDB file.

The export process takes some time to finish, and can produce very large files. The size of the VDB file of course depends on the voxel resolution you specify, but it's also affected by how much empty space there is in the volume.

===The Export Command (Linux)===

To export a cloud layer from the Linux command line renderer, use the following:

./terragen -p project.tgd -exportvdb "Name of cloud layer" filename.vdb -threads numthreads

The cloud name needs to be in quotes if there are spaces in its name. Usually there are.

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. If you don't use the -threads option, Terragen will use as many logical cores as it thinks are available on your computer. Builds earlier than 4.3.16 can only use one thread to export.

===Multi-Threaded Performance===

At the time of writing (build 4.3.16) the exporter has not been fully optimised for multi-threading, but it works. We've noticed that performance drops off as the number of threads increases, and the fastest export times may be at a relatively low number of threads. Therefore we strongly recommend that you use the -threads option and experiment with different thread counts to see what works best for your scene and your hardware.

===What About Mac?===

We plan to add this feature to Mac builds in the near future.

===Send Us Feedback===

The VDB exporter is a relatively new feature. So please let us know how you are using it, and send us suggestions for how we can improve it.

OpenColorIO

2022-02-11T20:02:25Z

Matt: Removed "Other Considerations" which applied only to older frontier builds.

[[File:TG_OCIO_Project_Settings_Colour_Managment.PNG|None|500px|Terragen's Project Settings Colour Management interface]]

=== Overview ===

OpenColorIO (OCIO) is integrated into Terragen 4.5 Professional. It aims to allow you to work with colour spaces consistently with other applications in your pipeline.
{|
|-
| [[File:Wiki_TG45_OCIO_RenderRec709_ViewRec709.jpg|none|400px|Terragen default scene, rendered and viewed in Rec 709 colour space.]] || [[File:Wiki_TG45_OCIO_RenderRec709_ViewACEScg.jpg|none|400px|Terragen default scene, rendered in Rec 709 colour space, viewed in ACEScg colour space.]]
|-
| [[File:Wiki_TG45_OCIO_RenderACEScg_ViewRec709.jpg|none|400px|Terragen default scene, rendered in ACEScg colour space, viewed in Rec 709 colour space.]] || [[File:Wiki_TG45_OCIO_RenderACEScg_ViewACEScg.jpg|none|400px|Terragen default scene, rendered and viewed in ACEScg colour space.]]
|}
 

=== Requirements ===

'''1. Set up OCIO on your computer'''

If you're working at a company that uses OCIO, this has probably already been done for you.

If you don't have OCIO set up, follow these instructions:

# Download the Sample OCIO Configurations at http://github.com/imageworks/OpenColorIO-Configs/zipball/master
# Extract the contents of the .zip file to your computer.
# Decide which configuration you want to use. We recommend the '''aces_1.0.3''' configuration. You should see a file called '''config.ocio''' inside each of the configuration folders.
# Set an environment variable in your system called OCIO. The '''OCIO variable should be set to the full path and filename of the config.ocio file you want to use'''.

'''2. Restart Terragen after you change environment variables that affect OCIO'''

'''3. Enable OCIO in your Terragen project'''

In Terragen, OCIO is enabled or disabled on a ''per-project (per-scene) basis''. Click on '''Project Settings''' at the lower left of the main window, then turn on '''Use OCIO''' if it is not already on.

=== Command Line Arguments (Optional) ===

OCIO can be force-enabled with the command line argument "ocio" or "ocio=yes", as long as there is an environment variable named OCIO pointing to a valid OCIO config file. This command line argument causes Terragen to enable "Use OCIO" in Project Settings at startup and after a project is loaded. Terragen will default to roles which work well with ACES 1.0.3 but might not be compatible with your OCIO configuration, so 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 can be disabled with the command line argument "ocio=no". This causes Terragen to disable "Use OCIO" in Project Settings at startup and after a project is loaded.

=== First Tests ===

Toggling "Use OCIO" in Project Settings should cause the 3D Preview to refresh. If OCIO is configured correctly on your computer then you should also see the colours change in the 3D Preview. The difference may be subtle, but this depends on the OCIO configuration and the default choices for "Rendering space" and "Display space".

When "Use OCIO" is enabled, rendered images should also look different in the Render View.

When rendering with Path Tracer mode and viewing the 3D Preview in RTP mode, be sure to enable “Enable Path Tracing in the 3D Preview” button, above the 3D Preview pane.

[[File:TG_OCIO_RenderView_3DPreview_Settings_v002.jpg|None|867px|Terragen's 3D Preview pane and Render View pane using OCIO colour management and ACES colour space.]]

=== Choosing Colour Spaces ===

'''Rendering space'''

You can change the "Rendering space" but this should usually be "scene_linear" or "rendering". The former is more likely to be compatible with a wide range of OCIO configurations, and this is what Terragen chooses by default.

'''Display space'''

You can change the "Display space", but this should match your monitor. Terragen defaults to whichever display/view the OCIO configuration says is the default. Often this is "sRGB", but if you're unsure what to use then check with the person who set up your OCIO configuration.

'''Shader params (linear)'''

This allows you to choose the colour space that is used by the colour parameters in most shaders, with some exceptions. It doesn't apply to atmosphere parameters, and some other shaders have parameters which are locked to a raw colour space. We'll update this document soon with more details.

You should choose a linear colour space for "shader params (linear)". RGB values stored in Terragen scene files have always been linear, and Terragen automatically applies a gamma of 2.2 when editing colours with the colour picker.

By default, Terragen tries to find a colour space in your OCIO configuration which is linear and uses Rec.709 primaries, based on the name. If it finds a colour space that it thinks is suitable, it maps it to a special built-in role called "linear_rec709" which Terragen always add to the list if it doesn't find a role by that name in your OCIO config. By using this built-in role, our goal is for project files to be portable between different OCIO configurations that have this colour space even if there isn't a standardized name for it. If it makes the wrong choice you will need to choose something more appropriate. Please ensure that you choose a linear colour space for the shader params space.

If you want to change this to a colour space other than linear Rec.709, bear in mind that most assets generated by third parties will have been built assuming linear Rec.709.

'''8-bit textures'''

This allows you to choose the colour space that is used by Image Map Shaders which have "convert to linear" enabled in their options. It is also used by some of the images in the Default Shader.

By default, Terragen tries to find a colour space in your OCIO configuration which has the words "sRGB" and "texture" in its name. If it finds one it maps it to a special built-in role called "sRGB_texture" which Terragen always add to the list if it doesn't find a role by that name in your OCIO config. By using this built-in role, our goal is for project files to be portable between different OCIO configurations that have this colour space even if there isn't a standardized name for it. If it makes the wrong choice you will need to choose something more appropriate.

=== What's Supported in v4.5.43 ===

* You can choose the rendering/working space from the roles defined in the OCIO config. It defaults to "scene_linear", e.g. "scene_linear (ACES - ACEScg)".
* You can choose the display/view space from the displays/views defined in the OCIO config. It defaults to whichever display/view the OCIO config says is the default, e.g. "sRGB (ACES)".
* You can choose the colour spaces used by shader parameters (a linear colour space). It defaults to a special built-in role called "linear_rec709". If it doesn't find this in your OCIO config it tries to guess a suitable colour space by looking at the names of colour spaces in your config.
* You can choose the colour space to interpret 8-bit texture reads (usually sRGB). It defaults to a special built-in role called "sRGB_texture". If it doesn't find this in your OCIO config it tries to guess a suitable colour space using the words "sRGB" and "texture".
* 3D Preview refreshes when toggling OCIO checkbox or changing colour spaces in Project Settings.
* Render View refreshes when toggling OCIO checkbox or changing colour spaces in Project Settings.
* HDR renders are interpreted using whichever "Rendering space" is selected.
* LDR (display) version of the render is the result of tonemapping and transforming the HDR image using whichever "Display space" is selected.
* The Render View displays the LDR (display) version of the rendered image.
* Saving to an LDR file format (e.g. TIFF) saves the LDR (display) version of the image.
* Saving to EXR saves directly from the raw HDR render. Therefore you should interpret EXRs according to whichever "Rendering space" is selected, e.g. "scene_linear (ACES - ACEScg)". We presume this is what you want if you are using Terragen in a multi-app OCIO workflow.

=== Not Yet Supported ===

* Colour space for ''linear'' textures. At the moment, when you check "data is linear" it treats the image as raw data (in the rendering space).
* Choice of colour space per shader or node. In this version, conversion is done the same for all images that have "convert to linear" checked, and individual colour parameters on shaders are predefined to either be convertible or not.
* Independent choice of colour space for internal rendering and file output. Until we add this option, EXRs are output using the scene linear values that were generated by the renderer.

=== Examples ===
The following example uses Terragen's Colour Management with the Academy Color Encoding System (ACES) config profile. Special thanks to Bastien Muller for providing the rendered examples.

[[File:TG_OCIO_Comparision_FusionTerragenNuke_v002.jpg|None|867px|Side-by-side comparision of view-ports in Fusion, Terragen, and Nuke using ACES colour space.]]

Add Scalar

2022-01-28T03:59:22Z

Matt: Changed wording of luminance conversion and removed "from the zero origin" when talking about the length of a vector.

[[File:AddScalar_00a_GUI.png|none|470px|Add Scalar]]

__TOC__

== Overview ==
The Add family of nodes allow you to add the colour/scalar/vector coming into the Main Input with the colour/scalar/vector coming into Input 2.

The Add Scalar node adds two scalars together. It wants the incoming data to be scalars, but it will convert colours and vectors to scalars if necessary.

* When the source of the incoming data is colour data, the Add Scalar node converts the data to scalar based on the luminance of the colour. The math for this is: 0.2125 * r + 0.7152 *g + 0.0724 * b.

* When the source of the incoming data is vector data, the Add Scalar node converts the data to scalar based on the length of the vector. The math for this is: square_root(x*x + y*y + z*z).

'''Settings:'''

*'''Name:''' This setting allows you to apply a descriptive name to the node, which can be helpful when using multiple Add Scalar nodes in a project.
*'''Enable:''' When checked, the node is active and the Main Input value is added with the Input 2 value. When unchecked, only the Main Input value is passed through the node.
*'''Input 2:''' The values from the shader or function nodes assigned to this setting are added to the values of the Main Input.

== Fun with Add Scalar ==

[[File:AddScalar_09_ScalarToScalar.JPG|none|800px|The Add scalar node requires scalar data. Here the colour output from the red nodes is converted to scalar data via the Luminous to scalar nodes.]]

[[File:AddScalar_01_MainInputAndInput2.JPG|none|800px| Add scalar combines the Main Input and Input 2 component values, discarding displacement data, and outputting scalar data.]]

[[File:AddScalar_02_MainInputOnly.JPG|none|800px|When Input 2 is unassigned, data from the Main Input is passed through as scalar data.]]

[[File:AddScalar_03_Input2Only.JPG|none|800px|When the Main Input is unassigned, nothing is passed through.]]

[[File:AddScalar_04_ColourInputs.JPG|none|800px|When colour values are used as the source for the Main Input and Input 2, their component’s luminance values are used.]]

[[File:AddScalar_05_VectorInputs.JPG|none|800px|When vector values are used as the source, the scalar values are based on the length of the vector from a zero origin.]]

[[File:AddScalar_08_VectorAndColourInputs.JPG|none|800px|Vector and colour values can be used simultaneously as inputs to the Add Scalar node. Their component values are converted as necessary and output as scalar data.]]

 

[[Category: Add]]

Add Multiplied Scalar

2022-01-28T03:06:01Z

Matt: Changed wording of conversion based on luminance.

[[File:AddMultipliedScalar_00_GUI.png|none|470px|Add Multiplied Colour]]

__TOC__

== Overview ==

The Add Multiplied family of nodes will multiply the Main Input with Input 2 and add that result with the Main Input.

Mathematically it looks like this:
<ul>
(Main Input * Input 2) + Main Input
</ul>

When the incoming data is not scalar data, the node first converts the data to scalar as follows:
<ul>
For colour data, the node converts the data to scalar based on the luminance of the colour. The math for this is: 0.2125 * r + 0.7152 *g + 0.0724 * b. 
For vector data, the node converts the data to scalar based on the length of the vector from the zero origin. The math for this is: square_root(x*x + y*y + z*z).
</ul>

In the example images below, a proxy box labeled Add Multiplied Scalar Output is used for illustration to see the numerical output values.

In this example, the source data is scalar.
<ul>
[[File:AddMultipliedScalar_01_ConstantScalars.JPG|none|800px|When the source data is scalar, the Main input value is multiplied by the Input 2 value, and the result is added to the Main Input value.]]
</ul>

When the source data is colour, it is first converted to scalar data. Note that the node ignores the displacement data.
<ul>
{|
|-
|[[File:AddMultipliedScalar_02_PF3.JPG|none|800px|When the source data is colour, it is first converted to scalar. Note that the displacement data is ignored.]]
|-
|[[File:AddMultipliedScalar_03_PF3s.JPG|none|800px|When the source data is colour, it is first converted to scalar. Note that the displacement data is ignored.]]
|}
</ul>

If a shader or function nodes are not connected to Input 2, the Main Input passes through to the Output.
<ul>
[[File:AddMultipliedScalar_05_PF3MainInputOnly.JPG|none|800px|When Input 2 is disconnected, the Main Input is passed through.]]
</ul>

If a shader or function nodes are not connected to the Main Input, nothing passes through the node.
<ul>
[[File:AddMultipliedScalar_04_PF3Input2Only.JPG|none|800px|When the Main Input is disconnected, nothing is passed through the node.]]
</ul>

All nodes in this family have just one setting, which lets you assign a shader or function nodes to Input 2.

'''Settings:'''

* '''Name:''' This setting allows you to apply a descriptive name to the node, which can be helpful when using multiple Add Multiplied Scalar nodes in a project.

*'''Enable:''' When checked, the node is active and the Main Input value is first multiplied by Input 2 value, and the result is added to the Main Input value. When unchecked, only the Main Input value is passed through the node.

*'''Input 2:''' The values from the shader or function nodes assigned to this setting are multiplied with the values of the Main Input. The result of that is added to the Main Input value.

== Fun with Add Multiplied Scalar ==
The Add Multiplied Scalar node can be used to exaggerate the high or low values from the Main Input.

In this example, the displacement of the mound increases as the value of the Constant Scalar is raised. Note how the values in the Add multiplied scalar preview window are brighter than those of the Transform input shader preview window.
<ul>
{|
|-
| [[File:AddMultipliedScalar_07_SSSMound.jpg|None|800px|The Add multiplied scalar node can be used to increase the steepness of a terrain feature.]]
|-
| [[File:AddMultipliedScalar_10_AltMnt.jpg|None|800px|Another landscape example using the Add multiplied scalar node and Constant scalar node to increase the steepness of a terrain features.]]
|-
|[[File:AddMultipliedScalar_06_SSSMoundNodeNetwork.JPG|none|800px|The brightness of the power fractal noise values increase as the Constant scalar value is raised.]]
|}
</ul>

In the example below, the steepness of a river gorge or canyon can be controlled by increasing the value of the Constant Scalar.
<ul>
{|
|-
| [[File:AddMultipliedScalar_08_SSSRiverGorge.jpg|None|800px|The Add multiplied scalar node can be used to increase the steepness of a terrain feature.]]
|-
| [[File:AddMultipliedScalar_09_SSSRiverGorgeNodeNetwork.JPG|none|800px|The Simple shape shader’s beveled edge values become brighter as the Constant scalar value is raised.]]
|}
</ul>

 

[[Category: Add]]

Add Colour

2022-01-21T02:08:50Z

Matt: Minor edit to first sentence

[[File:AddColour_00_GUI.png|none|470px|Add Colour]]

__TOC__

== Overview ==

The Add family of nodes allow you to add the colour/scalar/vector coming into the Main Input with the color/scalar/vector coming into Input 2.

With Add Colour the addition is component-wise:

Main Input.red + Input 2.red 
Main Input.green + Input 2.green 
Main Input.blue + Input 2.blue

All nodes in this family have just one setting, which lets you assign a shader or function nodes to Input 2.

'''Settings:'''

*'''Name:''' This setting allows you to apply a descriptive name to the node, which can be helpful when using multiple Add Colour nodes in a project.

*'''Enable:''' When checked, the node is active and the Main Input value is added with the Input 2 value. When unchecked, only the Main Input value is passed through the node.

*'''Input 2:''' The values from the shader or function nodes assigned to this setting are added to the values of the Main Input.

== Fun with Add Colour ==

Remember that each of the colour component values, the red, green, and blue channel values, from the Main Input and the Input 2 settings are added together to achieve the final result.
<ul>
{|
|-
| [[File:AddColour_04_AddColour.jpg|none|800px|In this example, Main Input's colour values are red and the Input 2's colour values are green. When added together via the Add Colour node they make yellow.]]
|-
| [[File:AddColour_05_AddColourPF3.jpg|none|800px|In this example, a Power Fractal shader assigned to Input 2 provides green values and black values. When added together via the Add Colour node, the green values become shades of yellow while the black values let the red values from the Main Input pass through.]]
|}
</ul>

It’s possible for the component values to exceed the visual range of colours from pure black (0,0,0) to pure white (1,1,1), although this is not recommended, and in some shaders such as the Power Fractal v3 shader, parameters exist to clamp the colour component values at black or white.

In the example below, colours of the terrain appear unnaturally dark, almost burnt, when their colour component values are below 0,0,0. When component values exceed pure white, this can lead to clipping or unnatural shades of colour, such as the magenta areas in the image below.
<ul>
[[File:AddColour_06_AddColourExceed.jpg|none|800px|When the evaluated component values (RGB) exceed the 0 to 1 range, the resulting colours can appear clipped or burnt in. ]]
</ul>

 

[[Category: Add]]

Add Scalar

2022-01-21T01:48:23Z

Matt: Edited overview for clarity.

[[File:AddScalar_00_GUI.png|none|470px|Add Scalar]]

__TOC__

== Overview ==
The Add family of nodes allow you to add the colour/scalar/vector coming into the Main Input with the colour/scalar/vector coming into Input 2.

The Add Scalar node adds two scalars together. It wants the incoming data to be scalars, but it will convert colours and vectors to scalars if necessary.

* When the source of the incoming data is colour data, the Add Scalar node converts the data to scalar based on the component's luminance values. The math for this is: 0.2125 * r + 0.7152 *g + 0.0724 * b.

* When the source of the incoming data is vector data, the Add Scalar node converts the data to scalar based on the length of the vector from the zero origin. The math for this is: square_root(x*x + y*y + z*z).

'''Settings:'''

*'''Name:''' This setting allows you to apply a descriptive name to the node, which can be helpful when using multiple Add Scalar nodes in a project.
*'''Enable:''' When checked, the node is active and the Main Input value is added with the Input 2 value. When unchecked, only the Main Input value is passed through the node.
*'''Input 2:''' The values from the shader or function nodes assigned to this setting are added to the values of the Main Input.

== Fun with Add Scalar ==

[[File:AddScalar_01_MainInputAndInput2.JPG|none|800px| Add scalar combines the Main Input and Input 2 component values, discarding displacement data, and outputting scalar data.]]

[[File:AddScalar_02_MainInputOnly.JPG|none|800px|When Input 2 is unassigned, data from the Main Input is passed through as scalar data.]]

[[File:AddScalar_03_Input2Only.JPG|none|800px|When the Main Input is unassigned, nothing is passed through.]]

[[File:AddScalar_04_ColourInputs.JPG|none|800px|When colour values are used as the source for the Main Input and Input 2, their component’s luminance values are used.]]

[[File:AddScalar_05_VectorInputs.JPG|none|800px|When vector values are used as the source, the scalar values are based on the length of the vector from a zero origin.]]

[[File:AddScalar_06_VectorAndColourInputs.JPG|none|800px|Vector and colour values can be used simultaneously as inputs to the Add Scalar node. Their component values are converted as necessary and output as scalar data.]]

[[File:AddScalar_07_VDMAndColourInputs.JPG|none|800px|No matter the type of source data, the output of the Add Scalar node is scalar data.]]

 

[[Category: Add]]

Multiply Scalar

2022-01-21T01:44:17Z

Matt: Edited second sentence.

[[Image:drex_module_75_image_0.png|485pxpx|Multiply Scalar]]

__TOC__

== Overview ==
The Multiply family of nodes allow you to multiply the colour/scalar/vector coming into the Main Input by the color/scalar/vector coming into Input 2.

The Multiply Scalar node multiplies two scalars together. It wants the incoming data to be scalars, but it will convert colours and vectors to scalars if necessary.

* When the source of the incoming data is colour data, the Multiply Scalar node converts the data to scalar based on the component's luminance values. The math for this is: 0.2125 * r + 0.7152 *g + 0.0724 * b.

* When the source of the incoming data is vector data, the Multiply Scalar node converts the data to scalar based on the length of the vector from the zero origin. The math for this is: square_root(x*x + y*y + z*z).

All nodes in this family have just one setting, which lets you assign a shader or function nodes to Input 2.

[[Category:Multiply]]

Multiply Scalar

2022-01-21T01:42:40Z

Matt: Updated to be correct for scalars, not using the colour example.

[[Image:drex_module_75_image_0.png|485pxpx|Multiply Scalar]]

__TOC__

== Overview ==
The Multiply family of nodes allow you to multiply the colour/scalar/vector coming into the Main Input by the color/scalar/vector coming into Input 2.

The Multiply Scalar node wants the incoming data to be scalars, but it will convert colours and vectors to scalars if necessary.

* When the source of the incoming data is colour data, the Multiply Scalar node converts the data to scalar based on the component's luminance values. The math for this is: 0.2125 * r + 0.7152 *g + 0.0724 * b.

* When the source of the incoming data is vector data, the Multiply Scalar node converts the data to scalar based on the length of the vector from the zero origin. The math for this is: square_root(x*x + y*y + z*z).

All nodes in this family have just one setting, which lets you assign a shader or function nodes to Input 2.

[[Category:Multiply]]

Add Colour

2022-01-21T01:35:39Z

Matt: Made opening more specific to Add Colour

[[File:AddColour_00_GUI.png|none|470px|Add Colour]]

__TOC__

== Overview ==

The Add family of nodes allow you to add the colour/scalar/vector coming into the Main Input by the color/scalar/vector coming into Input 2.

With Add Colour the addition is component-wise:

Main Input.red + Input 2.red 
Main Input.green + Input 2.green 
Main Input.blue + Input 2.blue

All nodes in this family have just one setting, which lets you assign a shader or function nodes to Input 2.

'''Settings:'''

*'''Name:''' This setting allows you to apply a descriptive name to the node, which can be helpful when using multiple Add Colour nodes in a project.

*'''Enable:''' When checked, the node is active and the Main Input value is added with the Input 2 value. When unchecked, only the Main Input value is passed through the node.

*'''Input 2:''' The values from the shader or function nodes assigned to this setting are added to the values of the Main Input.

== Fun with Add Colour ==

Remember that each of the colour component values, the red, green, and blue channel values, from the Main Input and the Input 2 settings are added together to achieve the final result.
<ul>
{|
|-
| [[File:AddColour_04_AddColour.jpg|none|800px|In this example, Main Input's colour values are red and the Input 2's colour values are green. When added together via the Add Colour node they make yellow.]]
|-
| [[File:AddColour_05_AddColourPF3.jpg|none|800px|In this example, a Power Fractal shader assigned to Input 2 provides green values and black values. When added together via the Add Colour node, the green values become shades of yellow while the black values let the red values from the Main Input pass through.]]
|}
</ul>

It’s possible for the component values to exceed the visual range of colours from pure black (0,0,0) to pure white (1,1,1), although this is not recommended, and in some shaders such as the Power Fractal v3 shader, parameters exist to clamp the colour component values at black or white.

In the example below, colours of the terrain appear unnaturally dark, almost burnt, when their colour component values are below 0,0,0. When component values exceed pure white, this can lead to clipping or unnatural shades of colour, such as the magenta areas in the image below.
<ul>
[[File:AddColour_06_AddColourExceed.jpg|none|800px|When the evaluated component values (RGB) exceed the 0 to 1 range, the resulting colours can appear clipped or burnt in. ]]
</ul>

 

[[Category: Add]]

Add Vector

2022-01-21T01:34:11Z

Matt: Removed spaces between X,Y,Z lines, added line breaks instead

[[Image:drex_module_43_image_0.png|485pxpx|Add Vector]]

'''Node Description & Purpose:'''
The Add family of nodes allow you to add the colour/scalar/vector coming into the Input by the color/scalar/vector coming into Input 2.

With Add Vector the addition is component-wise:

Main Input.X + Input 2.X 
Main Input.Y + Input 2.Y 
Main Input.Z + Input 2.Z

'''Node Type:''' Function

'''Settings:'''
All nodes in this family have just the one setting, which lets you choose a node for Input 2.

[[Category: Add]]

Add Vector

2022-01-21T01:32:43Z

Matt: Undo revision 15718 by Matt (talk)

[[Image:drex_module_43_image_0.png|485pxpx|Add Vector]]

'''Node Description & Purpose:'''
The Add family of nodes allow you to add the colour/scalar/vector coming into the Input by the color/scalar/vector coming into Input 2.

With Add Vector the addition is component-wise:

Main input.X + Input 2.X

Main input.Y + Input 2.Y

Main input.Z + Input 2.Z

'''Node Type:''' Function

'''Settings:'''
All nodes in this family have just the one setting, which lets you choose a node for Input 2.

[[Category: Add]]

Add Vector

2022-01-21T01:31:54Z

Matt: Removed spacing between X, Y, Z lines

[[Image:drex_module_43_image_0.png|485pxpx|Add Vector]]

'''Node Description & Purpose:'''
The Add family of nodes allow you to add the colour/scalar/vector coming into the Input by the color/scalar/vector coming into Input 2.

With Add Vector the addition is component-wise:

Main input.X + Input 2.X
Main input.Y + Input 2.Y
Main input.Z + Input 2.Z

'''Node Type:''' Function

'''Settings:'''
All nodes in this family have just the one setting, which lets you choose a node for Input 2.

[[Category: Add]]

Add Vector

2022-01-21T01:30:39Z

Matt: Changed the example math from colour to vector.

[[Image:drex_module_43_image_0.png|485pxpx|Add Vector]]

'''Node Description & Purpose:'''
The Add family of nodes allow you to add the colour/scalar/vector coming into the Input by the color/scalar/vector coming into Input 2.

With Add Vector the addition is component-wise:

Main input.X + Input 2.X

Main input.Y + Input 2.Y

Main input.Z + Input 2.Z

'''Node Type:''' Function

'''Settings:'''
All nodes in this family have just the one setting, which lets you choose a node for Input 2.

[[Category: Add]]

Add Scalar

2022-01-21T01:21:14Z

Matt: Capitalizing S in Add Scalar

[[File:AddScalar_00_GUI.png|none|470px|Add Scalar]]

__TOC__

== Overview ==
The Add family of nodes allow you to add the colour/scalar/vector coming into the Main Input by the color/scalar/vector coming into Input 2.

The Add Scalar node wants the incoming data to be scalars, but it will convert colours and vectors to scalars if necessary.

When the source of the incoming data is colour data, the Add Scalar node converts the data to scalar based on the component's luminance values. The math for this is: 0.2125 * r + 0.7152 *g + 0.0724 * b.

When the source of the incoming data is vector data, the Add Scalar node converts the data to scalar based on the length of the vector from the zero origin. The math for this is: square_root(x*x + y*y + z*z).

All nodes in this family have just one setting, which lets you assign a shader or function nodes to Input 2.

'''Settings:'''

*'''Name:''' This setting allows you to apply a descriptive name to the node, which can be helpful when using multiple Add Scalar nodes in a project.
*'''Enable:''' When checked, the node is active and the Main Input value is added with the Input 2 value. When unchecked, only the Main Input value is passed through the node.
*'''Input 2:''' The values from the shader or function nodes assigned to this setting are added to the values of the Main Input.

== Fun with Add Scalar ==

[[File:AddScalar_01_MainInputAndInput2.JPG|none|800px| Add scalar combines the Main Input and Input 2 component values, discarding displacement data, and outputting scalar data.]]

[[File:AddScalar_02_MainInputOnly.JPG|none|800px|When Input 2 is unassigned, data from the Main Input is passed through as scalar data.]]

[[File:AddScalar_03_Input2Only.JPG|none|800px|When the Main Input is unassigned, nothing is passed through.]]

[[File:AddScalar_04_ColourInputs.JPG|none|800px|When colour values are used as the source for the Main Input and Input 2, their component’s luminance values are used.]]

[[File:AddScalar_05_VectorInputs.JPG|none|800px|When vector values are used as the source, the scalar values are based on the length of the vector from a zero origin.]]

[[File:AddScalar_06_VectorAndColourInputs.JPG|none|800px|Vector and colour values can be used simultaneously as inputs to the Add Scalar node. Their component values are converted as necessary and output as scalar data.]]

[[File:AddScalar_07_VDMAndColourInputs.JPG|none|800px|No matter the type of source data, the output of the Add Scalar node is scalar data.]]

 

[[Category: Add]]

Add Scalar

2022-01-21T01:19:14Z

Matt: Correction to previous edit

[[File:AddScalar_00_GUI.png|none|470px|Add Scalar]]

__TOC__

== Overview ==
The Add family of nodes allow you to add the colour/scalar/vector coming into the Main Input by the color/scalar/vector coming into Input 2.

The Add scalar node wants the incoming data to be scalars, but it will convert colours and vectors to scalars if necessary.

When the source of the incoming data is colour data, the Add scalar node converts the data to scalar based on the component's luminance values. The math for this is: 0.2125 * r + 0.7152 *g + 0.0724 * b.

When the source of the incoming data is vector data, the Add scalar node converts the data to scalar based on the length of the vector from the zero origin. The math for this is: square_root(x*x + y*y + z*z).

All nodes in this family have just one setting, which lets you assign a shader or function nodes to Input 2.

'''Settings:'''

*'''Name:''' This setting allows you to apply a descriptive name to the node, which can be helpful when using multiple Add Scalar nodes in a project.
*'''Enable:''' When checked, the node is active and the Main Input value is added with the Input 2 value. When unchecked, only the Main Input value is passed through the node.
*'''Input 2:''' The values from the shader or function nodes assigned to this setting are added to the values of the Main Input.

== Fun with Add Scalar ==

[[File:AddScalar_01_MainInputAndInput2.JPG|none|800px| Add scalar combines the Main Input and Input 2 component values, discarding displacement data, and outputting scalar data.]]

[[File:AddScalar_02_MainInputOnly.JPG|none|800px|When Input 2 is unassigned, data from the Main Input is passed through as scalar data.]]

[[File:AddScalar_03_Input2Only.JPG|none|800px|When the Main Input is unassigned, nothing is passed through.]]

[[File:AddScalar_04_ColourInputs.JPG|none|800px|When colour values are used as the source for the Main Input and Input 2, their component’s luminance values are used.]]

[[File:AddScalar_05_VectorInputs.JPG|none|800px|When vector values are used as the source, the scalar values are based on the length of the vector from a zero origin.]]

[[File:AddScalar_06_VectorAndColourInputs.JPG|none|800px|Vector and colour values can be used simultaneously as inputs to the Add Scalar node. Their component values are converted as necessary and output as scalar data.]]

[[File:AddScalar_07_VDMAndColourInputs.JPG|none|800px|No matter the type of source data, the output of the Add Scalar node is scalar data.]]

 

[[Category: Add]]

Add Scalar

2022-01-21T01:17:53Z

Matt: Replaced example of component-wise vector addition with a sentence about wanting incoming data to be scalar and converting if necessary.

[[File:AddScalar_00_GUI.png|none|470px|Add Scalar]]

__TOC__

== Overview ==
The Add family of nodes allow you to add the colour/scalar/vector coming into the Main Input by the color/scalar/vector coming into Input 2.

The Add scalar node wants to incoming data that are scalars, but it will convert colours and vectors to scalars if necessary.

When the source of the incoming data is colour data, the Add scalar node converts the data to scalar based on the component's luminance values. The math for this is: 0.2125 * r + 0.7152 *g + 0.0724 * b.

When the source of the incoming data is vector data, the Add scalar node converts the data to scalar based on the length of the vector from the zero origin. The math for this is: square_root(x*x + y*y + z*z).

All nodes in this family have just one setting, which lets you assign a shader or function nodes to Input 2.

'''Settings:'''

*'''Name:''' This setting allows you to apply a descriptive name to the node, which can be helpful when using multiple Add Scalar nodes in a project.
*'''Enable:''' When checked, the node is active and the Main Input value is added with the Input 2 value. When unchecked, only the Main Input value is passed through the node.
*'''Input 2:''' The values from the shader or function nodes assigned to this setting are added to the values of the Main Input.

== Fun with Add Scalar ==

[[File:AddScalar_01_MainInputAndInput2.JPG|none|800px| Add scalar combines the Main Input and Input 2 component values, discarding displacement data, and outputting scalar data.]]

[[File:AddScalar_02_MainInputOnly.JPG|none|800px|When Input 2 is unassigned, data from the Main Input is passed through as scalar data.]]

[[File:AddScalar_03_Input2Only.JPG|none|800px|When the Main Input is unassigned, nothing is passed through.]]

[[File:AddScalar_04_ColourInputs.JPG|none|800px|When colour values are used as the source for the Main Input and Input 2, their component’s luminance values are used.]]

[[File:AddScalar_05_VectorInputs.JPG|none|800px|When vector values are used as the source, the scalar values are based on the length of the vector from a zero origin.]]

[[File:AddScalar_06_VectorAndColourInputs.JPG|none|800px|Vector and colour values can be used simultaneously as inputs to the Add Scalar node. Their component values are converted as necessary and output as scalar data.]]

[[File:AddScalar_07_VDMAndColourInputs.JPG|none|800px|No matter the type of source data, the output of the Add Scalar node is scalar data.]]

 

[[Category: Add]]

Main Page

2022-01-19T16:04:01Z

Matt: Updated link to TerraTuts tutorials

== Welcome to the Planetside Software Wiki ==

This is the primary documentation repository for Planetside Software's Terragen environment modeling and rendering product. This documentation refers primarily to the latest version of Terragen (currently Terragen 4). Whenever the general term "Terragen" is used, it is referring to this most recent version, unless otherwise specified, e.g. "Terragen Classic".

This wiki contains official information as well as community-written content. Official documentation is clearly delineated from user contributed information by section below. We hope you find this to be a valuable resource and we encourage you to contact us if you'd like to contribute in the community-generated areas.

If you are a licensed user of Terragen and you need direct support, you can contact us via [https://planetside.co.uk/contact-us/ our contact page].

== Video Tutorials and Other Learning Resources ==

While the documentation below is the most comprehensive source of specific information about Terragen, many people find it easier to learn through video tutorials. There are links to several high quality, free tutorial channels on the [https://planetside.co.uk/terragen-tutorials/ Terragen Tutorials page] of our website. We recommend the [https://planetside.co.uk/terragen-terratuts-tutorials/ TerraTuts tutorials] for quickly learning Terragen basics.

You can also find some helpful techniques and in-depth discussions of specific technical issues on the [https://planetside.co.uk/category/tips-tricks/ Tips and Tricks] page. Check back regularly for new articles.

== Fundamental Terragen Concepts ==

Articles in this section cover concepts fundamental to understanding and using Terragen.

[[What is Terragen?]] 
An explanation of Terragen's design and purpose.

[[Terragen Conventions]] 
Some conventions of Terragen and how it differs from other 3D graphics programs.

[[Nodes]] 
Nodes are the fundamental building blocks of a Terragen scene. Learn more about how they work and are represented in the UI.

[[Shaders]] 
Shaders provide color and texture for the terrain in a scene.

[[Heightfield and Procedural Terrain]] 
Terragen allows the use of both heightfield and procedural terrain. Learn about the advantages and disadvantages of each.

== Getting Started ==

[[Tutorial 1: Creating Your First Scene]] 
A step-by-step tutorial on how to create a basic Terragen 4 scene.

[[Tutorial 2: Adding a Lake]] 
A guide to adding a lake to a Terragen scene.

== User Interface ==

Terragen's user interface is tailored to creating and rendering procedural landscapes and skies. This section will give you an overview of the Terragen user interface.

[[Terragen Menu Reference]] 
This article describes the top menus in Terragen.

[[Main Window User Interface Elements]] 
This article provides an overview of the main elements of the Terragen UI. You may refer to the following sections for details on specific elements of the UI:

* [[Top Toolbar]]

* [[Node List]]

* [[Shader Preview]]

* [[Node Properties]]

* [[The 3D Preview]]

* [[The Node Network]]

* [[Bottom Toolbar]]

[[Render Window]] 
This article describes the render window.

[[Terragen Window Reference|Window Reference]] 
This reference describes the different windows used in Terragen 4.

== Guides ==

[[Terragen Network View Guide|Network View Guide]] 
This is a guide to using the Node Network (Network View) in Terragen 4.

[[The Default Scene Explained]] 
When you open Terragen the first thing you see is a "default" scene, with basic terrain, planet, and atmosphere. This page explains how the default scene is set up.

[[Organizing Your Terragen Project]] 
An introduction to Groups, Clip Files and Notes, and other tips for sharing things between projects and keeping them organized.

[[Terrain and Water]] 
Detailed information on creating and controlling terrain and water features.

[[Surface Mapping and Shading]] 
Detailed information on applying surface maps, i.e. texturing, in Terragen 4. This section is oriented toward surface maps as applied to terrain, but much of the information also applies to object texturing.

[[The Library]] 
This is a guide to using the Library and Library window in TG4.

[[Working with Objects]] 
This is a guide to working with objects in TG4. It covers topics such as importing objects, creating objects, manipulating them in the 3D Preview and much more.

[[Populator Guide]] 
This is a guide to using Populator nodes. Populator nodes help you to quickly and efficiently add many objects, such as trees, to a scene.

[[Painted Shader Guide]] 
This guide explains how to use and get the most out of the Painted Shader.

[[Working with Clip Files]] 
This page introduces Clip files, how to create them and how to use them. Clip files let you save nodes or collections of nodes so you can use them again or send them to others.

[[Terragen 4 Animation Guide|Animation Guide]] 
This is a guide to using the Animation functions in Terragen. It has information and tutorials about creating animations using TG4.

[[Animated Easy Clouds]] 
A tutorial on the simple-to-use animation features built into Easy Clouds. The tutorial includes example videos and a project file that you can download.

[[Clouds Following Terrain Tutorial]] 
Get an in-depth understanding of some powerful cloud control functions in Terragen with this tutorial by Martin Huisman

[[Subsurface Scattering]] 
A guide to rendering subsurface scattering effects with the Glass Shader.

[[Troubleshooting Licenses]]

[[FAQs and Troubleshooting]]

== References ==

[[Terragen Node Reference]] 
Describes all the Terragen 4 nodes.

[[Glossary]] 
The Glossary explains terms relevant to Terragen.

[[Terragen Input Settings Reference|Input Settings Reference]] 
Lists all the input settings, such as mouse clicks and hot keys, that can be used in various views.

[[Terragen Menu Reference|Menu Reference]] 
Describes the menus in the Terragen 4 menu bar.

[[Terragen Window Reference|Window Reference]] 
Describes the different windows used in Terragen 4.

[[Terragen 4 Animation Function Reference|Animation Module Reference]] 

Gives an overview of the Animation Module as well as a reference for animation related windows and views.

[[Terragen Import-Export Reference|Import-Export Reference]] 

This reference describes Terragen 4's import and export capabilities.

[[Terragen Gathering Projects Reference|Gathering Projects Reference]] 

Describes the project gathering process, which allows you to gather a project and related assets into a single folder.

[[Rendering Methods]] 

Discusses the two rendering methods that Terragen uses: micropolygon rasterization and raytracing.

[[Path Tracing]] 
Beginning with Terragen 4.3, path tracing can be used to render more realistic images.

[[Ray Trace Objects and Defer Shading]] 
How and when to use the rendering options "Ray trace objects", "Defer atmo/cloud" and "Defer all shading".

[[Terragen 4 Global Illumination|Global Illumination]] 

Explains what Global Illumination is and how to use it in Terragen 4.

[[Render Layers and Render Elements|Render Layers and Render Elements (Terragen 4 Professional)]] 

Explains the Render Layers system in Terragen 4 Professional, including Render Elements.

[[OpenColorIO|OpenColorIO (OCIO)]]

Instructions for setting up OpenColorIO (OCIO) in Terragen Professional (v4.5+). It aims to allow you to work with colour spaces consistently with other applications in your pipeline.

[[Terragen Preferences|Preferences]] 

Describes Terragen 4's preferences, which let you customise how the application behaves.

[[Command Line Reference]] 

How to run Terragen from the command line on Windows, Mac and Linux, and descriptions of all the command line options.

== Terragen Resources ==

[[Terragen Resource List]]

Find Terragen-compatible software, 3D models, content, and other resources.

== Terragen Community-Generated Content ==

[[Terragen Tips and Tricks]] 
Some quick tips and tricks for using Terragen, generated and maintained by our user community.

[[Terragen Tutorials]] 
A list of tutorials, from beginning to advanced, to take you through how to do certain things with Terragen.

Daniil Kamperov::Classic Erosion

2021-10-14T02:16:33Z

Matt: Added link to User Guide on daniilkamperov.com

User Guide for Classic Erosion by Daniil Kamperov:

https://daniilkamperov.com/download/Classic-Erosion-User-Guide.pdf

Reflective Shader

2021-02-26T07:18:41Z

Matt: Updated index of refraction

[[File:ReflShdr_00_GUI.png|none|470px|Reflective Shader]]

__TOC__

== Overview ==
The Reflective Shader provides a reflectivity effect for surfaces which can simulate wet, smooth, and otherwise shiny surfaces. Control is provided over the strength of the reflectivity, the reflection tint, transparency, index of refraction, and whether reflections are Ray Traced.

'''Settings:'''
<ul>
*'''Enable: '''When checked, the node is active and the settings below will affect the surface. When unchecked, the node is ignored.
</ul>

== Main Tab ==
[[File:ReflShdr_01_MainTab_GUI.png|none|470px|Main Tab]]

<ul>
*'''Reflectivity: '''This setting controls how reflective the surface is. Higher values are more reflective. While you can change the colour of the reflectivity via the Colour picker to the right of the slider, it’s recommended that you use the “Reflection tint” to change the colour. This allows you to separately adjust the brightness and the colour of the reflectivity.
<ul>
{|
|-
| [[File:ReflShdr_04_Reflectivity0p25.jpg|none|266px|Reflectivity = 0.25]] || [[File:ReflShdr_05_Reflectivity0p5.jpg|none|266px|Reflectivity = 0.5]] || [[File:ReflShdr_06_Reflectivity1.jpg|none|266px|Reflectivity = 1.0]]
|}
</ul>

*'''Reflection tint: ''' This setting allows you to tint the reflected colours by the color chosen via the Colour picker to the right of the slider.
<ul>
{|
|-
| [[File:ReflShdr_10_Reflectivity0p25_ReflTintRed.jpg|none|266px|Reflection tint = sRGB 229,50,50, Reflectivity = 0.25]] || [[File:ReflShdr_11_Reflectivity0p5_ReflTintRed.jpg|none|266px|Reflection tint = sRGB 229,50,50, Reflectivity = 0.5]] || [[File:ReflShdr_12_Reflectivity0p25_ReflTintRed.jpg|none|266px|Reflection tint = sRGB 229,50,50, Reflectivity = 1.0]]
|}
</ul>

*'''Index of refraction: ''' Index of refraction (IOR) is a property of real world materials which affects light refracted into it from another medium. Despite its name it also affects the amount of light ''reflected'' off the surface for a given angle; in other words it changes the reflectivity curve which is calculated using the Fresnel equations. In the Reflective Shader the IOR setting must be >= 1. When IOR is exactly 1 there is no reflection. When IOR is greater than 1 some amount of reflection occurs, and the higher the IOR the more visible the reflections. For ''any'' IOR > 1, the reflectivity approaches 100% at glancing angles where light travels parallel to the surface (although this can be changed with the Reflectivity setting and roughness also makes it appear to be less). At any other angle the amount of reflection is reduced, calculated from the IOR. The IOR of water is usually around 1.33, depending on conditions, and most types of glass are between 1.4 and 1.9. IOR is rarely higher than 4.0 in real materials. However, you might want to go higher than this to simulate metals. A higher index of refraction can be used to produce higher reflectivity at perpendicular angles, but this is essentially just a cheat and is not a physically-based way to render metal.
<ul>
{|
|-
| [[File:ReflShdr_13_IOR1.jpg|none|266px|IOR = 1]] || [[File:ReflShdr_14_IOR1p1.jpg|none|266px|IOR = 1.1]] || [[File:ReflShdr_15_IOR1p25.jpg|none|266px|IOR = 1.25]]
|-
| [[File:ReflShdr_16_IOR1p33.jpg|none|266px|IOR = 1.33 (default)]] || [[File:ReflShdr_17_IOR1p5.jpg|none|266px|IOR = 1.5]] || [[File:ReflShdr_18_IOR2.jpg|none|266px|IOR = 2.0]]
|}
</ul>

*'''Specular highlights: ''' This popup has 4 options for choosing the method of calculating the specular highlights.
<ul>
[[File:ReflShdr_03_MainTab_SpecularHighlightOptions_GUI.png|none|326px|Specular highlight methods.]]
{|
|-
| [[File:ReflShdr_19_SpecularHightlightsBlinn.jpg|none|200px|Specular highlights = Blinn]] || [[File:ReflShdr_20_SpecularHightlightsBeckmannTG2.jpg|none|200px|Specular highlights = Beckmann TG 2]] || [[File:ReflShdr_21_SpecularHightlightsBeckmannTG45.jpg|none|200px|Specular highlights = Beckmann TG 4.5]] || [[File:ReflShdr_22_SpecularHightlightsGGX.jpg|none|200px|Specular highlights = GGX]]
|}
</ul>

*'''Highlight intensity: ''' This setting controls the brightness of the specular highlight. A value of “0” results in no specular highlights, while increasing the value will brighten the highlight.
<ul>
{|
|-
| [[File:ReflShdr_23_HighlightIntensity0.jpg|none|266px|Highlight intensity = 0.0]] || [[File:ReflShdr_24_HighlightIntensity1.jpg|none|266px|Highlight intensity = 1.0]] || [[File:ReflShdr_25_HighlightIntensity4.jpg|none|266px|Highlight intensity = 4.0]]
|}
</ul>

*'''Caustic intensity: '''

*'''Specular roughness: ''' This setting controls how the specular highlight spreads out across the surface. Small values result in smaller, sharper and brighter highlights, while larger values result in larger, softer and more diffused highlights.
<ul>
{|
|-
| [[File:ReflShdr_26_SpecularRoughness0p01.jpg|none|266px|Specular roughness = 0.01]] || [[File:ReflShdr_27_SpecularRoughness0p1.jpg|none|266px|Specular roughness = 0.1]] || [[File:ReflShdr_28_SpecularRoughness0p2.jpg|none|266px|Specular roughness = 0.2]]
|}
</ul>

*'''Roughness function: '''The shader or function nodes assigned to this setting are multiplied by the “Specular roughness” value above which allow you to adjust or break up the intensity of the specular highlight. Note that negative results are clamped to 0.
<ul>
{|
|-
| [[File:ReflShdr_29_RoughnessFunctionPF0p01.jpg|none|266px|Power fractal shader assigned to Roughness function. Apply high colour = 0.01]] || [[File:ReflShdr_30_RoughnessFunctionPF0p1.jpg|none|266px|Power fractal shader assigned to Roughness function. Apply high colour = 0.1]] || [[File:ReflShdr_31_RoughnessFunctionPF0p2.jpg|none|266px|Power fractal shader assigned to Roughness function. Apply high colour = 0.2]]
|-
| [[File:ReflShdr_32_RoughnessFunctionPF0p5.jpg|none|266px|Power fractal shader assigned to Roughness function. Apply high colour = 0.5]] || [[File:ReflShdr_33_RoughnessFunctionPF1.jpg|none|266px|Power fractal shader assigned to Roughness function. Apply high colour = 1.0]] ||
|}
</ul>

*'''Ray traced reflections: ''' When checked, reflections are ray traced for the surface and accurately reflect the scene. When unchecked, only the specular effect will render.
<ul>
{|
|-
| [[File:ReflShdr_34_RayTracedReflOn.jpg|none|400px|Ray traced reflections checked.]] || [[File:ReflShdr_35_RayTracedReflOff.jpg|none|400px|Ray traced reflections unchecked.]]
|}
</ul>

*'''Reflection softness: ''' Together with the “Number of samples” setting on the Quality tab, this setting controls the blurriness of the reflections. The default value of “0” results in sharp reflections and uses only one sample regardless of the number of samples chosen. Although the slider allows for a large range of values, the recommended range is between 0.0 to 0.1.
<ul>
{|
|-
| [[File:ReflShdr_42_ReflectionSoftness0.jpg|none|266px|Reflection softness = 0.0]] || [[File:ReflShdr_43_ReflectionSoftness0p05.jpg|none|266px|Reflection softness = 0.05]] || [[File:ReflShdr_44_ReflectionSoftness0p1.jpg|none|266px|Reflection softness = 0.1]]
|}
</ul>
</ul>

== Quality Tab ==
[[File:ReflShdr_02_QualityTab_GUI.png|none|470px|Quality Tab]]

<ul>
*'''Number of samples: '''This setting controls the quality of the soft reflections, which occur when the “Reflection softness” value is greater than “0”. The default value is “4” and raising it will take additional samples leading to a smoother blurred result, at the cost of longer render times.
<ul>
{|
|-
| [[File:ReflShdr_38_ReflSoft0p1_NumSamples4.jpg|none|400px|Reflection softness = 0.1, Number of samples = 4.]] || [[File:ReflShdr_39_ReflSoft0p1_NumSamples16.jpg|none|400px|Reflection softness = 0.1, Number of samples = 16.]]
|-
| [[File:ReflShdr_40_ReflSoft0p1_NumSamples32.jpg|none|400px|Reflection softness = 0.1, Number of samples = 32.]] || [[File:ReflShdr_41_ReflSoft0p1_NumSamples64.jpg|none|400px|Reflection softness = 0.1, Number of samples = 64.]]
|}
</ul>

</ul>

[[Category:Surface Shader]]

OpenColorIO

2021-02-23T22:07:02Z

Matt: Removed some images from the Other Considerations section. This entire section should be removed at some point.

[[File:TG_OCIO_Project_Settings_Colour_Managment.PNG|None|500px|Terragen's Project Settings Colour Management interface]]

=== Overview ===

OpenColorIO (OCIO) is integrated into Terragen 4.5 Professional. It aims to allow you to work with colour spaces consistently with other applications in your pipeline.
{|
|-
| [[File:Wiki_TG45_OCIO_RenderRec709_ViewRec709.jpg|none|400px|Terragen default scene, rendered and viewed in Rec 709 colour space.]] || [[File:Wiki_TG45_OCIO_RenderRec709_ViewACEScg.jpg|none|400px|Terragen default scene, rendered in Rec 709 colour space, viewed in ACEScg colour space.]]
|-
| [[File:Wiki_TG45_OCIO_RenderACEScg_ViewRec709.jpg|none|400px|Terragen default scene, rendered in ACEScg colour space, viewed in Rec 709 colour space.]] || [[File:Wiki_TG45_OCIO_RenderACEScg_ViewACEScg.jpg|none|400px|Terragen default scene, rendered and viewed in ACEScg colour space.]]
|}
 

=== Requirements ===

'''1. Set up OCIO on your computer'''

If you're working at a company that uses OCIO, this has probably already been done for you.

If you don't have OCIO set up, follow these instructions:

# Download the Sample OCIO Configurations at http://github.com/imageworks/OpenColorIO-Configs/zipball/master
# Extract the contents of the .zip file to your computer.
# Decide which configuration you want to use. We recommend the '''aces_1.0.3''' configuration. You should see a file called '''config.ocio''' inside each of the configuration folders.
# Set an environment variable in your system called OCIO. The '''OCIO variable should be set to the full path and filename of the config.ocio file you want to use'''.

'''2. Restart Terragen after you change environment variables that affect OCIO'''

'''3. Enable OCIO in your Terragen project'''

In Terragen, OCIO is enabled or disabled on a ''per-project (per-scene) basis''. Click on '''Project Settings''' at the lower left of the main window, then turn on '''Use OCIO''' if it is not already on.

=== Command Line Arguments (Optional) ===

OCIO can be force-enabled with the command line argument "ocio" or "ocio=yes", as long as there is an environment variable named OCIO pointing to a valid OCIO config file. This command line argument causes Terragen to enable "Use OCIO" in Project Settings at startup and after a project is loaded. Terragen will default to roles which work well with ACES 1.0.3 but might not be compatible with your OCIO configuration, so 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 can be disabled with the command line argument "ocio=no". This causes Terragen to disable "Use OCIO" in Project Settings at startup and after a project is loaded.

=== First Tests ===

Toggling "Use OCIO" in Project Settings should cause the 3D Preview to refresh. If OCIO is configured correctly on your computer then you should also see the colours change in the 3D Preview. The difference may be subtle, but this depends on the OCIO configuration and the default choices for "Rendering space" and "Display space".

When "Use OCIO" is enabled, rendered images should also look different in the Render View.

When rendering with Path Tracer mode and viewing the 3D Preview in RTP mode, be sure to enable “Enable Path Tracing in the 3D Preview” button, above the 3D Preview pane.

[[File:TG_OCIO_RenderView_3DPreview_Settings_v002.jpg|None|867px|Terragen's 3D Preview pane and Render View pane using OCIO colour management and ACES colour space.]]

=== Choosing Colour Spaces ===

'''Rendering space'''

You can change the "Rendering space" but this should usually be "scene_linear" or "rendering". The former is more likely to be compatible with a wide range of OCIO configurations, and this is what Terragen chooses by default.

'''Display space'''

You can change the "Display space", but this should match your monitor. Terragen defaults to whichever display/view the OCIO configuration says is the default. Often this is "sRGB", but if you're unsure what to use then check with the person who set up your OCIO configuration.

'''Shader params (linear)'''

This allows you to choose the colour space that is used by the colour parameters in most shaders, with some exceptions. It doesn't apply to atmosphere parameters, and some other shaders have parameters which are locked to a raw colour space. We'll update this document soon with more details.

You should choose a linear colour space for "shader params (linear)". RGB values stored in Terragen scene files have always been linear, and Terragen automatically applies a gamma of 2.2 when editing colours with the colour picker.

By default, Terragen tries to find a colour space in your OCIO configuration which is linear and uses Rec.709 primaries, based on the name. If it finds a colour space that it thinks is suitable, it maps it to a special built-in role called "linear_rec709" which Terragen always add to the list if it doesn't find a role by that name in your OCIO config. By using this built-in role, our goal is for project files to be portable between different OCIO configurations that have this colour space even if there isn't a standardized name for it. If it makes the wrong choice you will need to choose something more appropriate. Please ensure that you choose a linear colour space for the shader params space.

If you want to change this to a colour space other than linear Rec.709, bear in mind that most assets generated by third parties will have been built assuming linear Rec.709.

'''8-bit textures'''

This allows you to choose the colour space that is used by Image Map Shaders which have "convert to linear" enabled in their options. It is also used by some of the images in the Default Shader.

By default, Terragen tries to find a colour space in your OCIO configuration which has the words "sRGB" and "texture" in its name. If it finds one it maps it to a special built-in role called "sRGB_texture" which Terragen always add to the list if it doesn't find a role by that name in your OCIO config. By using this built-in role, our goal is for project files to be portable between different OCIO configurations that have this colour space even if there isn't a standardized name for it. If it makes the wrong choice you will need to choose something more appropriate.

=== What's Supported in v4.5.43 ===

* You can choose the rendering/working space from the roles defined in the OCIO config. It defaults to "scene_linear", e.g. "scene_linear (ACES - ACEScg)".
* You can choose the display/view space from the displays/views defined in the OCIO config. It defaults to whichever display/view the OCIO config says is the default, e.g. "sRGB (ACES)".
* You can choose the colour spaces used by shader parameters (a linear colour space). It defaults to a special built-in role called "linear_rec709". If it doesn't find this in your OCIO config it tries to guess a suitable colour space by looking at the names of colour spaces in your config.
* You can choose the colour space to interpret 8-bit texture reads (usually sRGB). It defaults to a special built-in role called "sRGB_texture". If it doesn't find this in your OCIO config it tries to guess a suitable colour space using the words "sRGB" and "texture".
* 3D Preview refreshes when toggling OCIO checkbox or changing colour spaces in Project Settings.
* Render View refreshes when toggling OCIO checkbox or changing colour spaces in Project Settings.
* HDR renders are interpreted using whichever "Rendering space" is selected.
* LDR (display) version of the render is the result of tonemapping and transforming the HDR image using whichever "Display space" is selected.
* The Render View displays the LDR (display) version of the rendered image.
* Saving to an LDR file format (e.g. TIFF) saves the LDR (display) version of the image.
* Saving to EXR saves directly from the raw HDR render. Therefore you should interpret EXRs according to whichever "Rendering space" is selected, e.g. "scene_linear (ACES - ACEScg)". We presume this is what you want if you are using Terragen in a multi-app OCIO workflow.

=== Not Yet Supported ===

* Colour space for ''linear'' textures. At the moment, when you check "data is linear" it treats the image as raw data (in the rendering space).
* Choice of colour space per shader or node. In this version, conversion is done the same for all images that have "convert to linear" checked, and individual colour parameters on shaders are predefined to either be convertible or not.
* Independent choice of colour space for internal rendering and file output. Until we add this option, EXRs are output using the scene linear values that were generated by the renderer.

=== Other Considerations ===

'''''This information pertains to Frontier Builds from 4.5.32 up to 4.5.43 only.'''''

The default atmosphere has colours which were chosen for a Rec. 709 (sRGB) pipeline. They don't know about your OCIO config. If you're using an ACES configuration, for example, you might find that the sky looks too green.



[[File:TG_OCIO_OtherConsiderations_02_DefaultAtmoNoToneMap_ColManACES.jpg|None|867px|Terragen default atmosphere without Terragen tone mapping. Terragen project Colour Management enabled. Display space is sRGB(ACES).]]

'''''Frontier Builds from 4.5.32 up to 4.5.43 only.'''''

If this affects you, you might find the following adjustments useful:

* '''Bluesky horizon colour''' (on the Main tab): reduce the green channel very slightly so that it's closer to the red value than the blue value. For a less saturated look, simply make it greyscale 0.25 (135, 135, 135).

[[File:TG_OCIO_Atmosphere_Recommended_Settings.PNG|None|470px|Atmosphere Main tab.]]
[[File:TG_OCIO_Atmosphere_ColorPicker_Recommended_Settings.PNG|None|280px|Colour picker values for Bluesky horizon colour.]]

* '''Bluesky density colour''' (on the Tweaks tab): increase the red channel so that it's a little closer to the green value.

[[File:TG_OCIO_Atmosphere_BlueskyDensityColour_Recommended.PNG|None|470px|Atmosphere Tweaks tab.]]
[[File:TG_OCIO_Atmosphere_BlueSkyDensityColourPicker.PNG|None|280px|Colour picker values for Bluesky density colour.]]

=== Examples ===
The following example uses Terragen's Colour Management with the Academy Color Encoding System (ACES) config profile. Special thanks to Bastien Muller for providing the rendered examples.

[[File:TG_OCIO_Comparision_FusionTerragenNuke_v002.jpg|None|867px|Side-by-side comparision of view-ports in Fusion, Terragen, and Nuke using ACES colour space.]]

Linux Command Line Reference (TG4)

2021-01-04T18:06:11Z

Matt: OCIO arguments, 4.5.56

This document is a mirror of the file 'linux_command_line.txt' in the Terragen 4 for Linux distribution.

Updated 4/January/2021 (build 4.5.56)

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

IMPORTANT: Currently 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.

-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.
<nodename> must be the name of a render node in the project.
Projects loaded subsequently are not affected.

-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

Mac Command Line Reference (TG4)

2021-01-04T18:03:53Z

Matt: OCIO arguments, 4.5.56

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

Updated 4/January/2021 (build 4.5.56)

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

Terragen 4 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 4 from the command line you need to access the executable directly. Terragen 4 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 TG4>/Terragen 4.app/Contents/MacOS/'

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

Notice that the first part of the path is "Terragen 4.app". This is name of the special application folder mentioned above, which is what you see in the Finder as the actual Terragen 4 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 4.app" application folder.

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

./'Terragen 4'

N.B. You will need to use single quotes around paths (as I have above), because of the spaces in the "Terragen 4" 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 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 4'

Run Terragen 4 and load a project file:

./'Terragen 4' -p project.tgd

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

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

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

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

IMPORTANT: Currently 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.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.
<nodename> must be the name of a render node in the project.
Projects loaded subsequently are not affected.

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

-w <filename>

The same as the -p option

Windows Command Line Reference (TG4)

2021-01-04T18:02:02Z

Matt:

This document is a mirror of the file 'win_command_line.txt' in the Docs folder in the Terragen 4 folder.

Updated 4/January/2021 (build 4.5.56)

-----------------------------------------------------------
Running Terragen 4 From a Command Line or Shell environment
-----------------------------------------------------------

Two executables are provided with TG4:

tgd.exe: Does not print anything to the console. Returns to the command prompt immediately while continuing to run in the background.

tgdcli.exe: Exactly the same as tgd.exe, except that it prints messages and warnings to the console and it only returns to the command prompt after execution has finished.

Both executables can be run either with or without a GUI, and both share the same command line options.

SETUP
-----

tgd or tgdcli can be launched from the command line in a number of different modes. However, before you try running them from the command line it's wise to set up some environment variables.

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 tgdcli 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, on the Windows command line or batch file:

set TERRAGEN_PATH=C:\Program Files\Planetside Software\Terragen 4

In other shells you would use the appropriate syntax (such as setenv).

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 the environment variable is set, you can run Terragen. Here are some examples at the Windows command prompt or in a batch file. In other shells you would probably replace %TERRAGEN_PATH% with $TERRAGEN_PATH.

Quotes are used to surround the executable path, because TERRAGEN_PATH may contains spaces.

Run Terragen as normal:

"%TERRAGEN_PATH%/tgdcli"

Run Terragen and load a project file:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd

Run Terragen without the GUI, render frame 42, then close:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd -hide -exit -r -f 42

Run Terragen without the GUI, render frames 1,4,51,53,55,57,59, then close:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd -hide -exit -r -f 1,4,51-60/2

IMPORTANT: Currently 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.
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. 'C:\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:

'C:\frames\image.0023.IMAGETYPE.exr'

may result in:

'C:\frames\image.0023.tgAlpha.exr' 
'C:\frames\image.0023.tgSurfRgb.exr' 
'C:\frames\image.0023.tgSurfAlpha.exr' 
etc.

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

'C:\frames\tgAlpha\image.0023.tgAlpha.exr' 
'C:\frames\tgSurfRgb\image.0023.tgSurfRgb.exr' 
'C:\frames\tgSurfAlpha\image.0023.tgSurfAlpha.exr' 
etc.

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

'C:\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:

'C:\frames\image.0023.exr'

may result in:

'C:\frames\tgAlpha\image.0023.exr' 
'C:\frames\tgSurfRgb\image.0023.exr' 
'C:\frames\tgSurfAlpha\image.0023.exr' 
etc.

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

'C:\frames\tgAlpha\image.0023.tgAlpha.exr' 
'C:\frames\tgSurfRgb\image.0023.tgSurfRgb.exr' 
'C:\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.
<nodename> must be the name of a render node in the project.
Projects loaded subsequently are not affected.

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

-w <filename>

The same as the -p option

Windows Command Line Reference (TG4)

2021-01-04T18:00:12Z

Matt: OCIO arguments

This document is a mirror of the file 'win_command_line.txt' in the Docs folder in the Terragen 4 folder.

Updated 26/November/2020 (build 4.5.46)

-----------------------------------------------------------
Running Terragen 4 From a Command Line or Shell environment
-----------------------------------------------------------

Two executables are provided with TG4:

tgd.exe: Does not print anything to the console. Returns to the command prompt immediately while continuing to run in the background.

tgdcli.exe: Exactly the same as tgd.exe, except that it prints messages and warnings to the console and it only returns to the command prompt after execution has finished.

Both executables can be run either with or without a GUI, and both share the same command line options.

SETUP
-----

tgd or tgdcli can be launched from the command line in a number of different modes. However, before you try running them from the command line it's wise to set up some environment variables.

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 tgdcli 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, on the Windows command line or batch file:

set TERRAGEN_PATH=C:\Program Files\Planetside Software\Terragen 4

In other shells you would use the appropriate syntax (such as setenv).

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 the environment variable is set, you can run Terragen. Here are some examples at the Windows command prompt or in a batch file. In other shells you would probably replace %TERRAGEN_PATH% with $TERRAGEN_PATH.

Quotes are used to surround the executable path, because TERRAGEN_PATH may contains spaces.

Run Terragen as normal:

"%TERRAGEN_PATH%/tgdcli"

Run Terragen and load a project file:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd

Run Terragen without the GUI, render frame 42, then close:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd -hide -exit -r -f 42

Run Terragen without the GUI, render frames 1,4,51,53,55,57,59, then close:

"%TERRAGEN_PATH%/tgdcli" -p myproject.tgd -hide -exit -r -f 1,4,51-60/2

IMPORTANT: Currently 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.
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. 'C:\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:

'C:\frames\image.0023.IMAGETYPE.exr'

may result in:

'C:\frames\image.0023.tgAlpha.exr' 
'C:\frames\image.0023.tgSurfRgb.exr' 
'C:\frames\image.0023.tgSurfAlpha.exr' 
etc.

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

'C:\frames\tgAlpha\image.0023.tgAlpha.exr' 
'C:\frames\tgSurfRgb\image.0023.tgSurfRgb.exr' 
'C:\frames\tgSurfAlpha\image.0023.tgSurfAlpha.exr' 
etc.

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

'C:\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:

'C:\frames\image.0023.exr'

may result in:

'C:\frames\tgAlpha\image.0023.exr' 
'C:\frames\tgSurfRgb\image.0023.exr' 
'C:\frames\tgSurfAlpha\image.0023.exr' 
etc.

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

'C:\frames\tgAlpha\image.0023.tgAlpha.exr' 
'C:\frames\tgSurfRgb\image.0023.tgSurfRgb.exr' 
'C:\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.
<nodename> must be the name of a render node in the project.
Projects loaded subsequently are not affected.

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

-w <filename>

The same as the -p option

Default Shader 4.5

2020-12-28T11:44:00Z

Matt: Remap ^2 after invert

[[File:DefShdr_00_GUI_ColourTab.png|none|470px|Default Shader GUI]]
 
== Overview ==
The Default shader is primarily designed for use with imported 3D assets from third-party applications. It is an extremely flexible shader capable of defining new surface materials or allowing you to assign existing texture maps to its attributes. With the release of Terragen 4.5 the shader’s settings, tabs and layout has been updated to maximize compatibility with Metallic / Roughess, and Specular / Glossiness workflows based on the Physically Based Rendering (PBR) model.

Just as in prior versions of the shader, many of its common settings are grouped together, such as the “Base colour”, “Colour image” and “Colour function” settings. It’s important to understand that when settings are grouped together like this their colour component values are multiplied with each other to determine the final colour as in the example below.

{|
|-
| [[File:DefShdr_37_ColourTab_BaseColour.jpg|none|400px|Base colour sRGB 240,99,70 chosen via the Colour Picker pane.]] || [[File:DefShdr_35_ColourTab_ColourImage.jpg|none|400px|Colour derived by multiplying Base colour and pixels from image map.]]
|-
| [[File:Wiki_DefShdr_131_ColourTab_ColourFunctionPF3.jpg|none|400px|Colour derived by multiplying Base colour and values from Power fractal shader.]] || [[File:Wiki_DefShdr_132_ColourTab_ColourImageColourFunction.jpg|none|400px|Colour derived by multiplying all three colour sources.]]
|}

When applying texture maps containing “final colour” values for an asset, such as a uv mapped character, a hero object, or Megascans object, the “Base colour” value should be set to 1.0. If you wish to darken or tint the “final colour” values you can change the “Base colour” as needed.

[[File:WIki_DefShdr_132_Overview_BaseColours.jpg|none|800px|Varying the "Base colour" tints the final base colour on a texture-mapped object.]]

 

== Colour Tab ==
[[File:DefShdr_01_GUI_ColourTab.png|none|470px|Colour Tab]]
 

'''Base colour''' 

For a Metallic/Roughness workflow you can use the base colour to define the colour (albedo) of both metals and non-metals. Metallic surfaces have specular reflections that use the base colour as their main reflectivity colour. Non-metallic surfaces have a diffuse base layer that uses the base colour as its diffuse reflectivity.

For a Specular/Glossiness workflow, use the base colour to set the diffuse colour only. In this workflow the base colour should be set to 0.0 for raw metallic surfaces that have no diffuse reflectivity. For non-metal surfaces, including dirt and grime that may rest upon a raw metal surface, the colour values represent the colour of the diffuse material.

* ''' Base colour: '''This setting provides access to the [[Colour_Picker | Colour Picker]] window in order to specify a base colour for the surface. The adjustment slider can be used to modify the brightness of the colour value.
<ul>
{|
|-
| [[File:Wiki_DefShdr_90_ColourTab_BaseColour0-1rygcbm.jpg|none|800px|Base colour examples: 0, 0.25, 0.5, 0.75, 1.0, red, yellow, green, cyan, blue, magenta.]]
|}
</ul>
* ''' Colour image: '''This setting allows you to assign an image map to the surface’s colour channels. The image map is projected onto the surface as defined on the Images tab.
<ul>
[[File:Wiki_DefShdr_129_ColourTab_ColourImage.jpg|none|400px|Image map assigned to Colour image setting.]]
</ul>
* ''' Colour function: ''' This setting allows you to assign shader or function nodes to the surface’s colour channels.
<ul>
[[File:Wiki_DefShdr_130_ColourTab_ColourFunction.jpg|none|400px|Power fractal shader assigned to Colour function setting.]]
</ul>
 

'''Translucency''' 

Translucency is the effect of light filtering through a surface. For example you might use translucency on a leaf texture to simulate light passing through it. It's not the same thing as opacity and is explained in more detail [[Translucency|here]]. The three settings of the translucency group are multiplied together to determine the final amount of translucency of the surface.
* ''' Translucency: '''This setting specifies the amount of translucency a surface has, and acts as a multiplier to the "Translucency image" and "Translucency function" settings. Translucency is the effect of light filtering through a surface, and more information may be found [[Translucency|here]].
* ''' Translucency image: '''This setting allows you to assign an image map to control the amount and location of translucency on the surface. The image map is projected onto the surface as defined on the Images tab.
* ''' Translucency function: '''This setting allows you to assign shader or function nodes to control the amount and location of translucency on the surface.
 
{|
|-
| [[File:DefShdr_38_ColourTab_TranslucencyOff.jpg|none|200px|Translucency off.]] || [[File:DefShdr_39_ColourTab_TranslucencyRed.jpg|none|200px|Translucency using colour values sRGB 240,30,30.]] || [[File:DefShdr_40_ColourTab_TranslucencyImageMap.jpg|none|200px|Translucency using image map.]] || [[File:DefShdr_41_ColourTab_TranslucencyFunction.jpg|none|200px|Translucency function using distance shader to limit effect to localized area.]]
|-
| [[File:DefShdr_53_ColourTab_TranslucencyOffFrontLit.jpg|none|200px|Translucency off, front lit.]] || [[File:DefShdr_54_ColourTab_TranslucencyOffBackLit.jpg|none|200px|Translucency off, back lit.]] || [[File:DefShdr_55_ColourTab_Translucency0p5.jpg|none|200px|Translucency = 0.5]] || [[File:DefShdr_56_ColourTab_Translucency1.jpg|none|200px|Translucency = 1.0]]
|}
 

'''Luminosity''' 

Luminosity is the effect of a surface’s self illumination or glow. See the Surface Layer - Luminosity Tab [[Surface_Layer_-_Luminosity_Tab| page]] for a more detailed information about using the luminosity settings.
* ''' Luminosity: '''This setting provides access to the Colour Picker window in order to specify a colour or amount (greyscale) of luminosity for the surface. The adjustment slider can be used to adjust the level of luminosity.
<ul>
[[File:Wiki_DefShdr_92_ColourTab_Luminosity0-1.jpg|none|800px|Luminosity values 0 - 1, red, yellow, green, cyan, blue, magenta.]]
</ul>
* ''' Luminosity image: '''This setting allows you to assign an image map to control the amount and location of luminosity on the surface. The image map is projected onto the surface as defined on the Images tab.
* ''' Luminosity function: '''This setting allows you to assign shader or function nodes to control the amount and location of luminosity on the surface.
 
{|
|-
| [[File:DefShdr_46_ColourTab_LuminosityOff.jpg|none|200px|Luminosity off.]] || [[File:DefShdr_47_ColourTab_Luminosity1.jpg|none|200px|Luminosity = 1]] || [[File:DefShdr_48_ColourTab_Luminosity10.jpg|none|200px|Luminosity = 10]]|| [[File:DefShdr_49_ColourTab_Luminosity30.jpg|none|200px|Luminosity = 30]]
|-
| [[File:DefShdr_50_ColourTab_Luminosity10_sRGB240-30-30.jpg|none|200px|Luminosity = 10, Luminosity colour = 240,30,30 sRGB]] || [[File:DefShdr_51_ColourTab_LuminosityImage.jpg|none|200px|Luminosity controlled by image map.]] || [[File:DefShdr_51_ColourTab_LuminosityImage_FunctionPF3.jpg|none|200px|Luminosity function = Power fractal v3 shader]]
|}
 

== Roughness Tab ==
[[File:DefShdr_02-2_GUI_RoughnessTab.png|none|470px|Roughness Tab]]
Settings on this tab control the smoothness of a surface. All the settings are multiplied together and evaluated to determine the final roughness value. When the combined values evaluate to 0 a perfectly smooth surface will result and reflections will be sharp and mirror-like. Rougher surfaces are the result of values closer to 1.0 and will make reflections appear more blurry.
 

{|
|-
| [[File:specmodels_v2_Dielectric_TopLit.jpg|none|800px|Specular roughness models on dielectric (non-metal) surface with front lighting.]]
|-
| [[File:specmodels_v2_Conductive_FrontLit.jpg|none|800px|Specular roughness models on conductor (metal) surface with front lighting.]]
|-
| [[File:specmodels_v2_Conductive_TopLit.jpg|none|800px|Specular roughness models on conductor (metal) surface with top lighting.]]
|} 


'''Settings: '''
* '''Roughness: '''This value should be set to 0 for perfectly smooth surfaces and up to 1.0 for rougher surfaces.
<ul>
[[File:Wiki_DefShdr_133-2_RoughnessGreenYellowGold.jpg|none|800px|Roughness setting on dark and light coloured dielectric (non-metal) surface, and light coloured conductor (metal) surface.]]
</ul>
* '''Roughness image: '''This setting allows you to specify an image file to use for roughness.
* '''Invert (gloss map): '''When enabled, or checked, the image assigned to the “Roughness image” is inverted, i.e. black becomes white. This allows you to use gloss maps or shininess maps instead of roughness maps.
* '''Remap ^2: '''Changes the roughness curve by squaring the values in the image. This improves compatibility with many third-party PBR shaders. If "Invert (gloss map)" is enabled, the squaring occurs after the inversion.
* '''Gamma (deprecated): '''When enabled, or checked, assumes the image assigned to the “Roughness image” is in sRGB colour space (or some other space if colour management is enabled) and needs to be converted to linear colour space. This setting is deprecated, i.e. it will be removed in future versions.
* '''Roughness function: '''This setting allows you to assign shader or function nodes to determine the surface’s roughness value.
* '''Specular roughness model: '''This popup menu has three options for choosing the type of specular roughness model used on the surface.
<ul>
[[File:DefShdr_57-2_GUI_RoughnessTab_SpecRoughnessModel.png|none|327px|Specular roughness models]]
* Beckmann TG 2 is available for legacy and backwards compatibility with projects created in older vesions of Terragen. This option is not as physically correct as the others. When roughness is high it overestimates reflections of environment/indirect light (ignores self shadowing) and underestimates reflections of direct lights.

* Beckmann TG 4.5 uses the Beckmann microfacet distribution like Beckmann TG 2 but has some improvements to make it more physically correct. Reflected energy is more consistent between direct light and environment/indirect light. It also uses a fast approximation of multiple scattering when roughness is high, which reflects more light according to base colour (for metals) and Fresnel settings (for both metals and non-metals). This has the effect of increasing colour saturation in metals when roughness is high. For direct lights it uses a shadowing-masking function that produces a "rounder" falloff when roughness is high.

* GGX uses the GGX microfacet distribution and shadowing-masking function. This produces a longer tail to highlights and more closely resembles a diffuse reflection when roughness is high. This makes it more predictable when using roughness or glossiness maps. Our implementation of GGX also uses a fast approximation of multiple scattering when roughness is high, which reflects more light according to base colour (for metals) and Fresnel settings (for both metals and non-metals). This has the effect of increasing colour saturation in metals when roughness is high. GGX is the default option for new projects, but existing projects will load with their own model for backwards compatibility.
</ul>

 

== Specular Tab ==
[[File:DefShdr_03_GUI_SpecularTab.png|none|470px|Specular Tab]]
 
For documentation of Specular tab settings prior to Terragen 4.5 click [[Default_Shader_-_Specular_Tab|here]].
[[File:Drex_module_134_1_image_0.png|none|300px|Specular tab settings prior to Terragen 4.5|]]

 
''' Metalness '''

Generally speaking, a surface is either metal or it’s not. The combined (multiplied) values of the “Metalness”, “Metalness image” and “Metalness function” settings should always evaluate to 1.0 for a metal material or 0.0 for a non-metal. Note, greyscale values can be used to denote where non-metal materials, such as dirt or grime occur on the metal surface.


* '''Metalness: '''This value should be set to 1.0 for metal surfaces or 0 for non-metallic surfaces.
<ul>
{|
|-
| [[File:Wiki_DefShdr_93_SpecularTab_Metalness0-1.jpg|none|800px|Metalness values 0 - 1.]]
|}

</ul>

* '''Metalness image: '''This setting allows you to specify an image file to use for metalness. White pixel values (255,255,255) in sRGB colour space should be used for metal and black pixel values (0,0,0) for non-metal.
<ul>
{|
|-
| [[File:DefShdr_82_SpecularTab_MetalnessImageSpitBW.jpg|none|400px|Image map assigned to Metalness image setting.]] || [[File:DefShdr_83_SpecularTab_MetalnessImageFracSplitBW.jpg|none|400px|Image map assigned to Metalness image setting.]]
|}
</ul>

* '''Gamma image: ''' This setting has been removed.
* '''Metalness function: ''' This setting allows you to assign shader or function nodes to determine the surface’s metalness value. A value of 1.0 (sRGB 255,255,255) indicates a metal material and a value of 0 indicates a non-metal material.
<ul>
[[File:DefShdr_84_SpecularTab_MetalnessFunctionPF3.jpg|none|400px|Power fractal v3 shader assigned to Metalness function.]]
</ul> 

'''Fresnel'''

The Fresnel effect states that the amount of light reflected from a surface depends on the viewing angle at which it is perceived. The classic example of this is the reflections on a body of water. Looking straight down towards your feet, you can see directly through the water to any terrain beneath. This would be considered zero degrees or F0. Gazing outwards towards the horizon, perpendicular to the water surface, you see the reflected sky more intensely on the surface of the water. In the PBR shading model a reflection becomes almost 100% at an incident angle of ninety degrees.
* '''Fresnel reflectivity: '''This sets the intensity of the Fresnel effect. In Terragen 4.5 this defaults to 0.75.
<ul>
[[File:Wiki_DefShdr_134_SpecularTab_FresnelReflectivty_BlueBlackGrey.jpg|none|800px|Fresnel reflectivity on non-metal (Dielectric) surface with various Reflection values.]]
</ul>
* '''Reflectivity image: '''This setting allows you to specify an image file to use for the intensity of the Fresnel effect and where it is visible on the surface.
* '''Reflectivity function: '''This setting allows you to assign shader or function nodes to control the intensity of the Fresnel effect and where it is visible on the surface.
<ul>
{|
|-
| [[File:DefShdr_73-2_SpecularTab_ReflectivityFunctionPF3_Blue.jpg|none|400px|Power fractal v3 assigned to Reflectivity function]] || [[File:DefShdr_74-2_SpecularTab_ReflectivityFunctionPF3_Black.jpg|none|400px|Power fractal v3 assigned to Reflectivity function.]]
|}
</ul>
* '''Fresnel reflection tint: '''This setting allows you to tint the colour of the reflected light in the area defined by the Fresnel effect.
<ul>
[[File:Wiki_DefShdr_85-2_SpecularTab_FresmelReflectionTintOnWhite.jpg|none|800px|Fresnel reflection tinted. Greyscale values 0 - 1. Colour values for red, yellow, green, cyan, blue, magenta.]]
</ul>
* '''Index of refraction:''' Index of refraction (IOR) is a property of real world materials which affects light refracted into it from another medium. Despite its name it also affects the amount of light ''reflected'' off the surface for a given angle; in other words it changes the reflectivity curve which is calculated using the Fresnel equations. In the Default Shader the IOR setting must be >= 1. When IOR is exactly 1 there is no reflection. When IOR is greater than 1 some amount of reflection occurs, and the higher the IOR the more visible the reflections. For ''any'' IOR > 1, the reflectivity approaches 100% at glancing angles where light travels parallel to the surface (although this can be changed with the "Fresnel reflectivity" setting and roughness also makes it appear to be less). At any other angle the amount of reflection is reduced, calculated from the IOR. The IOR of water is usually around 1.33, depending on conditions, and most types of glass are between 1.4 and 1.9. If you don't know the IOR of your material, 1.5 works well in most cases. For photorealistic results we recommend applying the correct IOR for your material, then making major changes to reflectivity using "Roughness" and "Metalness".
<ul>
[[File:Wiki_DefShdr_94_SpecularTab_IORBlue.jpg|none|800px|Index of refraction: 1.0 - 5.0]]
</ul>
 
== Displacement Tab ==
[[File:DefShdr_04_GUI_DisplacementTab.png|none|470px|Displacement Tab]]

The settings found under this tab allow you to control the three dimensional displacement of the surface. Displacement is only applied if an image is specified in the “Displacement image” setting, or shader or function nodes assigned to the “Displacement function” setting.

'''Settings: '''
<ul>
* '''Displacement direction: '''This popup menu has 5 options which let you choose the direction the displacement is applied in. Options that indicate “(requires computed normal)” require a Compute Terrain or Compute Normal node to be connected somewhere above the Default shader node in the network to work properly. These three options are primarily used to displace terrain. For displacing 3D objects, such as an imported geometry in OBJ format, it is recommended to use the "Along normal" option.
<ul>
[[File:DefShdr_07_GUI_DisplacementDirection.png|none|438px|Displacment direction options]]

* Along vertical: Displacement happens along the normal of the underlying planet or 3D object.
* Along normal: Displacement happens along the current surface normal.
* Vertical only (requires computed normal): Displacement only happens along the normal of the underlying planet or 3D object. The displacement is scaled by the difference between the object normal and the surface normal. Displacement is reduced as the angle between the normals approaches 90°.
* Lateral only (requires computed normal): Displacement only occurs in the lateral plane, that is perpendicular to the normal of the underlying object.
* Lateral normalized (requires computed normal): This is the same as “Lateral only” but the normal is normalised, that is scaled so it has a length of 1.

{|
|-
| [[File:DefShdr_17_DisplacementTab_DiplaceDirectionOff.jpg|none|266px|Displace direction: Off]] || [[File:DefShdr_09_DisplacementTab_DisplaceDirectionAlongVertical.jpg|none|266px|Displace direction: Along vertical]] || [[File:DefShdr_10_DisplacementTab_DisplaceDirectionAlongNormal.jpg|none|266px|Displace direction: Along normal]]
|-
| [[File:DefShdr_11_DisplacementTab_DisplaceDirectionVerticalOnly.jpg|none|266px|Displace direction: Vertical only]] || [[File:DefShdr_12_DisplacementTab_DisplaceDirectionLateralOnly.jpg|none|266px|Displace direction: Lateral only]] || [[File:DefShdr_13_DisplacementTab_DisplaceDirectionLateralNormalized.jpg|none|266px|Displace direction: Lateral normalized]]
|}
</ul>
* ''' Displacement multiplier: '''This multiplies the displacement values coming from the "Displacement function" input. A value of 1 leaves the incoming values unchanged. A value of 2 would make the incoming values twice as large. A value of 0.5 would make them half as large. Negative values will invert the displacement.
<ul>
{|
|-
| [[File:DefShdr_14_DisplacementTab_DirectionMulitplier0p25.jpg|none|266px|Direction multiplier = 0.25]] || [[File:DefShdr_15_DisplacementTab_DirectionMulitplier0p5.jpg|none|266px|Displacement multiplier = 0.5]] || [[File:DefShdr_16_DisplacementTab_DirectionMulitplier1.jpg|none|266px|Displacement multiplier = 1.0]]
|}
</ul>
* ''' Displacement image: '''This setting allows you to specify an image file to use for displacement. The luminance of the image pixels is used to generate displacement.
<ul>
{|
|-
| [[File:DefShdr_18_DisplacementTab_DisplaceImageGems.png|none|266px|Displacement image = gems]] || [[File:DefShdr_19_DisplacementTab_DisplaceImageSwirls.png|none|266px|Displacement image = swirls]] || [[File:DefShdr_20_DisplacementTab_DisplaceImageTG.png|none|266px|Displacement image = Terragen]]
|}
{|
|-
| [[File:Wiki_DefShdr_121_DisplacementTab_NonDisplaceableObj.jpg|none|266px|Non-displaceable 3D object (OBJ format) without displacement.]] || [[File:Wiki_DefShdr_122_DisplacementTab_NonDisplaceableObj_Image.jpg|none|266px|Non-displaceable 3D object (OBJ format) with image assigned to Displacement image setting.]]
|-
| [[File:Wiki_DefShdr_125_DisplacementTab_DisplaceableSphere.jpg|none|266px|Displaceable 3D sphere object without displacement.]] || [[File:Wiki_DefShdr_126_DisplacementTab_DisplaceableSphereImage.jpg|none|266px|Displaceable 3D sphere object with image assigned to Displacement image setting.]]
|}
</ul>
* ''' Gamma (deprecated): '''When enabled, or checked, assumes the image assigned to the “Displacement image” is in sRGB colour space (or some other space if colour management is enabled) and needs to be converted to linear colour space. This setting is deprecated, i.e. it will be removed in future versions.
* ''' Displacement function: '''This setting allows you to assign shader or function nodes to use as displacement for the surface.
<ul>
{|
|-
| [[File:DefShdr_21_DisplacementTab_DisplaceFunctionOff.jpg|none|266px|Displacement function = off]] || [[File:DefShdr_22_DisplacementTab_DisplaceFunctionPF3.jpg|none|266px|Displacement function = Power fractal]] || [[File:DefShdr_23_DisplacementTab_DisplaceFunctionOn.jpg|none|266px|Displacement function = Power fractal, Displacement image = Terragen]]
|-
| [[File:Wiki_DefShdr_123_DisplacementTab_NonDisplaceableObj_Function.jpg|none|266px|Non-displaceable 3D object (OBJ format) with Power fractal shader assigned to Displacement function setting.]] || [[File:Wiki_DefShdr_131_DisplacementTab_NonDisplaceableObj_ImageAndFunction.jpg|none|266px|Non-displaceable 3D object (OBJ format) with image map assigned to Displacement image setting and Power fractal shader assigned to Displacement function setting.]]
|-
| [[File:Wiki_DefShdr_127_DisplacementTab_DisplaceableSphereFunction.jpg|none|266px|Displaceable 3D sphere object with Power fractal shader assigned to Displacement function setting.]] || [[File:Wiki_DefShdr_128_DisplacementTab_DisplaceableSphere_ImageAndFunction.jpg|none|266px|Displaceable 3D sphere object with image map assigned to Displacement image setting and Power fractal shader assigned to Displacement function setting.]]
|}
</ul>
* ''' Displacement offset: '''This value is added to incoming displacement values after they are multiplied by the “Displacement multiplier” setting. This creates the effect of offsetting the displacement by a set amount along the “Displacement direction”. Positive values push the displacement out so it looks almost as if it was sitting on a plinth. Negative values will sink the displacement back into the surface. It doesn't reverse the displacement, it's more like creating a hole in the surface and then applying the displacement to the bottom of the hole.
<ul>
{|
|-
| [[File:DefShdr_24_DisplacementTab_DisplaceModifier0.jpg|none|266px|Displacment modifier = 0 (default)]] || [[File:DefShdr_25_DisplacementTab_DisplaceModifier1.jpg|none|266px|Displacement modifier = 1]] || [[File:DefShdr_26_DisplacementTab_DisplaceModifierNeg1.jpg|none|266px|Displacement modifier = -1]]
|}
</ul>
</ul>
 

== Opacity Tab ==
[[File:DefShdr_05_GUI_OpacityTab.png|none|470px|Opacity Tab]]
The Opacity tab has settings which effect the opacity of the shader. It might help to think of opacity as being the opposite of transparency.

In the example images below, the 3D Preview pane's RTP mode has been enabled in order to illustrate the Opacity settings. For renders, Opacity is currently limited to either an on or off state.

'''Settings: '''

* ''' Opacity: '''This sets the overall opacity of the shader. A value of 1 means the shader is fully opaque. A value of 0 means the image is fully transparent.
<ul>
{|
|-
| [[File:Wiki_DefShdr_107_OpacityTab_Opacity0-1.jpg|none|800px|Opacity values 0 - 1]]
|} </ul>
* ''' Opacity image: '''This setting allows you to specify an image file to use for opacity. The luminance of the image pixels is used to determine the level of opacity.
<ul>
{|
|-
| [[File:Wiki_DefShdr_108_OpacityTab_OpacityImageCheckersBW.jpg|none|400px|Black and white checker pattern image assigned to Opacity image setting.]] || [[File:Wiki_DefShdr_109_OpacityTab_OpacityImageCheckersGrey.jpg|none|400px|Greyscale checker pattern image assigned to Opacity image setting.]]
|} </ul>
* ''' Use alpha channel: '''When enabled, or checked, the alpha channel from the specified image file will be used for opacity rather than the colour channels.
<ul>
{|
|-
| [[File:Wiki_DefShdr_119_OpacityTab_Opacity1.jpg|none|400px|Tree image assigned to Colour image setting.]] || [[File:Wiki_DefShdr_120_OpacityTab_Opacity1_UseAlphaOn.jpg|none|400px|Tree image assigned to Opacity image setting and Use alpha channel enabled.]]
|} </ul>
* ''' Invert opacity image: '''When enabled, or checked, the image assigned to the “Opacity image” is inverted, i.e. black becomes white.
<ul>
{|
|-
| [[File:Wiki_DefShdr_110_OpacityTab_UseAlphaChannelOn.jpg|none|400px|Use alpha channel enabled.]] || [[File:Wiki_DefShdr_111_OpacityTab_UseAlphaChannelOn_InvertOpacityOn.jpg|none|400px|Use alpha channel and Invert opacity image enabled.]]
|} </ul>
* ''' Opacity function: '''This setting allows you to assign shader or function nodes to determine a surface’s level of opacity.
<ul>
{|
|-
| [[File:Wiki_DefShdr_114_OpacityTab_OpacityFunctionPF3.jpg|none|400px|Power fractal v3 assigned to Opacity function.]] || [[File:Wiki_DefShdr_115_OpacityTab_OpacityFunctionPF3_OpacityImageCheckersBW.jpg|none|400px|Power fractal v3 assigned to Opacity function and black and white checker pattern image assigned to Opacity image.]]
|} </ul>
* ''' Alpha from colour: '''When enabled, or checked, the level of opacity is based on the colours from the “Colour image” and “Colour function” that match the “Alpha key” colour and “Key tolerance” settings. This may be useful if you don't have a dedicated opacity map or alpha channel.
* ''' Alpha key: '''This setting determines the colour used to generate the level of opacity. Colour values from the “Colour image” and “Colour function” that match this value will create an opacity value of 0. For example, if you have a leaf texture on a solid coloured background but don't have an alpha channel or opacity map, you could set the "Alpha key" to the background colour.
* ''' Key tolerance: '''This setting provides a threshold by which you can expand the colour chosen in the “Alpha key” setting to include similar shades of colour.
<ul>
{|
|-
| [[File:Wiki_DefShdr_116_OpacityTab_AlphaFromColourOn.jpg|none|800px|Alpha from colour enabled. Alpha key is black (sRGB 0,0,0). ]]
|}
</ul>
 
== Images Tab ==
[[File:DefShdr_06_GUI_ImagesTab.png|none|470px|Images Tab]]

This tab contains the global settings for any image assigned to the settings of this shader. All images use the same global settings settings, in other words if an object has uv coordinates and the “Image projection” is set to “Object UV (if available)” then all images used within this shader will be projected onto the object’s uv coordinates. If further adjustments are needed, you can apply a “Transform input” shader downstream of the Default shader node.

''' Settings: '''
* ''' Image projection: '''This popup menu has seven options pertaining to how the images are projected or applied by the shader. All of the images used by the shader are projected according to this parameter.
<ul>
[[File:DefShdr_08_GUI_ImageProjection.png|none|310px|Image projection options]]
</ul>
<ul>
* Plan Y (edges = XZ): Images are projected vertically along the Y axis in world space and images are tiled to 1 metre in scale. To adjust the scale of the image, add a “Transform input” shader node downstream of the Default shader node.
* Side X (edges = YZ): Images are projected horizontally along the X axis in world space and images are tiled to 1 metre in scale. To adjust the scale of the image, add a “Transform input” shader node downstream of the Default shader node.
* Side Z (edges = XY): Images are projected horizontally along the Z axis. in world space and images are tiled to 1 metre in scale. To adjust the scale of the image, add a “Transform input” shader node downstream of the Default shader node.
* Through camera: Images are projected through the camera specified in the “Projection camera” setting.
* Object UV (if available): Images are mapped using the 3D object’s UV coordinates, if they're available.
* Cylindrical: Images are projected from a virtual cylinder around the object towards the central axis of the cylinder.
* Spherical:
</ul>
* ''' Projection camera: '''The camera assigned to this setting is used for the “Through camera” image projection. If no camera is specified the camera rendering the scene is used.
The Unpremultiply checkboxes below correspond to the image settings. For example, the Unpremultiply colour checkbox applies to the “Colour image” setting on the Colour tab. When enabled, or checked, the image is unpremultiplied. Some images use premultiplied alpha channels and may give incorrect results if they're not unpremultiplied. If an image doesn't have an alpha channel you don't need to enable these checkboxes
* ''' Unpremultiply colour: ''' When enabled, or checked, the image assigned to the "Colour image" setting on the Colour tab is unpremultiplied.
* ''' Unpremultiply metalness: ''' When enabled, or checked, the image assigned to the "Metalness image" setting on the Specular tab is unpremultiplied.
* ''' Unpremultiply translucency: ''' When enabled, or checked, the image assigned to the "Translucency image" setting on the Colour tab is unpremultiplied.
* ''' Unpremultiply luminosity: ''' When enabled, or checked, the image assigned to the "Luminosity image" setting on the Colour tab is unpremultiplied.
* ''' Unpremultiply reflectivity: ''' When enabled, or checked, the image assigned to the "Reflectivity image" setting on the Specular tab is unpremultiplied.
* ''' Unpremultiply roughness: ''' When enabled, or checked, the image assigned to the "Roughness image" setting on the Roughness tab is unpremultiplied.
<ul>
{|
|-
| [[File:Wiki_DefShdr_117_ImageTab_UnpremultiplyColourOff.jpg|none|400px|Black fringe around tree leafs because texture image mapped to Colour image setting has not been premultiplied.]] || [[File:Wiki_DefShdr_118-2_ImageTab_UnpremultiplyColourOn.jpg|none|400px|Black fringe around tree leafs removed by enabling Premultiply colour.]]
|}</ul>