# Terraform Themes Users Guide

Author: Raymond Ostertag,

This is the user's guide for terraform's themes and objects. Terraform use POV-Ray as descripting language for writing them.

## Table of Contents

- Introduction
- User themes
  - Clouds
  - Skycolor
  - Stars
  - Earth texture
  - Moon Image
  - Background Image
- Complex themes
  - Fog
  - Water
  - Sky Type
  - Lights
- Objects
  - Multiple Objects
  - Single Objects
- Advanced scripting
- Some useful links

## Introductions

Terraform use POV-Ray as descripting language for writing the themes or objects. The basis of this language is very simple to understand, the dificulty is to learn all the features that POV-Ray provide and the fine settings of the paramaters. Some themes use only the Textures features and it's possible for a beginner to write them. This document is separated in four sections : user themes easy to write and images, more complex themes, objects and finally advanced scripting.

In Terraform almost everything is themable. The first thing to do is to understand the organisation of the POV-Ray files. The files coming with your installation are in /usr/share/terraform/ or /usr/local/share/terraform/. You can read them but please dont modify them are you can get quickly in trouble. The best way is to create the new theme in your home directory. There is a .terraform directory in your home directory, go and put your personal POV-Ray files there. There is 3 sub-directories : image_maps is for the images not for the themes, include is the rigth directory and objects is only for objects not for themes. Well change to the include directory. Here you can put a copy of the parameters file defaults.inc and change the parameters from there. The most important thing it's that now we are seeing the directories used for the themes : atmospheres, earth_textures, skies and water

## User themes

In the directory include/skies/include you find themes for clouds, skycolor and stars. Those themes are all used in the Earth Regular Sky Sky Type. Some other Sky Type might use them but it's not always true.
In the directory earth_textures you find themes for the terrain. For further information on how to describe a texture or pigment declaration read the dedicated chapter in the POV-Ray manual.

### Clouds

A cloud theme is a texture declaration. The form is :

    #declare TF_clouds = texture { TEXTURE_DECLARATION }

It's important to keep the name TF_clouds. The other important thing is to keep a part of the texture transparent, the filter values of the colors can not be always 0. This texture is applied on a sphere and behind this sphere there is objects (moon, sun) other textured spheres (stars, sky) and you won't see them if there is no transparency in your clouds texture. The worse thing wiil to have the ligths behind a no transparent sphere : your image will be black.
How the internal texture declaration is made depend of what you want. There is some sample scripts given with POV-Ray. You can use the material editor of Truevision there is some clouds given with this program (just remove the material declaration level).
This theme is automatically scanned and available in the dialog boxes. For a succesful scan keep the prefix clouds_ for the name of the file.

### Skycolor

A skycolor theme is a set of sixteen colors declaration. The form is for each color :

    #declare *_color   = < Red value, Green value, Blue value > * TF_SKY_COLORATION ;

Make a copy of the sample file skycolor_earth.inc and rename it for exemple skycolor_mars.inc. All you need to do is to edit the color and change them following your wishes. The colors are blend to produce the sky. There is three sections : colors at noon, at night and day transition, at night. TF_SKY_COLORATION is a global parameter that change the coloration of all the skies. It can be changed from the file defaults.inc.
This theme can not be changed from the dialog boxes, you have to edit the file defaults.inc and change the TF_SKY_COLORDESCRIPTION option.

### Stars

A star theme is a pigment declaration. The pigment is a sub-level of a texture declaration. The form is :

    #declare stars_pigment = pigment { PIGMENT_DECLARATION }

It's important to keep the name stars_pigment. The other important thing is to add the stars_transmit in the transmit value of the colors where there is stars and 1 where there is no stars. This texture is applied on a sphere and behind this sphere there is the sky. If you forget zone to give the transmit value 1 where there is no stars the sky will be affected. The value stars_transmit is different at nigth or day time, at night you see the stars, at day there are not visible, between day and nigth there is a blend factor.
How the internal pigment declaration is made depend of what you want. There is some sample scripts given with POV-Ray. You can use the material editor of Truevision there is some clouds given with this program (just remove the material and texture declaration level).
This theme is automatically scanned and available in the dialog boxes. For a succesful scan keep the prefix stars_ for the name of the file.

### Earth texture

A earth theme is a texture declaration. The form is :

    #declare TF_clouds = texture { TEXTURE_DECLARATION }

In older version of Terraform it was the only thing who was themable. If you made some, there are always avalaible. It's important to keep the name TF_LANDSCAPE_TEXTURE. This texture is applied on a the Height-field. You can declare a simple texture or declare a more complex texture_map using a gradient Y. In the last case you can then use the TF_WATER_LEVEL parameter to create a texture depending on the level of the water. Some other parameters like TF_LANDSCAPE_TURBULENCE and TF_LANDSCAPE_DISTRIBUTION can also be added somewhere in your texture. There is some scripts (simple or complex) given with Terraform, you could start from one of this or use the material editor of Truevision (just remove the material level).
This theme is automatically scanned and available in the dialog boxes. For a succesful scan just put it in a earth_texture directory.

