# Terraform Frequently Asked Questions

Author: Robert Gasch, Updated by David A. Bartold

This is the FAQ for Terraform, an interactive fractal landscape generator/modeller. Chances are you can encounter a lot more problems than I've managed to answer here, so if have any suggestions concerning this document, drop me an email.

- Terraform Overview
  - What is Terraform?
  - What systems does it run under?
  - What dependencies does it have?
  - How is it distributed?
  - Why are you writing it?
  - How complete is it?
  - What is your goal/mission with it?
  - What about Photorealistic output?
  - How can I contribute?
  - A Call to Arms!
  - Wow. What are you on?
  - Credits
- Running and Using Terraform
  - Is there any information about all the transformations terraform supports?
  - What file formats does Terraform support?
  - Does terraform support Gtk+ themes?
  - POV-Ray render fails
  - How can I customize the way the POVRay image is rendered?
- Building Terraform and General Troubleshooting
  - How can I compile terraform?
  - Something's wrong. Where should I look first?
  - How do I submit a bug report and why should I bother to do so?
  - Something doesn't work. How can I see what's going on?
  - Terraform crashes while loading a file
  - Terraform crashes. What useful information can I provide to the author?
  - Terraform exits with a failed assertion

## Terraform Overview

This section covers questions that pertain to Terraform as a whole.

### What is Terraform?

Terraform is an interactive fractal landscape generator/viewer. It allows you to create fractal terrain (also called a height field) and transform it using a number of algorithms. It is meant to be a tool for those who want to generate digital terrain models for use in raytracing or other simulations. It's written in C using the GNOME libraries and as such has a non-sucking graphical user interface.

### What systems does it run under?

Terraform was written under Linux (or GNU/Linux if you're an RMS faithful) and should run under any UNIX type system that has the proper libraries and compilers installed. The following are a list of systems that I know terraform has successfully been compiled under

- Linux ix86 Debian 2.1 glibc
- Linux ix86 Mandrake 7.0 glibc (using gcc-2.95)
- Linux ix86 Mandrake 6.0 glibc (using pgcc-2.91.66, gcc-2.95)
- Linux ix86 Mandrake 6.1 glibc (using pgcc-2.91.66, gcc-2.95)
- Linux ix86 Redhat 5.2 glibc (using egcs-2.91.57)
- Linux ix86 Redhat 6.0 glibc (using egcs-2.91.66)
- Solaris Sparc 2.6 (using egcs 2.91.66)
- Solaris Sparc 2.7 (using gcc 2.8.1)

The compiler versions given above are intended as a reference point for a particular platform and the accompanying compiler. Other compiler versions of both gcc and egcs may work just as well or even better, especially if the version is higher than what's listed above. The configure scripts checks wether your system has all required libraries installed and whether your compiler supports all required ANSI C features.

### What dependencies does it have?

Terraform requires the following:

- The GNOME Desktop, version 1.2
- GNOME Print v0.25 or greater
- GNOME XML

The configure scripts checks wether all necessary compiler features are supported on your system. Typically, you should try to have the most recent version of the required libraries installed on your system.

### How is it distributed?

Terraform is released under the GNU GPL and as such comes with full source code. You basically get everything I have. Terraform is available from it's home page http://terraform.sourceforge.net and possibly from other places such as the Sunsite gtkbuffet mirror and Linuxberg.

The rationale for using the GPL is simple: I have profitted enourmously (as has the entire Linux community) from the availability of free software that comes with source code. I wish for this process to continue and see the GPL as the mother of open source software licences which will assure the continued availablilty/openness of the source code.

### Why are you writing it?

Because I think coding is fun and I have no other life :-) ... the truth is that I was looking for something like John Beale's gforge and hf-lab but with a nicer user interface. John's tools are very good but are command-line driven, which is fine for most things but not ideal for graphical things.

### How complete is it?

