# Terraform Users Guide

Author: Robert Gasch, Updated by David A. Bartold Updated by Koos Jan Niesink

This is the user's guide for terraform, an interactive digital terrain generator/modeller.

## Table of Contents

- FAQ (Frequently Asked Questions)
- Tutorial
- The Main Window
  - Generating a New Heightfield
    - Perlin Noise
    - Spectral
    - Subdivision
    - Random
  - Merging Two or More Terrains
  - The Global Options Dialog
- The Terrain Window
  - Views
  - Rendering
    - The Render Options Dialog
    - Rendering in POV-Ray
  - Basic Height Field Transforms
    - Invert
    - Mirror
    - Move
    - Rotate
    - Scale
  - Specialized Height Field Transforms
    - Connect
    - Craters
    - Erode
    - Fill
    - Flowmap
    - Fold
    - Gaussian Hill
    - Radial Scale
    - Rasterize
    - Roughen
    - Smooth
    - Terrace
    - Tile
    - Transform
  - Objects
    - Show
    - Place
    - Remove All
    - Move
  - Advanced Topics
    - Adding your own scene files and objects
    - Hacking Terraform
    - Writing POV-Ray Templates

## FAQ (Frequently Asked Questions)

Answers to many common questions are available here.

## Tutorial

A quick tutorial is available here for first time users.

## Main Window

The main window allows the user to open new terrain windows. A terrain can be loaded or created using one of several algorithms. The Options window accessable from the main window menu exposes several global parameters such as the POV-Ray executable location and maximum undo size.

### Generating a New Heightfield

The easiest way to generate a new terrain is to select the "Random" menu item. It will automatically select one of several different algorithms using randomly generated parameters and create a new heightfield for you.

#### Perlin Noise

The Perlin layered noise function is calculated by taking the sum of several octaves of noise. To produce a two dimensional octave of noise, a grid of random numbers are interpolated. The distance between the points is determined by the frequency.

#### Spectral Synthesis

Spectral synthesis involves filling an array with random data. The array is fed to an inverse fourier function to generate terrain.

#### Subdivision

The subdivision algorithms initially set several outer points to random values and those points are used to calculate an interior point. For example, the recursive square algorithm sets the four corners of the terrain to random values. The center point's value is calculated by averaging the value of the four corners and adding a random number. The random number is multiplied by the size of the square so that larger distances have greater variation. Finally the algorithm divides the square into quarters and recurses on each.

#### Random

Generates a new terrain using a randomly chosen algorithm. The terrain size will be 400 x 400 pixels.

### Merging Two or More Terrains

Multiplies two terrains by different coefficients and combines them using an operator such as addition. Merged terrains are automatically normalized-- their height is stretched such that the lowest point's value is 0.0 and the highest point is 1.0.

### The Global Options Dialog

Provides application-wide settings such as the POV-Ray executable name, maximum undo levels, and gamma.

## The Terrain Window

[To be written]

### Views

[To be written]

### Rendering

[To be written]

### The Render Options Dialog

[To be written]

### Rendering in POV-Ray

Exports the terrain to POV-Ray and calls the povray executable specified in the main options window. POV-Ray must be able to find its include files. Make sure you have a .povrayrc file in your home directory that has a line such as Library_Path=/usr/share/povray31/include.

### Basic Height Field Transforms

This menu provides essential operations you'd expect in a terrain manipulation program

#### Invert

Inverts the current height field, leaves the waterlevel unchanged.

#### Mirror

Mirror the height field along one of four axis. Horizontal (-), vertical (|), top-left bottom-right (\) or bottom-left top-right (/). This is useful for leaving the general characteristics of the landscape intact while changing it's layout.

#### Move

Offset the terrain wrapping it around the edges. Useful for moving a mountain to a desired location. If the terrain was not generated using spectral synthesis, it may be desirable to run the Tile filter first.

#### Rotate

Rotate the height field in increments of 90 degrees.

#### Scale

Allows you to either double or half the size of the current height field. A fractal algorithm is used to double the size of a terrain.

### Specialized Height Field Transforms

These operations map specific features onto a terrain.

#### Connect

This is the level connector plug-in as used in the MS Windows terrain editor leveller. It smooths selected terrain.

#### Craters

Place the specified number of craters on the height field using the specified parameters. This is a slightly modified version of John Beale's hf-lab crater routines. On the crater dialog, if you reduce the number of craters to 1, you can specify the exact locaton of the crater. Craters are placed only in selected areas. A crater is fully rendered even if it overlaps a nonselected area.

#### Erode

This routine calculates the flowmap and the uses the flowmap to erode the terrain, refreshing the flowmap at regular intervals (thus trading accuracy for speed). This is a lot faster than John Beale's code, but needs some more work.

#### Fill

Fill the terrain object up to the specified elevation, using using the tightness parameter to determine how much the altered points are allowed to deviate from the specified elevation.

#### Flowmap

Calculate the flowmap of the current height field (see code for details). You can choose between the Single-Flow-Direction algorithm (which is reasonably fast) or the Multiple-Flow-Direction algorithm (which is slow). On my machine (AMD K6-233) SFD takes about 2.5 seconds, while MFD takes around 30 minutes for a 400x400 height field.

#### Fold

The 'fold' option allows you to create a margin at the edge of the height field which is submerged below the current sealevel. This is useful to force a generated height field to be integratable into a scene with a predictable horizon or sealevel and is probably best used in small multiple steps.

#### Gaussian Hill

This creates a gaussian hill at the specified location with the specified parameters. You can use the 1st and 2nd mouse button to set the location parameters.

#### Radial Scale

Picks a point and scales the surrounding terrain in a circular maner. Can be used to make all sorts of circular shapes. Still needs some work.

#### Rasterize

This filter equalizes the elevation in the terrain in small rectangular sections. The tightness factor determines the "blockyness" of the terrain.

#### Roughen and Smooth

Use neighbour-averaging to roughen or smooth the height field. The factor determines how much of the computed roughening is actually applied to the height field. In it's default invocation, the 4 directly neighbouring squares are used to calculate the roughening. If you select big sampling grid, all 8 neighbouring cells will be used.

#### Terrace

Divide the terrain object into n specified levels with the specified closeness factor.

#### Tile

Make the current height field tilable. Still needs some work.

#### Transform

Transform applies power transformations to the current height field such that the land's height becomes statistically similar to the earth. Edges around the land flatten and drop sharply to the smooth ocean floor.

### Objects

#### Show

This show the standard objects available in Terraform.

#### Place

Place objects of one particular type onto a terrain

#### Remove All

Removes all objects from the terrain.

#### Move

Go into 2D Plane mode. Select the pointer toolbar button and move objects around by dragging and dropping them.

### Advanced Topics

[To be written]

#### Adding your own scene files and objects

It is possible to add your own scenes and objects to terraform. Go to the ~/.terraform directory and create the subfolders "objects", "themes" and "includes". Now you can place the files in the corresponding directory, now they can be used by terraform. If files with the same name occur in your home directory and in the system terraform directory the files in the home directory are used for rendering.

#### Hacking Terraform

See the Hacking Terraform document for more information.

#### Writing POV-Ray Templates

See the Writing POV-Ray Templates document for more information.