Terragen .TER Format - Revision history

Matt: Added link to tgter on Github

2020-10-23T20:12:11Z

Added link to tgter on Github

Matt: Parentheses in equation in last paragraph

2020-10-23T20:09:15Z

Parentheses in equation in last paragraph

Matt: Correction to altitude equation in the last paragraph

2020-10-23T20:08:02Z

Correction to altitude equation in the last paragraph

JavaJones: Created page with "= Terragen™ Terrain file specification = == File Structure == A terrain file contains a 16-byte identifier followed by a number of chunks. The positions of the various chunks..."

2012-11-09T16:49:12Z

Created page with "= Terragen™ Terrain file specification = == File Structure == A terrain file contains a 16-byte identifier followed by a number of chunks. The positions of the various chunks..."

New page

= Terragen™ Terrain file specification =

== 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:

# An 8-byte "TERRAGEN" string at the beginning of the file.
# An 8-byte "TERRAIN " string located 8 bytes from the beginning of the file. (Note the last space character.)
# A "SIZE" chunk.
# If the terrain is not square, "XPTS" and "YPTS" chunks are required.
# 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.

<blockquote> 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. </blockquote>

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

<blockquote> 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. </blockquote>

'''"SIZE"''' 4-byte marker, necessary. Must appear before any altitude data.

<blockquote> 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. </blockquote>

'''"SCAL"''' 4-byte marker, optional. Must appear before any altitude data.

<blockquote> 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. </blockquote>

'''"CRAD"''' 4-byte marker, optional. Must appear before any altitude data.

<blockquote> 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. </blockquote>

'''"CRVM"''' 4-byte marker, optional. Must appear before any altitude data.

<blockquote> 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. </blockquote>

'''"ALTW"''' 4-byte marker. Must appear after the "SIZE" marker. Must appear after the "XPTS" and "YPTS" markers (if they exist).

<blockquote> ALTW stands for 'Altitude in 16-bit Words'. After The "ALTW" marker, the following appear in order: <blockquote>''HeightScale'', a 2-byte signed integer value. ''BaseHeight'', a 2-byte signed integer value. ''Elevations'', a sequence of 2-byte signed integers. </blockquote> 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. </blockquote>

← Older revision		Revision as of 20:12, 23 October 2020
Line 53:		Line 53:

	<blockquote> ALTW stands for 'Altitude in 16-bit Words'. After The "ALTW" marker, the following appear in order: <blockquote>''HeightScale'', a 2-byte signed integer value. <br />''BaseHeight'', a 2-byte signed integer value. <br />''Elevations'', a sequence of 2-byte signed integers. </blockquote> 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) </blockquote>		<blockquote> ALTW stands for 'Altitude in 16-bit Words'. After The "ALTW" marker, the following appear in order: <blockquote>''HeightScale'', a 2-byte signed integer value. <br />''BaseHeight'', a 2-byte signed integer value. <br />''Elevations'', a sequence of 2-byte signed integers. </blockquote> 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) </blockquote>
		+
		+	== C++ Code ==
		+
		+	A reference implementation and header-only C++ library can be found here:
		+
		+	https://github.com/mfairclough/tgter

← Older revision		Revision as of 20:09, 23 October 2020
Line 52:		Line 52:
	'''"ALTW"''' 4-byte marker. Must appear after the "SIZE" marker. Must appear after the "XPTS" and "YPTS" markers (if they exist).		'''"ALTW"''' 4-byte marker. Must appear after the "SIZE" marker. Must appear after the "XPTS" and "YPTS" markers (if they exist).

−	<blockquote> ALTW stands for 'Altitude in 16-bit Words'. After The "ALTW" marker, the following appear in order: <blockquote>''HeightScale'', a 2-byte signed integer value. <br />''BaseHeight'', a 2-byte signed integer value. <br />''Elevations'', a sequence of 2-byte signed integers. </blockquote> 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. </blockquote>	+	<blockquote> ALTW stands for 'Altitude in 16-bit Words'. After The "ALTW" marker, the following appear in order: <blockquote>''HeightScale'', a 2-byte signed integer value. <br />''BaseHeight'', a 2-byte signed integer value. <br />''Elevations'', a sequence of 2-byte signed integers. </blockquote> 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) </blockquote>

← Older revision		Revision as of 20:08, 23 October 2020
Line 52:		Line 52:
	'''"ALTW"''' 4-byte marker. Must appear after the "SIZE" marker. Must appear after the "XPTS" and "YPTS" markers (if they exist).		'''"ALTW"''' 4-byte marker. Must appear after the "SIZE" marker. Must appear after the "XPTS" and "YPTS" markers (if they exist).

−	<blockquote> ALTW stands for 'Altitude in 16-bit Words'. After The "ALTW" marker, the following appear in order: <blockquote>''HeightScale'', a 2-byte signed integer value. <br />''BaseHeight'', a 2-byte signed integer value. <br />''Elevations'', a sequence of 2-byte signed integers. </blockquote> 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. </blockquote>	+	<blockquote> ALTW stands for 'Altitude in 16-bit Words'. After The "ALTW" marker, the following appear in order: <blockquote>''HeightScale'', a 2-byte signed integer value. <br />''BaseHeight'', a 2-byte signed integer value. <br />''Elevations'', a sequence of 2-byte signed integers. </blockquote> 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. </blockquote>