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,
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 plug-ins, 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)
The two environments not directly supported by Terragen and addressed by this
Frame output options (-f)
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 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
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.
This option determines the format of the output tgs file(s). The options are as follows.
Additional options (-z and -p)
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 interpolation.
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
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
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 bydelta = 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 is2 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
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
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