Well, it's slowly getting there. The first public release (0.1.0, released 07DEC98) was very rudimentary and contained lots of bugs.

As of release 0.2.10 (relased 07APR1999) things look a lot better: Terraform is now a lot more complete and doesn't crash as much while having gained lots of functionality.

As of release 0.3.1 (released 23MAY1999) things look better again. The dialogs have been upgraded to a real time preview dialog and I've fixed quite a few bugs, some of which caused seemingly random crashes on some platforms.

As of release 0.4.4 (released 28OCT1999) we have a pretty complete set of dialogs and an engine that can keep mulitple height fields open in parallel.

As of release 0.5.0 (released 20DEC1999) the source code is a lot saner/cleaner and terraform now supports internationalization.

As of release 0.6.x (Feb2000 or later) the most basic things work, most dialogs are fixed/finished, the app doesn't crash much anymore and things generally work OK, execpt for the occasional bug that either hits terraform or Gtk--.

As of release 0.7.x (18JUN2000 or later) POV-Ray scenes were added and the beginnings of a selection interface emerged. The new operation Move was added and many bugs were fixed.

The current version (0.8.x) runs under the GNOME desktop, has Glade generated interface code, new contour line code, its own native file format, faster terrain view screen updates, fewer bugs, and online help.

It's come quite a way but still has ways to go before I have it doing what I want. Please realize that I have a job and a life and that I'm writing terraform after work at night or on weekends. As such my progress will at best be steady but certainly not lightning-fast.

### What is your goal/mission with it?

