# FAQ: Writing Your Own Templates

Terraform FAQ, version 0.1 Jun. 09, 2000 by David A. Bartold modeled after the Hacking Terraform FAQ

Terraform FAQ, version 0.1.1 Mar. 10, 2001 by David A. Bartold updated for Terraform 0.8.0+

- 0. Foreword
- 1. How Terraform renders a POV-Ray scene
  - 1.1 Parameters
  - 1.2 Which parameters are defined where
- 2. POV-Ray data files
  - 2.1 Your kit of parts
- 3. How the world is set up
  - 3.1 Where is the land and water
  - 3.2 Where is the texture on the land
- 4. Creating your own template
- 5. Conclusion

# 0: Foreword

Terraform allows you to design landscape shapes however you want using height field operations. If you want to change the land's color, or its texture, and there isn't a template file available to your liking, you can write your own. Terraform comes with a few templates describing the texture of the land and its surrounding celestial bodies. These templates are in the form of *.pov files typically located in the /usr/shared/terraform directory. The template files can be sampled by right clicking on a Height Field and then clicking HF > Render Options > PovRay > POV template file. The ones included at the time of this writing are: bare_rock, earth_basic, earth_canyon, and earth_green. This document covers how to design your own template file and assumes you already understand povray scene file syntax, have looked at a povray file exported by Terraform. Also, it'd be a good idea to look over defaults.inc as a reference describing all the parameters.

# 1: How Terraform renders a POV-Ray scene

Terraform renders a POV-Ray scene by first creating a temporary *.pov file in your /tmp directory. Then it writes a temporary heightfield to that directory. It calls the "povray" executable, passing the temporary *.pov file and an include path that typically points to /usr/share/terraform. The temporary *.pov file contains #declared parameters followed by a #include of the template file.

# 1.1: Parameters

There are quite a few parameters Terraform passes to the template file. The most important of them include: TF_HEIGHT_FIELD, TF_WATER_LEVEL, TF_X_SCALE, TF_Y_SCALE, TF_Z_SCALE, TF_CAMERA_LOCATION, and TF_CAMERA_LOOK_AT. The first one is a height field object declaration, the last two are vectors used for setting up the camera, and the rest of the parameters in the above list are floats. Many other parameters are available to the template file, some of which are booleans. You need not implement every parameter.

# 1.2: Which parameters are defined where

There's only one parameter that Terraform does not explicitly define in the temporary povray file it exports: TF_LANDSCAPE_TEXTURE. That parameter will be defined by the template file as we soon will see. For more information on individual parameters, see the defaults.inc file for more documentation.

# 2: POV-Ray data files

These are the files used by the template system to define a scene:

- *.pov-- These are the top-level template files themselves. They may make use of the *.inc files as described below.
- defaults.inc-- #declares any parameter that hasn't yet been defined.
- *_landscape.inc-- defines TF_LANDSCAPE_TEXTURE for a particular environment.
- earth_sky.inc, earth_water.inc-- creates objects for an earth sky and seas, respectively. Note that these include files actually create objects, unlike your typical *.inc file, therefore all available parameters should be previously defined before #including one of these files.
- generic_land.inc-- declares an object for the land as well as defines a camera. The camera is positioned relative to the land, that is why it's in the same file. Again, it actually creates objects, not just #declares, so make sure all parameters are defined before #including it.

# 2.1: Your kit of parts

The files mentioned in section 2 are there for you to use. Feel free to #include them in your template file. You are also encouraged to create new parts. Create a nice martian landscape texture you wish to share? Put it in a file named mars_rocky_landscape.inc and post it on Terraform's email list. Try to be consistant with the naming scheme. Most of the files are named along the lines of plant_shortdescription*.*. If you do contribute parts, it'd be nice to send at least one template *.pov file that makes use of them, too. Once there are a multitude of parts, it will be possible to mix and match pieces as needed. Imagine being able to render a martian landscape with an earth sky as well as an extra moon with a ring around it. Cool..

# 3: How the world is set up

The sky spheres, sun, and moon are centered around the origin <0, 0, 0>. Generally, the distance from the origin to, say, a sun, should always be proportional to vlength (<TF_X_SCALE, TF_Y_SCALE, TF_Z_SCALE>). You can always break the rules if a heavenly body has, say, an elliptical path, but always try and make the ellipse proportional to the aforemensioned value. Otherwise, changing the scale in Terraform may cause scaling problems.

# 3.1: Where is the land and water

The land is centered on the XZ plane from <-TF_X_SCALE / 2.0, 0.0, -TF_Z_SCALE / 2.0> to <TF_X_SCALE / 2.0, TF_Y_SCALE, TF_Z_SCALE / 2.0>. In relation to the actual Targa height field, the lower left-hand corner of the *.tga file corresponds to <-TF_X_SCALE / 2.0, y, -TF_Z_SCALE / 2.0>. The sea floor maps to y=0, sealevel maps to y=(TF_Y_SCALE * TF_WATER_LEVEL), and the highest peak maps to y=TF_Y_SCALE.

# 3.2: Where is the texture on the land

If you use a texture_map for the land (i.e. do a #declare TF_LANDSCAPE_TEXTURE = texture { texture_map { ... } }), 0.0 maps to the bottom of the sea, TF_WATER_LEVEL maps to sealevel, and 1.0 maps to the highest peak. See earth_green_landscape.inc on how to stretch the landscape texture to keep the sealevel at the right position. It also employs a trick to reduce the likelihood of texture wraparound by mapping the texture_map from 0.0 to 0.1 and then scaling by 10.0 afterwards. It'd be nice if povray had a pattern that didn't apply some sort of repetition/reflection function but it doesn't.

# 4: Creating your own template

First create a *.pov file and copy these lines into it:

    // Include Povray standard include files.
    #include "colors.inc"
    #include "skies.inc"

    // Set any unassigned parameters to their default values.
    #include "defaults.inc"

    // Override default texture.
    #declare TF_LANDSCAPE_TEXTURE = texture
    {
      pigment { color rgb <0.8, 0.4, 0.1> }
    }

    // Add an earth sky, sun, moon, and stars.
    #include "earth_sky.inc"

    // Create water.
    #include "earth_water.inc"

    // Create the land and camera.
    #include "generic_land.inc"

Note that you should declare TF_LANDSCAPE_TEXTURE after #including defaults.inc. That's because your texture may rely on the TF_WATER_LEVEL parameter. Next, copy this *.pov file into your /usr/share/terraform/themes directory. Generate a height field and then render it using this template file. You can select your theme from the Edit > Options > POV-Ray > Terrain theme combo box. You can modify the texture to suit your tastes. Play around with it for a bit. If you are feeling comfortable creating your own landscape textures, try something more difficult, such as designing a martian sky. Try using the files that come with Terraform as a starting point for making your own.

# 5: Conclusion

It's not hard to create basic land textures. Once you get the hang of the parts already available and understand how to use them, you can modify them to create your own terrain patterns and even your own worlds. But most of all, be creative and have fun.