### 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. The width of the image must be the double of the height to avoid deformations. You can find several nice maps on the web (Resources page), almost all with the good size but in JPEG format, just change the format with Gimp or ImageMagick. Put the new map in the image_maps directory. This map can not be changed from the dialog boxes, you have to edit the file defaults.inc and change the TF_MOON_IMAGE option.
Some control parameters TF_MOON_Y_ROT and TF_MOON_Z_ROT from the defaults.inc file can be used to control with point of the map you see with the camera. TF_MOON_Y_ROT = 0 and TF_MOON_Z_ROT = 0 show the what-you-see side of the moon TF_MOON_Y_ROT = 180 and TF_MOON_Z_ROT = 0 show the dark side of the moon. If you render a map of the earth instead of the moon and want see a specific point of the earth you should know is geographical positions and then change the rotations like the following TF_MOON_Y_ROT = latitude coord as E20=20 W20=-20 TF_MOON_Z_ROT = longitude coord as N0=90 S0=-90.

### Background Image

The image mapped on the background plane for the Mapped Sky Sky Type can be changed. The map is in the image_maps directory. The format is TGA. The width is 16/9 of the height to avoid deformations, some valid sizes are 1600x900, 800x450, 400x225. There is some exemples on the web. If you made a nice picture of a sunset and you'd like as background in Terraform then crop it at a valid size and save it as TGA format. Put the TGA file in the image_maps directory. The background image can not be changed from the dialog boxes, you have to edit the file defaults.inc and change the TF_SKY_IMAGE option.
Some control parameters TF_SKY_IMAGE_SCALE and TF_SKY_IMAGE_ELEVATION_OFFSET from the defaults.inc file can be used to control the good positionning of the background image.

## Complex themes

There is still other themable parts in Terraform : Fog in atmospheres, Water in water, Lights in skies/include and Sky Type in skies. For further informations on the scripting language read the POV-Ray manual.

### Fog

In the atmospheres directory there is main files beginning with the prefix earth_ and other file to include in your fog theme. Typically the theme has this form :

    #if (TF_HAVE_FOG)
      FOG_DECLARATION
    #end // TF_HAVE_FOG
    #if (TF_HAVE_GROUND_FOG)
      #include "fog_ground.inc"
    #end // TF_HAVE_GROUND_FOG
    #if (TF_HAVE_RAINBOW)
      #include "rainbow.inc"
    #end // TF_HAVE_RAINBOW

First you write your fog description then you include the ground fog and the rainbow files. Of course if you'd like change the rainbow you should create a rainbow2.inc file and include it in a new earth_fog2.inc main file.
The parameters in the Atmosphere section of the defaults.inc file can be used as your convenience.
This theme is automatically scanned and available in the dialog boxes. For a succesful scan keep the prefix earth_ for the name of the file.

### Water

In the water directory there is themes files for the water beginning with the prefix earth_. Typically the theme has this form :

    #if (TF_HAVE_WATER)
      WATER_DECLARATION
    #end // TF_HAVE_WATER

The water is an infinite plane with a texture applied on it. You must translate this plane at a Y level corresponding at the value : TF_WATER_LEVEL * TF_Y_SCALE. If you prefer some other object to simulate the water, for exemple a giant box, keep in mind that the bounding of Height-field begin at the coordinate < 0,0,0 > and finish at < 1 * TF_X_SCALE, 1 * TF_Y_SCALE, 1 * TF_Z_SCALE >. TF_WATER_LEVEL is a value between 0 and 1, that's logical. Until your plane or object is at the right place then texture it.
The parameters in the Water section of the defaults.inc file can be used as your convenience.
This theme is automatically scanned and available in the dialog boxes. For a succesful scan keep the prefix earth_ for the name of the file.

### Sky Type

In the skies directory there is files for the global sky description beginning with the prefix earth_. Some files are very complex like the Earth Regular theme some others are much simple. The purpose of those files is to describe or arrange :

- the background sky ans stars
- the lights
- the celest object
- the clouds

The functionnality of the Terraform Sky Types are explained in the render doc file. You should not start from nothing but only make a copy and modify one of existing file to add or change what you need. Keep in mind that the bounding of Height-field begin at the coordinate < 0,0,0 > and finish at < 1 * TF_X_SCALE, 1 * TF_Y_SCALE, 1 * TF_Z_SCALE >.
The parameters in the Sky section of the defaults.inc file can be used as your convenience.
This theme is automatically scanned and available in the dialog boxes. For a succesful scan just put it in the skies directory.

