TerraJ FAQ

What is TerraJ?

TerraJ is a set of fractal terrain and solar system generation programs that have been ported from C/C++ to Java.

The port has included extensive refactoring, the creation of a documented API to enable reuse of parts of them in other programs and extensions to the originals such as new Swing user interfaces. Full javadoc for the classes in the project is available.

Top ^

What Might it be Used For?

I hope that this software will be useful both for learning purposes and as part of other programs such as games and simulations.

The updated user interfaces mean that everyone should be able to play around with it and the refactoring has aimed to separate out code that might be useful to other projects. Go on, surprise me!

Top ^

What is Included?

The TerraJ suite currently contains the following software:

  • Fracplanet. Generates fractal planets and terrains with a wide range of user controlled parameters. Has an OpenGL rendering preview using JOGL and can export to POVRay format for rendering. Also includes experimental support for rendering with with the Rings raytracing engine, which is written in Java. Now includes Javascript control of the camera and rendering parameters.
  • Stargen. Creates realistic planetary systems and stars using an accretion simulation. The resulting text and HTML output is template based and configurable.
  • Planetary Terrain Generator. A second fractal terrain generation program. This one does not do 3D rendering but can output images using many different map projections.
  • Dole Accretion. An older and slightly less complex star system generator included for reference and completeness.
Top ^

What is Required to Run These Programs?

Most of the programs will run on any Java J2SE 1.5 runtime environment. Additionally to run Fracplanet you must have a platform that is supported by the JOGL OpenGL bindings library. This is currently Windows, Linux and OS X.

Some Linux systems will already have Java or you may have installed it to run other programs. To download a Java runtime for Windows and Linux go to: The Java Download Page.

To obtain Java 1.5 for OS X you will need to go to the Apple downloads site and search for the latest version.

To build and extend these programs you will need a suitable JDK. These can normally be downloaded from the same place as the JRE.

Note to run Fracplanet you will need to make sure the JOGL native libraries are available on your library path. The details of how to do this vary by platform. If you get an error that mentions UnsatisfiedLinkException then this is probably what is wrong.

If these problems persist then the library directory property can be set explicitly from the command line. On Windows this might look something like:

java -jar stargen.jar -Djava.library.path=c:/stargen/lib/natives-win32
On Linux it would probably be something like: 
java -jar stargen -Djava.library.path=/opt/stargen/lib/natives-linux

Obviously the paths will depend on where the program has been installed.

To generate large terrains you may need to increase the amount of memory available to the Java runtime system. To do this include -Xmx=size in the options passed to java. For example -Xmx=512m allocates up to 512 Mb. If you do not increase the memory size appropriately then you may get Out Of Memory errors with large terrains. This is not a bug in the program, honest!

Top ^

What License is TerraJ Released Under?

TerraJ is released under the GNU General Public License. This is one of the most widely used free software licenses. Everyone is welcome to modify and extend the software as it stands (providing they respect the GPL) and I hope some people will find uses for it in their own applications. An exception has been made in the license to allow linking to the BSD and Apache Commons libraries required by the program. I hope that GPL V3 will make this unnecessary when it is released.

Note: The original code was issued under a variety of licenses and some of it predates the existence of standard open software licenses. If you wish to use the original C code you should refer to the corresponding original source files and documentation rather than rely on anything that I've written about this.

Top ^

What about Contributions?

This is an open source project and contributions are welcome. Some of the things that would be good to have are:

  • New features or enhancements to existing ones
  • Rings Rendering
  • Better integration of the programs
  • Details of software that should be added to this collection, whether or not a Java version already exists.
  • Offers of collaboration or help from the authors of such software
  • Figuring out why Jalopy won't format the code any more (NullPointerExceptions etc ...)
Top ^

I Found a Bug ...

I'm sure there are quite a few. Its pretty unlikely to release 60,000 lines of code and for there not to be any problems with it. Testing this sort of application is quite hard both because of the complexity and because most of the output is based on things that are generated randomly.

If you do find problems with it then let me know, particularly differences from the ranges of values produced by the C code for programs like Stargen.

Top ^