# Terraform Render Users Guide

Author: Raymond Ostertag,

This is the user's guide for terraform's render tool. Terraform use POV-Ray as renderer.

## Table of Contents

- Settings
- Render Options
  - Output
  - Size
  - Quality
- Scene Options
  - Camera
  - Scaling
  - Atmosphere
  - Sky
  - Sea
  - POV-Ray
- More Scene Options
  - More Sky
  - More Sea/Water
  - More POV-Ray
- Some useful links

## Settings

Terraform use POV-Ray as renderer. It's important that a recent version of POV-Ray is installed on your machine. You can download the last version at http://www.povray.org/ or in the Main window from the File menu choose the Options dialog and the POV-Ray tab and click on Download POV-Ray. Once POV-Ray is installed in an executable directory write here the name of your executable (we suggest you the generic name povray).

## Render Options

The Render Options Dialog can be open from the Terrain Window and the Edit Menu.
Here you find the important settings for the renderer.
Output options : The rendering image can be only display at screen, in this case there is no output fle. If you prefer have a copy of your image check the Output to file box, choose the format and the name of the file. The Bits per colour value is also called depth of the RGB channel, with the PNG you can specify different values, for exemple 16 bits per channel (Gimp 1.2 and 1.4 series can only read 8 bits per channel).
Size options : Here you set the size in pixels of the output file. If you use a custom size don't forget that the default camera of Terraform is in a 4/3 ratio, the output file should also be in 4/3 ratio to avoid deformations. The Partial render can save you lot of time when you are doing some test and you just need to see a part of the image.
Quality options : Quality options are important things for the time and the result of the rendering. If you don't know POV-Ray you have to know that with a low quality the rendering is very fast but the image is not complete. Quality 9 without antialiasing is a good choice for test renderings. The antialiasing is normally only used for the final rendering but be careful that some details may disappear (stars for example) and some textures may be smoothing and present a different aspect as without antialiasing. You can read the POV-Ray doc (it's given with the program or you can find an online and downloadable HTML version) for more informations.

## Scene Options

The Scene Options Dialog can be open from the Terrain Window and the Edit Menu.
Here you find the important settings for the scene (camera, textures, lights).
Camera : The camera location is strictly the same used in POV-Ray scripting language. It's defined by the coordinates of two points Camera_location and Camera_look-at. Considering we are working on a 2D map the coordinate system is so :

- X : left to right, 0 is the left border and 1 is the right border of the terrain
- Y : elevation, 0 is the bottom and 1 is the summit of the terrain
- Z : up to down, 0 is the down border and 1 is the up border of the terrain

In 3D by convention X is the lateral, Y the vertical and Z the forward/backward displacement.
You can set the camera values manually or you can clic with the mouse in the 2D map. Left click is for the Camera_location point and Right clic is for the Camera_look-at point. The Elevation offset value is added to the Y coordinate to be sure that the camera is not under the terrain. If you set the values manually it can happen that the camera goes down the terrain, in this case you'll see a black or very strange image because Terraform is not a tool for submarine or underground images ;-)
Scaling : Nothing special here, this is for the X,Y,Z scales. Be careful that scales are not only for the terrain but also for the camera. You should considerer to choose the scale before doing a fine setting of the camera.
Atmosphere : The Atmosphere tab is used for fog, haze and some other effects. The normal Atmosphere type is Earth Fog. With this type of atmosphere you can have a basic Fog, use the Fog Density and Fog Turbulence slides to perform different effects of fog. It's also possible to have a ground Fog, the Fog Offset slide increase or decrease the height of this fog and the Fog Alt rules how fast the fog disappear vertically in the atmosphere (0 it's like a wall). Other Atmosphere type is Earth Haze. It's purpose is to have some nice effect when the camera look at the sun or the moon. Without some direct light pointing to the camera you won't see interresants things. Fog Density and Fog Turbulence can be used to perform different effects. If you check the Rainbow box you'll see an additionnal rainbow feet in the background.
Sky : The Sky tab is used for lights, clouds, stars, celest objects and sky. It's a bit complex and the first thing to understand is what kind of Sky Types can be used and what their purpose are. In the Sky Type menu you'll found the following types :
Earth Regular Sky : the complet model including night and day lights, moon and sun. The clouds and the stars can be selected from the menus belows the Sky Type menu. In order to change the hours and the location of the sun and the moon you have to go to the POV-Ray tab and play with the Time of Day and North Direction values.
Earth Static Sky : a very simple model where it's always noon. The ligths are fixed like a studio enligthment. The clouds can be selected from the menu below the Sky Type menu. Stars are not visible.
Earth Dynamic Sky : a simple model where the lights can be changed. The clouds can be selected from the menu below the Sky Type menu. Stars are not visible. In order to change the lights you have to go to the POV-Ray tab and play with the Time of Day and North Direction values. If you choose a Time of Day between 0-6 and 18-24 hours the power of the light is divided by two simulating a moon enlightment. Mapped Sky : as background you see a plane where a image is projected. The lights can not be changed, Clouds and Stars are not visible. To select the projected image jump to the chapter More Scene options
Sea : The Sea tab is used for the sea but not for the rivers. In the Water Type menu you can select some themes for the sea. The values of the sea level and the sea clarity can be changed here. Uncheck the Filled Sea box can be useful in some kind of terrain but it should not often be used.
POV-Ray : The POV-Ray tab is used for different purpose. With the Terrain Theme menu you select how the terrain are textured. The Auto-render is only unchecked if don't want a rendering image each time you clic on the Apply button. The Time of Day and North Direction values are only useful if you have selected a Earth Regular or Earth Dynamic Sky from the Sky tab. To locate the sun, first look at the horizon with the camera, then choose a very early 6.5 hours Time of Day and turn the North Direction 30° by 30° until the sun appears in the camera field. For exemple, if you look at the Z- direction the North direction to see the sun is 270°. Now to see the moon only add 12 hours (6.5+12=18.5) at the Time of Day value.

