# Terraform Frequently Asked Questions

Terraform FAQ
v&tfversion
&docownerFirst
&docownerLast

&docownermail

&wwwterraform

April 7. 2000

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

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 GTK (actually Gtk--) widget set 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 wether your compiler supports all required ANSI C++ features.

### What dependencies does it have?

Terraform requires the following:

- libglib and libgtk 1.2.x. You should be advised that due to some semi-serious bugs, libgkt 1.2.4 is notsupported.

- libgtk-- 1.1.x (Gtk-- 1.1.10 or greater recommended)

- optionally imlib 1.8 or greater

- you need a C++ compiler (such as gcc or egcs) which has sufficient support of ANSI C++ features such as member templates, C++ cast operators and a working string class.

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 &wwwterraform 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--.

The current version (&tfversion) should support more features and hopefully less bugs.

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 (&wwwgimp), where many of these ideas come from):

- implement selection so that you can select a subset and work on that only

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

### What about Photorealistic output?

I typically use PovRay (www.povray.org) 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 raytraced 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. POVRay 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 file `docs/UsersGuide`. 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?

File Type | Read | Write
--- | --- | ---
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
ACAD Modeller | N | Y

### When resizing a height field, the window always doesn't resize properly

This is a bug. I have not yet been able to figure out what I'm doing wrong. Resizing currently only seems to work when the window size increases.

### I'm confused about the dialogs. What's the logic behind the OK button?

If you click OK without having done anything else, the action is performed and the dialog closed. If you click OK after having clicked Apply, the dialog simply closes and the action is not performed.

When you're using the Subdivision or Specral Synthesis dialogs, the first time (after calling the dialog from the menu) when you click on Apply, a Height Field will be generate in a new window. Subsequent Applys will generate new HeightFields in the newly opened window until the dialog is closed.

### I would like to generate a height field of size x but the slider increments are too big to allow me to select that size

Position the slider to a value close to what you want and then use the left and right arrow keys to set the final value you want.

### Does terraform support resource files?

Yes. Terraform will check for (and read) `TF_DATADIR/system.terraformrc` and then `$HOME/.terraformrc` where TF_DATADIR is a variable set at compile time. To find out the resource file settings terrafrom was compiled with, you can say

- `terraform --helprc`

and it will tell you what it's resource file locations are. To install a terraform resource file, you can use the builtin method of

- `terraform --installrc`

to have terraform write the configuration file `.terraformrc` with the default settings to your home directory. Finally you can say

- `terraform --helprc`

to see the resource file settings terrafrom was compiled with and get a list of supported resource file options.

The format of the resource file is very simple. The first 2-letter prefix of the option name refers to the option's type and thus specifies what kind of paramter it expects:

Resource Prefix | Data Type | Sample Data
--- | --- | ---
b_ | boolean | 0(FALSE), 1(TRUE)
i_ | integer | 1, 2, 3, 4, ...
f_ | float | 0.1234, 987.321, Pi, ...
s_ | string | any string, typically a file name/path

### 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.

### How can I tell if my POVRay install is OK with terraform?

Try the following:

- `povray +i tf_land.pov`

where `tf_land.pov` is the file distributed in the terraform root directory. If you get the following type of error:

- tf_land.pov:26: error: Error opening TGA image.

you're OK in the sense that POV can find it's include files (tf_land.pov is a template file which has to be processed to render). If you get an error about "colors.inc" your POV can't find it's include files and you need to go fix your povrayrc.

If this fails, check to see if your executable is named `povray-x`; some distributions use this naming scheme to distinguish between the X and SVGA povray executables. If this applies to your situation, you should use the `--pov_exec povray-x` flag to specify what your povray executable is called.

### The POVRay render either fails or just isn't displayed

If the default export to POVRay fails or if it just isn't displayed (even though no error is reported), it could be that your POVRay is of version 3.0, while Terraform expects version 3.1. If you are using version 3.0, use the `--pov30` switch to inform terraform of this.

