Terragen™ Terrain
file specification
File Structure
The Chunks


File Structure

A terrain file contains a 16-byte identifier followed by a number of chunks. The positions of the various chunks are not rigidly defined, so if you are writing a terrain file reader it should allow for the flexibility of chunk positioning. However, if you are writing out terrain files, beware that some chunks must appear before others.

All chunks are aligned to the nearest 4 bytes. Each chunk contains a 4-byte marker (eg. "ALTW"), then some data.

Note: The structure of a chunk in a terrain file is different from that of the chunks found in some other Terragen files. Terrain file chunks do not include a "length of data" value.

A terrain file must contain the following:

1) An 8-byte "TERRAGEN" string at the beginning of the file.
2) An 8-byte "TERRAIN " string located 8 bytes from the beginning of the file. (Note the last space character.)
3) A
"SIZE" chunk.
4) If the terrain is not square, "XPTS" and "YPTS" chunks are required.
5) A 4-byte "EOF " string at the end of the file (necessary for old versions of Terragen).
Following these, the actual elevation data may be described. Future versions of Terragen may support compression of the data, or a more efficient storage method, but until then the elevation data is stored in an "ALTW" chunk.

Please note that all distance units (X, Y and Z) are in Terrain units, and not metres. If you need to convert from metres, the default scale is 30 metres to one terrain unit. The actual scale value for a particular terrain is stored in its "SCAL" chunk.


The Chunks

"XPTS" 4-byte marker. Must appear after the "SIZE" marker. Must appear before any altitude data.

The "XPTS" marker is followed by a 2-byte integer value xpts, followed by 2 bytes of padding. xpts is equal to the number of data points in the x-direction in the elevation image.
"YPTS" 4-byte marker. Must appear after the "SIZE" marker. Must appear before any altitude data.
The "YPTS" marker is followed by a 2-byte integer value ypts, followed by 2 bytes of padding. ypts is equal to the number of data points in the y-direction in the elevation image.
"SIZE" 4-byte marker, necessary. Must appear before any altitude data.
The "SIZE" marker is followed by a 2-byte integer value equal to n - 1, followed by 2 bytes of padding. In square terrains, n is the number of data points on a side of the elevation image. In non-square terrains, n is equal to the number of data points along the shortest side.
Example: a terrain with a heightfield 300 points in the x-direction and 400 points in the y-direction would have a size value of 299.
"SCAL" 4-byte marker, optional. Must appear before any altitude data.
The "SCAL" marker is followed by three intel-ordered 4-byte floating point values (x,y,z). It represents the scale of the terrain in metres per terrain unit. Default scale is currently (30,30,30). At present, Terragen can not use non-uniform scaling, so x, y and z must be equal.
"CRAD" 4-byte marker, optional. Must appear before any altitude data.
The "CRAD" marker is followed by one intel-ordered 4-byte floating point value. It represents the radius of the planet being rendered and is measured in kilometres. The default value is 6370, which is the approximate radius of the Earth.
"CRVM" 4-byte marker, optional. Must appear before any altitude data.
The "CRVM" marker is followed by one unsigned integer. Mode 0 means the terrain is rendered flat (default). Mode 1 means the terrain is draped (and stretched) over a sphere of radius CRAD*1000/zscale, centred at (midx, midy, -CRAD*1000/zscale), where midx=XSIZE/2 and midy=YSIZE/2. (Terrain sizes are one less than the number of points on the side.)
The x and y values are undistorted, therefore the map will still look normal when viewed from above, but geographic distances will be stretched towards the edge of the map if there is a lot of curvature. There is also an implicit limit on the size/curvature radius of a landscape before the landscape becomes unacceptably distorted.
Other curve modes are currently undefined, and reserved for the future.
"ALTW" 4-byte marker. Must appear after the "SIZE" marker. Must appear after the "XPTS" and "YPTS" markers (if they exist).
ALTW stands for 'Altitude in 16-bit Words'. After The "ALTW" marker, the following appear in order:
HeightScale, a 2-byte signed integer value.
BaseHeight, a 2-byte signed integer value.
Elevations, a sequence of 2-byte signed integers.
There are (xpts * ypts) elevation integers, where xpts and ypts will have been set earlier in the "SIZE" chunk or the "XPTS" and "YPTS" chunks. The elevations are ordered such that the first row (y = 0) is read first from left to right, then the second (y = 1), and so on. The values in Elevations are not absolute altitudes. The absolute altitude of a particular point (in the same scale as x and y) is equal to BaseHeight + Elevation * HeightScale / 65536.


Last modified 2003.10.30 by Matt Fairclough

Terragen, this site and its contents are all copyright 2003 Planetside Software, contact@planetside.co.uk
Terragen is a trademark of Planetside Software
All other trademarks are the property of their respective owners