BTG file format

Terrain in FlightGear is currently stored using the Binary Terrain Format, in *.btg or *.btg.gz files. These files contain geometry in the form of points, individual triangles, triangle strips and triangle fans.

The authoritative source for the format definition is the class SGBinObject, which is defined in simgear/io/sg_binobj.{hxx,cxx}.

General Structure

Each BTG-File contains a header followed by a variable number of objects. Each object is introduced by a header indicating the type of object, the number of associated properties and the number of elements contained in the object.

All coordinates in the file are geocentric/cartesian coordinates, with

• the center of the earth being the origin,
• the z-axis aligned with the earth axis pointing north,
• the x-axis going through the Greenwich Meridian at its intersection with the equator, and
• the y-axis going through the intersection of the meridian at 90 degrees east and the equator.

In order to allow more compact storage, all coordinates are stored as single precision floating point values relative to the center of a bounding sphere, except for the bounding sphere itself, which is stored in double precision format.

All measurements are in meters.

Endianness

The files are stored in Little Endian, i.e. the least-significant byte is stored first.

Header

Byte offset	Type	Description
0	unsigned short	Version (currently 7)
2	unsigned short	Magic Number 0x5347 ("SG")
4	unsigned int	Creation Time (seconds since the epoch)
8	unsigned short	Number of Toplevel Objects

In files before version 7, the number of toplevel objects was interpreted as a signed short, leading to a maximum number of 32767 objects in a single file.

Objects

Each object starts by an object header.

Byte offset	Type	Description
0	char	Object Type (see below)
1	unsigned short	Number of Object Properties
3	unsigned short	Number of Object Element

The object type can be one of the following:

Code	Object Type
0	Bounding Sphere
1	Vertex List
2	Normal List
3	Texture Coordinates List
4	Color List
9	Points
10	Individual Triangles
11	Triangle Strips
12	Triangle Fans

The object header is followed by a list of properties. The number of properties in this list is given by the Number of Object Properties field.

Byte offset	Type	Description
0	char	Property Type (see below)
1	unsigned int	Number of Bytes in Property Data
5	bytes	Property Data

The property type can be one of the following (see the object type descriptions for more details):

Code	Property Type
0	Material
1	Index Types

Similarily, each element starts with a single unsigned integer, giving the number of bytes the element's data occupies.

Bounding Sphere Object

The Bounding Sphere object gives the bounding sphere of the tile, defined by a center and a radius.

The properties of a Bounding Sphere are ignored.

The elements of the Bounding Sphere object are bounding spheres. Even though more than one bounding sphere may be stored in such an object, all except for the last one found in the file are ignored.

Byte offset	Type	Description
0	unsigned int	number of bytes in this element
4	double	x-part of the center
12	double	y-part of the center
20	double	z-part of the center
28	float	radius of the bounding sphere

Note that the element may be longer than 32 bytes, but only the first 32 bytes are actually used.

Vertex List

The Vertex List object contains a list of vertices to be referenced by other geometry primitives.

The properties of a Vertex List object are ignored.

Each element of a Vertex List object is a list of vertices. Each of the vertices gets a unique index, starting with 0 for the first vertex found in the file and incrementing by 1 for each further vertex.

Byte offset	Type	Description
0	unsigned int	number of bytes in this element
4	vertices	vertex list

Each vertex is a triple of single precision floating point values:

Byte offset	Type	Description
0	float	x-part of the vertex coordinates
4	float	y-part of the vertex coordinates
8	float	z-part of the vertex coordinates

The number of vertices in an element is therefore the number of bytes in the element divided by 12.

Normal List

The Normal List contains a list of normals to be referenced by other geometry primitives.

The properties of a Normal List object are ignored.

Each element of a Normal List object is a list of normals. Each of the normals gets a unique index, starting with 0 for the first normal found in the file and incrementing by 1 for each further normal.

Byte offset	Type	Description
0	unsigned int	number of bytes in this element
4	normals	normal list

Each normal is a triple of signed bytes, interpreted as fixed point values:

Byte offset	Type	Description
0	byte	x-part of the normal coordinates
1	byte	y-part of the normal coordinates
2	byte	z-part of the normal coordinates

The individual parts are interpreted by dividing each of the parts by 127.5 and subtracting 1.0, leading to a linear mapping from the range of 0...255 to the range of -1.0...1.0.

Texture Coordinates List

TODO

Color List

TODO

Points

TODO

Individual Triangles

TODO

Triangle Strips

TODO

Triangle Fans

TODO