Alternativeley you can use the `--debug 255` switch to have the actual povray output echoed to the standard output. This output should help you figure out what is being done going and what is going wrong.

To see what POVRay version you have installed, simply type `povray` and the first line of output displayed will contain the version number.

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

You can edit the file `tf_land.pov` to your liking as long as you keep the TF* placeholders for terraform to substitute. Alternativeley you can also point terraform at another POV file through the Options dialog or the terraform resource file. Whatever POV file terraform uses must contain the TF* placeholders for terraform to be able to use it. If you come up with something neat, consider sending me the POV file, so I can add it to the terraform distribution.

## 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`

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

Since Terraform builds on Gtk--, please take a look at the Gtk-- FAQ. It covers some of the basic things about compiling Gtk-- programs.

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

How: Mail &docownermail 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.

### Do I really need imlib?

No. Terraform uses imlib's JPG read for the about dialog and the PNG and TIFF read as an additional height field formats. Configure should let you compile terraform without imlib. If you run into problems, run

- `configure --disable-imlib`

which will revert back to the default code base which doesn't use imlib.

### I get compile errors like about -fhuge-objects

I get compile errors like: TFDialogOptions.h:87: sorry, not implemented: object size exceeds normal limit for virtual function table implementation, recompile all source and use -fhuge-objects

Yes, certain verions of egcs seem to need this flag in order to compile terraform. As of version 0.3.6 I've rewritten most of the GUI code to use dynamic memory allocation (vs. allocating objects on the stack), so if you get this error, you should mail me about it so I can rework some code internals in order to avoid this warning. This is a CPU-type specific feature, so what may work on one type of CPU, might result in a huge-objects error on another platform.

In order to compile the version you have, simply re-run the configure script as follows:

- `configure --enable-hugeobjects`

You should then see the flag -fhuge-objects being passed to g++ during the compile process. If you need this, you should be aware that both your Gtk-- and all other programs using it need to be compiled with the same -fhuge-objects flag.

### I get link errors about undefined reference to `Gtk_Object::signal_connect

I get link errors like: TFWindow.o: In function `ItemFactoryConnector[TFWindow, basic_string [char, string_char_traits[char], __default_alloc_template[true, 0] ] ]::connectTo(Gtk_Widget *) const': TFWindow.o(.ItemFactoryConnector[TFWindow, basic_string[char, string_char_traits[char], __default_alloc_template[1, 0] ] ]::gnu.linkonce.t.connectTo(Gtk_Widget *) const+0x23e): undefined reference to `Gtk_Object::signal_connect(char const *, void (*)(...), void *)'

This is usually the result of having different compile options for glib, Gtk+ and Gtk--, specifically the -pedantic option. Make sure you use the same '-pedantic'ness for each of these libraries. Either all or none of these should be compiled with -pedantic.

### I get link errors about differing symbol sizes in GuiBufferedDrawingArea

I get like errors like: ld: warning: symbol 'Connection_impl virtual table' has differing sizes: (file GuiBufferedDrawingArea.o value=0x10; file /usr/local/opt/libgtk--/lib/libgtkmm.so value=0x20); GuiBufferedDrawingArea.o definition taken

I've only heard of this once from the owner of a Sun Solaris (+egcs) machine, but it seems to be the result of having different compile options for Gtk-- and terraform, specifically the -fhuge-objects flag. Make sure you use the same '-fhuge-object'ness for both Gtk-- and Terraform (actually all your Gtk-- programs). Either all or none of these should be compiled with -fhuge-objects.

### Terraform segmentation faults upon startup (bt points to TFWindow.cc:77)

I've only heard this once in which case the solution (and another symptom) are described under section in the previous section about the -fhuge_objects flag. If terraform crashes without these symptoms, you've found a new bug.

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

If you find that Terraform isn't behaving as it should, you might want to try running `terraform --verbose` which will give you verbose debug output. Alternativeley, you can try `terraform --debug level` where level is an integer between 0 and 255. See the source files `GlobalTrace.h` and `GlobalTrace.cc` for the details of this.

### 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 SanityCheck.

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