### Lights

In the skies/include directory there is files for the lights description beginning with the prefix lights_. Lights files are not always themes. lights_studio is used in the Earth Static Sky Type, this is a fixed three lights system as used in Hollywood. lights_toymodel is used in the Earth_Dynamic Sky Type, this is a set of lights that simulate the sun or moon enlightment with an optionnal ambient enlightment. Ligths_standard is a theme for the main Earth Regular Sky Type. Typically the theme has this form :

    #if (TF_HAVE_AMBIENT_LIGHT)
      AMBIENT_LIGHT_DECLARATION
    #end // TF_HAVE_AMBIENT_LIGHT
    #if (TF_HAVE_CAMERA_LIGHT)
      CAMERA_LIGHT_DECLARATION
    #end // TF_HAVE_CAMERA_LIGHT

Keep in mind that the bounding of Height-field begin at the coordinate < 0,0,0 > and finish at < 1 * TF_X_SCALE, 1 * TF_Y_SCALE, 1 * TF_Z_SCALE >. If you add some custom light point don't forget to scale the coordinate with the TF_XYZ_SCALE parameters. The location camera can be obtain with the TF_CAMERA_LOCATION parameter.
Some parameters related to the Lights in the Sky section of the defaults.inc file can be used as your convenience.
This theme can not be changed from the dialog boxes, you have to edit the file defaults.inc and change the TF_LIGHTS_DESCRIPTION option.

## Objects

Objects can be multiple or single. Multiple objects are the standard of Terraform, they are listed in the Place objects dialog box. There is many parameters to let you choose how to spread them on the heigth-field. Single objects are called TRACE objects because a POV-Ray trace function is used to put them at the right place. They are not accessible through a menu or dialog box.

### Multiple Objects

You can add objects in the objects directory. Every kind of object is acceptable at the condition that it can be read from the POV-Ray code. For exemple you can describe an object with the CSG features of POV-Ray or create an object with the 3D modeler Moonlight and export it in POV mesh format. The declaration of the object should finally have this form :

    #declare POV_OBJECT_ NAME = { any kind of POV object declaration }
    #macro OBJECT_NAME ()
       object {  POV_OBJECT_NAME  }
    #end

The name of the file should be OBJECT_NAME.inc (the same name as for the macro declaration).
Those objects are automatically scanned and available in the Object dialog box from the Operations menu. For a succesful scan just put the file OBJECT_NAME.inc in the object directory.
Often the declaration of the object is separate in two files OBJECT_NAME_INC.txt and OBJECT_NAME.inc. The file OBJECT_NAME_INC.txt contain the object itself and can be then reused as Single object.

### Single Objects

Single objects can be everywhere, on earth, water or in the air. A few parameters are needed to control the location of the object :

- LOCAL_EYE_POINT : initial location of the object, absolute coordinates system similar as in the camera dialog
- LOCAL_CAMERA_RELATIV : you can change the coordinates system that they are relativ to camera location
- LOCAL_CONSERVE_ELEVATION : if false the object fall down on the earth or water
- LOCAL_OBJECT_FLOAT : if false the object can be on earth but under the water
- LOCAL_OBJECT_SCALE : scale the object

The single objects are listed in at the end of the defaults.inc file. You have to edit them. The declaration files for the object itself are located in the include directory and prefixed with the word TRACE.

## Advanced scripting

Advanced POV-Ray scripters can add their own scripts in Terraform. Terraform built dynamically the render process with the themes files and some static files as below :

- defaults.inc , the parameter file is the first read
- themes files like sky, fog, water, earth texture, objects : the dynamic part
- generic_land.inc, the final declaration file.

The best solution is to put in the last declaration file generic_land.inc an instruction

    #include "mycustom.inc"

Terraform declare a lot of Library path, simply use the include directory to store your custom files, they'll be read. Of course you can download and integrate all the POV resources of the web. The Trace instruction is useful to put individual objects at a specific place on the heigth-field. Just keep in mind the basic parameters :

- TF_CAMERA_LOCATION, TF_CAMERA_LOOK_AT : coordinate of the camera with scaling
- < 0,0,0 > <1,1,1> : bounding of the heigth-field without scaling
- TF_X_SCALE, TF_Y_SCALE, TF_Z_SCALE : scales applied to the heigth-field,
- TF_SCALE = < TF_X_SCALE, TF_Y_SCALE, TF_Z_SCALE > : global scale factor, sometimes useful
- TF_WATER_LEVEL : level of the sea without scaling

## Some useful links

POV-Ray documentation, Table of contents
POV-Ray documentation, Chapter Simple Texture Options
POV-Ray documentation, Advanced Texture Options
Resources for Background Images
Resources for Moon images
Resources for POV scripts