Terraform Frequently Asked Questions

Robert Gasch

   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.
     _________________________________________________________________
   
   Table of Contents
   1. [1]Terraform Overview
          
        [2]What is Terraform?
        [3]What systems does it run under?
        [4]What dependencies does it have?
        [5]How is it distributed?
        [6]Why are you writing it?
        [7]How complete is it?
        [8]What is your goal/mission with it?
        [9]What about Photorealistic output?
        [10]How can I contribute?
        [11]A Call to Arms!
        [12]Wow. What are you on?
        [13]Credits
                
   2. [14]Running and Using Terraform
          
        [15]Is there any information about all the transformations
                terraform supports?
                
        [16]What file formats does Terraform support?
        [17]When resizing a height field, the window always doesn't
                resize properly
                
        [18]I'm confused about the dialogs. What's the logic behind the
                OK button?
                
        [19]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
                
        [20]Does terraform support resource files?
        [21]Does terraform support themes?
        [22]How can I tell if my POVRay install is OK with terraform?
        [23]The POVRay render either fails or just isn't displayed
        [24]How can I customize the way the POVRay image is rendered?
                
   3. [25]Building Terraform and General Troubleshooting
          
        [26]How can I compile terraform?
        [27]Something's wrong. Where should I look first?
        [28]How do I submit a bug report and why should I bother to do
                so?
                
        [29]Do I really need imlib?
        [30]I get compile errors like about -fhuge-objects
        [31]I get link errors about undefined reference to
                `Gtk_Object::signal_connect
                
        [32]I get link errors about differing symbol sizes in
                GuiBufferedDrawingArea
                
        [33]Terraform segmentation faults upon startup (bt points to
                TFWindow.cc:77)
                
        [34]Something doesn't work. How can I see what's going on?
        [35]Terraform crashes while loading a file.
        [36]Terraform crashes. What useful information can I provide to
                the author?
                
        [37]Terraform exits with a failed SanityCheck.
     _________________________________________________________________
   
Chapter 1. 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 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 [38]gcc and [39]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:
   
     * [40]libglib and libgtk 1.2.x. You should be advised that due to
       some semi-serious bugs, libgkt 1.2.4 is notsupported.
     * [41]libgtk-- 1.0.x (Gtk-- 1.0.1 or greater recommended)
     * [42]optionally imlib 1.8 or greater
     * you need a C++ compiler (such as [43]gcc or [44]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 [45]GNU GPL and as such comes with
   full source code. You basically get everything I have. Terraform is
   available from it's home page [46]http://212.187.12.197/RNG/terraform/
   and possibly from other places such as the [47]Sunsite gtkbuffet
   mirror and [48]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.
   
   The current version (0.4.4) 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 (http://www.gimp.org), 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.
     _________________________________________________________________
   
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.
     _________________________________________________________________
   
Chapter 2. 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?

   Supported file types
   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:
   
   Terraform resource file parameter types
   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 [49]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.
     _________________________________________________________________
   
Chapter 3. 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 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.
     _________________________________________________________________
   
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.

References

   1. file://localhost/tmp/@5903.2#OVERVIEW
   2. file://localhost/tmp/@5903.2#AEN21
   3. file://localhost/tmp/@5903.2#AEN24
   4. file://localhost/tmp/@5903.2#AEN46
   5. file://localhost/tmp/@5903.2#AEN65
   6. file://localhost/tmp/@5903.2#AEN73
   7. file://localhost/tmp/@5903.2#AEN76
   8. file://localhost/tmp/@5903.2#AEN85
   9. file://localhost/tmp/@5903.2#AEN93
  10. file://localhost/tmp/@5903.2#AEN97
  11. file://localhost/tmp/@5903.2#AEN100
  12. file://localhost/tmp/@5903.2#AEN105
  13. file://localhost/tmp/@5903.2#AEN108
  14. file://localhost/tmp/@5903.2#RUNNINGTERRAFORM
  15. file://localhost/tmp/@5903.2#AEN115
  16. file://localhost/tmp/@5903.2#AEN119
  17. file://localhost/tmp/@5903.2#AEN174
  18. file://localhost/tmp/@5903.2#AEN177
  19. file://localhost/tmp/@5903.2#AEN183
  20. file://localhost/tmp/@5903.2#AEN186
  21. file://localhost/tmp/@5903.2#AEN230
  22. file://localhost/tmp/@5903.2#AEN241
  23. file://localhost/tmp/@5903.2#AEN256
  24. file://localhost/tmp/@5903.2#AEN264
  25. file://localhost/tmp/@5903.2#BUILDINGTERRAFORM
  26. file://localhost/tmp/@5903.2#AEN271
  27. file://localhost/tmp/@5903.2#AEN283
  28. file://localhost/tmp/@5903.2#AEN286
  29. file://localhost/tmp/@5903.2#AEN292
  30. file://localhost/tmp/@5903.2#AEN298
  31. file://localhost/tmp/@5903.2#AEN307
  32. file://localhost/tmp/@5903.2#AEN311
  33. file://localhost/tmp/@5903.2#AEN315
  34. file://localhost/tmp/@5903.2#AEN318
  35. file://localhost/tmp/@5903.2#AEN326
  36. file://localhost/tmp/@5903.2#AEN330
  37. file://localhost/tmp/@5903.2#AEN347
  38. http://www.gni.ai.mit.edu/software/gcc/gcc.html
  39. http://egcs.cygnus.com/
  40. http://www.gtk.org/
  41. http://www.iki.fi/terop/gtk/gtk--.html
  42. http://www.labs.redhat.com/imlib
  43. http://www.gni.ai.mit.edu/software/gcc/gcc.html
  44. http://egcs.cygnus.com/
  45. http://www.gnu.org/copyleft/gpl.html
  46. http://212.187.12.197/RNG/terraform/
  47. http://metalab.unc.edu/pub/Linux/X11/apps/
  48. http://www.linuxberg.com/
  49. http://gtk.themes.org/