## More Scene Options

The options that can be changed through the dialog box are the very useful one. But each image need its fine tuning and some additonnals parameters can be found and changed in a text file. The name of this file is defaults.inc and it can be found in the /usr/local/share/terraform/include or /usr/share/terraform/include directory. Make a secure copy of this file and then edit it with your favorite text editor. The file is divided in sections according to the tab of the Scene Options dialog : Global, Camera, Atmosphere, Sky, Water, POV-Ray. Each parameter has a short description : Level 1 or 2 (important or not), name of the parameter in the dialog box, type and commentar. Each value can be changed after the #declare statments. The Global, Camera, Scale and Atmosphere Sections have no additonnal parameters that can not be found in the dialog box, so we begin the description from the Sky section.
Sky section : additonnal parameters
TF_SKY_COLORDESCRIPTION : name of the file used to describe the sky coloration located in the include/skies/include directory. Read the theme document if you would create your own sky color files.
TF_SKY_COLORATION : you can add a permanent coloration to the blue sky. To achieve this change the RGB color vector ( amount of Red, amount of Green, amount of Blue ). For exemple to obtain a reddish sky : #declare TF_SKY_COLORATION = <1.0, 0.0, 0.0>;.
TF_STARS_BRIGHTNESS : here you can increase or decrease the brightness of the stars. Although you put a very high brightness the stars will never be visible at day light between 7 and 15 hours (they are transparent).
TF_LIGHTS_DESCRIPTION : in the Earth Regular Sky Sky Type there is a simulation for the global or ambient illumination, you can change the name of the file used for this from there.
TF_HAVE_AMBIENT_LIGHT : here you can suppress the ambient illumination.
TF_AMBIENT_LIGHT_LUMINOSITY : it's a very important option. Here you change the power of the lights. This can radically change the aspect of the scene.
TF_HAVE_CAMERA_LIGHT : here you can add a light over the camera if you used the Earth Regular Sky Sky Type
TF_CAMERA_LIGHT_LUMINOSITY : the power of the previous camera light.
TF_HAVE_CLOUDS_ROOF : create a clouds as object instead as texture. Experimental, no good results yet.
TF_SUN_APPARENT_SIZE : here you can increase or decrease the size of the sun.
TF_SUN_LIGHT_COLOR : here you can change the color of the light of the sun, not the color of the sun itself.
TF_MOON_IMAGE : a real map of the moon is applied to the moon object. The map is in the image_maps directory. The format is PNG. Here you can change the name of the image applied to the moon object. The width of the image must be the double of the height to avoid deformations.
TF_MOON_TIME_OFFSET : the default offset value between sun and moon is 12 hours. You can change this here, for exemple if you wish a moon visible at day light
TF_MOON_LIGHT_COLOR : here you can change the color of the light of the moon, not the color of the moon itself.
TF_MOON_APPARENT_SIZE : here you can increase or decrease the size of the moon.
TF_MOON_[YZ]_ROT : there is an algorithm that compute and adjust which point of the moon you are looking with the camera. By default this point is always the center of the map applied to the moon object. You can change this here. Y rotation means moving the point along the width and Z rotation along the height of the map. It's similar at longitude and latitude coordinates.
TF_SKY_IMAGE : the image mapped on the background plane for the Mapped Sky Sky Type. The format is TGA. The image is located in the image_maps directory. The width is 16/9 of the height to avoid deformations.
TF_SKY_IMAGE_SCALE : here you can change the scale of the previous image. It's important if the image don't fill all the background.
TF_SKY_IMAGE_ELEVATION_OFFSET : this option help you to adjust the image with the line of the horizon.
Water section : additonnal parameters
TF_WATER_COLOR : here you can change the basic color of the water
TF_WATER_BOTTOMCOLOR : with some Water Type you see the part of the terrain who is under the water. This option changed the color of the very deep underwater terrain.
TF_WATER_REFLECTION : very important option. Here you can change the reflection factor of the water.
TF_WATER_FREQUENCY : here you can change the frenquency ot the waves.
TF_WATER_HEIGTH : the heigth of the waves, don't make a confusion with the water level.
TF_WATER_SMOOTHWAVE : an additonnal optionnal wave that smooth the aspect of the water
POV-Ray section : additonnal parameters
TF_LANDSCAPE_TURBULENCE : here you can change the global turbulence of the texture applied to the terrain.
TF_LANDSCAPE_DISTRIBUTION : here you can change the distribution of each component (grass,snow,rock,..) of the texture applied to the terrain. Increase this and each component will cover a smaller part of the terrain.

## Some useful links

POV-Ray official site
POV-Ray documentation, Table of contents