This is the user's guide for terraform's themes and objects. Terraform use POV-Ray as descripting language for writing them.
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
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.
A cloud theme is a texture declaration. The form is :
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.
A skycolor theme is a set of sixteen colors declaration. The form is for each color :
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.
A star theme is a pigment declaration. The pigment is a sub-level of a texture declaration. The form is :
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.
A earth theme is a texture declaration. The form is :
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).
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.
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.
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.
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 :
In the water directory there is themes files for the water beginning with the prefix earth_.
Typically the theme has this form :
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 :
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 :
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.
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 :
Single objects can be everywhere, on earth, water or in the air. A few parameters are needed
to control the location of the object :
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 :
POV-Ray documentation, Table of contents
User themes
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
#declare TF_clouds = texture { TEXTURE_DECLARATION }
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
#declare *_color = < Red value, Green value, Blue value > * TF_SKY_COLORATION ;
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
#declare stars_pigment = pigment { PIGMENT_DECLARATION }
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
#declare TF_clouds = texture { TEXTURE_DECLARATION }
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
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
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
Fog
#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
#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
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
#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
Multiple Objects
#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
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
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 :
Some useful links
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