Terragen Animation Extension (tgs_interp)

Written by Paul Bourke
July 2003, updated November 2004

"Terragen is a scenery generator, created with the goal of generating photorealistic landscape images and animations.....capable of near-photorealistic results for professional landscape visualisation, special effects, art and recreation." [Terragen web site].


There are a number of environments in which one might want to create content using Terragen but for which Terragen doesn't provide explicit support eg: stereoscopic projection, fisheye frames for planetarium domes, panoramic images. The following describes a utility that solves this problem and as a side effect conforms to conventions that allow time consuming animation rendering to be performed locally on a large rendering cluster of 200+ processors.

The utility is called "tgs_interp" mostly because it provides keyframe interpolation (supported by keyframe files in Terragen called a .tgs file). The basic work flow is to create a tgs file using Terragen or plugins, use tgs_interp to read this tgs file and instruct it to create a number of other tgs files which will then be read and rendered by Terragen. In the case of stereoscopic projection two tgs frames result from each interpolated frame. For cubic projection 5 or 6 tgs frames result for each interpolated frame. The utility is written for UNIX command line operation, currently compiled for Mac OS-X and Linux.

Usage: tgs_interp [options] tgsfile
   -n n   number of tween frames (default: 1)
   -c n   calculate cubic views, 5 or 6 (default: off)
   -s n   calculate stereo pairs, supply eye separation (default: off)
   -p n   add a pitch offset in degrees, positive pitch forward (default: 0)
   -f n   tgs splitting mode, 0=single, 1=lots, 2=stereo, 6=cubic
   -z n   adjust camera height (default: 0)
Projection options

The two environments not directly supported by Terragen and addressed by this utility are:

  • Stereoscopic (-s)
    In this case the camera is offset to the left and right of the non-stereoscopic position. The width of the left and right images should be widened for rendering in Terragen and truncated afterwards to create the correct stereo pairs, this is discussed in more detail here and later in this document.

  • Cubic (-c).
    Cubic renderings are created by rendering 5 or 6 perspective frustums, namely the frustums formed from the center of a cube about the camera and each of the faces of the cube. These renderings can then combined into a fisheye image (or other projections such as panoramic or spherical) using techniques described here. Note that the QuickTime VR support in terragen isn't quite good enough for creating fisheye animations because the faces of the cube in that case are aligned with the coordinate axes rather than the camera view direction.

Frame output options (-f)

This option determines the format of the output tgs file(s). The options are as follows.

  • 0 - All the frames are written to a single tgs file, the default. This is usually the choice when tgs_interp is simply used as a keyframe interpolator.

  • 1 - Each frame is written to a single tgs file. This is intended primarily for locally developed cluster based distributed rendering software, use with care...it can create lots of files.

  • 2 - This is intended for use with stereoscopic output, the left and right eye frames will each be written to their own tgs file. Recommended for stereoscopic output.

  • 3 - This is intended for cubic output, each of the 5 or 6 faces (left, front, right, back, top, bottom) will be written to their own tgs file. Recommended for cubic output.

Additional options (-z and -p)
  • Height adjustment (-z)
    This raises or lowers the camera along the camera "up" vector.

  • Pitch adjustment (-p)
    This will pitch the camera forward or upward by some angle. Primarily intended for creating fisheye content for planetarium domes which have different ideal horizon levels. Note that this can also be performed using the software that converts cubic views to a fisheye image.

Notes on stereoscopic rendering

There are a number of ways of formulating and setting up stereoscopic rendering, the approach taken here will be the correct parallel camera method and since Terragen doesn't support offaxis frustums it will be based upon the techniques described here. In essence this involves rendering frustums that are slightly wider than desired and truncating the images to give the correct stereo pairs. The following example outlines how the author would set up a stereoscopic rendering using Terragen and tgs_interp.

  • The horizontal camera aperture "a" (also called the horizontal field of view) is controlled in Terragen by the zoom setting. The relationship is

    zoom = 1 / tan(a/2)

    So in this example if the intended horizontal aperture is 60 degrees, the Terragen zoom is 1.732

  • The degree to which the image width (as specified in Terragen) should be increased is given by

    delta = e w / (2 fo tan(a/2))

    So in this example, if the final image width "w" is to be 1024 pixels and the eye separation 100 units and the distance to zero parallax is 3000 units, then amount by which the image width will be extended is 30 pixels. Note this is based upon the eye separation being 1/30 of the distance to zero parallax, a common ratio. It is often more useful to think in terms of the zero parallax distance and then use 1/30 of that for the eye separation.
    So, Terragen should be instructed to render an image that is 1054 pixels wide. After the images are rendered 30 pixels will be removed from the left of the left eye image and 30 pixels will be removed from the right of the right eye image. This process in effect creates offaxis frustums even though only symmetric frustums were available.

  • And finally, to be strictly correct the aperture and hence the zoom setting in Terragen needs to be recalculated, the expression is

    2 atan((w + delta) tan(a/2) / w)

    In this example the intended aperture is 61.443 degrees and the zoom to be set in Terragen is 1.683. This is a relatively minor adjustment that is often not bothered with.

Left eye, model courtesy of Peter Morse
Right eye

Notes on cubic rendering and derived projections

The width and height of the rendered image should be set equal before rendering. The zoom factor set by the user will be reset to 1, in other words a horizontal (and vertical) aperture of 90 degrees.

Unfolded cube, model courtesy of Peter Morse

Derived spherical panoramic

Derived cylindrical panoramic

Derived fisheye

Further notes

  • The Mac and MSWindows version of Terragen seem to be slightly out of step with how animation files are named. Until this is resolved tgs_anim will use it's own conventions that just happen to be those preferred by the author and most compatible with local conventions used for stereoscopic content and animations for planetariums.

  • This utility has been tested/checked with the current version of Terragen and the format/style of the tgs files it creates. Obviously future versions of terragen may change details of the tgs files that this utility assumes, or new features may be added for which this utility is ignorant. Every attempt will be made to keep this utility in step with the current version of Terragen.