While I don't have an exactly spelled out vision (ie: I didn't sit down and make an actual design document), I would like it to eventually become the GIMP of digital terrain. Here are some things that I eventually want terraform to have (if you're not sure what I mean take a look at The GIMP, where many of these ideas come from):

- ability to 'draw' your height field with different 'brushes'

### What about Photorealistic output?

I typically use POV-Ray to render the landscapes I generate. A while ago though, on www.slashdot.org there was mention of a Windows (blah!) application called 'terragen' which produces photorealistic output. I haven't downloaded/installed it but the web page they have looks very nice. Of course, in the wonderful world on MS Windows, they don't seem to have any intention of releasing the source.

If the lack of finished native realistic output annoys you, I invite you to respond to my Call to Arms below.

### How can I contribute?

Making Terraform into a complete and polished application will take some major (or at least persistent) effort on my part (ie: don't hold your breath waiting for verion 1.0). As such, if you can contribute anything (code, fixes, suggestions, documentation), read my A Call to Arms below.

### A Call to Arms!

If you can contribute anything (code, fixes, documentation or even suggestions) I would appreciate hearing from you. Part of the open source philosophy seems to be "Do it yourself" so here's your chance.

Lets prove to the world that the whole open source thing really works and that we can make something that isn't put to shame by terragen (or maybe even puts terragen to shame?). If you are able and willing help out in any way with extending terraform to produce photorealistic output of landscapes, please contact me.

We've made some progress on this front over the past few months. POV-Ray support is now pretty good and is still being worked on. OpenGL support went from butt-ugly to basic-but-acceptable, and we're working (or at least thinking about) integration with some other cool front ends.

### Wow. What are you on?

The crack pipe, lots of illegal drugs or just a mission. You pick the one that sounds most appropriate.

### Credits

Terraform in many respects build on publicly available code. See the AUTHORS for details on what was stolen from where.

## Running and Using Terraform

This section covers general questions you may have about using particular aspects of using Terraform.

### Is there any information about all the transformations terraform supports?

Check out the online documentation. It contains a brief description of what the different operations really do. If that doesn't satisfy your curiosity, there's always the source code ...

### What file formats does Terraform support?

Supported file types:

File Type | Read | Write
Terraform Native | Y | Y
BMP | Y | N
DEM | Y | N
GTOPO30 | Y | N
Matlab Binary | Y | Y
OCT | Y | Y
PGM ASCII | Y | Y
PGM BINARY | Y | Y
PNG | Y | N
TIFF | Y | N
TGA | Y | Y
AutoCAD Modeller | N | Y

### Does terraform support themes?

Yes. As of version 0.3.1 terraform properly supports Gtk themes. If you have a gtk theme on your system, you can enable it for your user by doing the following:

    cp /usr/whereever/THEMENAME/gtk/gtkrc $HOME/.gtkrc

If you get errors about being unable to open theme files, you should edit your .gtkrc and add a line like this

    pixmap_path "/usr/whereever/THEMENAME/gtk"

at the *beginning* of this file. Terraform should now load the theme upon startup.

### POV-Ray render fails

You can get more information about the execution problems by clicking the "Details" on an error dialog box, if one appears. There are several common reasons why POV-Ray might fail:

- You must use POV-Ray version 3.1 or greater. Old 3.0 versions will not work.
- Make sure Terraform can find the X capable POV-Ray executable. In the global options, click on the POV-Ray tab and make sure it points to the right executable. The most popular names are "x-povray" and "povray-x". Sometimes it's just "povray".
- Make sure POV-Ray can find its standard include files. In your ~/.povrayrc file there should be a line similar to: "Library_Path=/usr/share/povray31/include".

### How can I customize the way the POVRay image is rendered?

You can create your own terrain theme file and put it in the themes data directory (usually /usr/share/terraform/themes). The next time you open up the Edit > Options dialog box, the theme combo box will display your new template file as an option. For more information on designing your own textures, see the writing your own POV-Ray templates document.

## Building Terraform and General Troubleshooting

This sections covers some of the things that may go wrong when you try to build or run terraform.

### How can I compile terraform?

Assuming you've downloaded the source archive, you should be able to do the following:

tar -xvzf terraform-0.x.x.tgz ./configure make && make install

If you are running SuSE, it is recommended to run ./configure with these command-line arguments: "--prefix=/opt/gnome --sysconfdir=/etc/opt/gnome".

### Something's wrong. Where should I look first?

Since Terraform builds on GNOME, verify that GNOME and its development packages are installed on your system.

### How do I submit a bug report and why should I bother to do so?

How: Mail rng@chello.nl and describe what you did and what went wrong.

Why: In my experience, lots of subtle little bugs only turn up when compiling the code on another OS or hardware platform. As such, if you're not on an Intel Glibc Linux system, and something breaks, I would appreciate a mail; especially so, if it's in a rather obvious place as this usually indicates a bug that might just not appear on my system. Your bug reports help me make Terraform a better application.

### Something doesn't work. How can I see what's going on?

Try running Terraform from gdb and do a backtrace "bt" to view the callstack.

### Terraform crashes while loading a file.

Make sure that the extension of your filename matches the actual file type. Ie: don't try to rename a *.tga file to a *.bmp file and then load it into terraform. This is currently considered a feature.

### Terraform crashes. What useful information can I provide to the author?

If you've downloaded the precompiled executable you can't do much at this point as the executable is stripped of all debug information. The best thing is probably to send me an email describing what you did.

If you compiled your own executable from the source code, please recompile terraform with the -g flag (add the -g flag to the TF_CFLAGS and TF_CXXFLAGS variables in terraform/src/Makefile). Then use gdb (or any other debugger) to send me a stack trace:

    gdb ./terraform
    r [append any necessary options here]
    .... this will run until it crashes ...
    bt
    q

The bt command should give you a stack trace which should help me figure out what went wrong. You can use ./configure --disable-debug to compile an executable without the built in stack trace facility.

If you downloaded the static executable, don't bother doing this as your executable has been stripped off all debug information; as such the information above only applies if you compiled your own executable. Thank you for your cooperation.

### Terraform exits with a failed assertion

This is a situation which should not occur; it signifies a logic error somewhere in the application. Please mail me what you did so I can reproduce and fix the error.