Terrain Builder Utility

The terrain builder processes an elevation data file and outputs a binary data file loadable by the Terrain model. The input file can be of any type loadable by GDAL, see http://www.gdal.org/formats_list.html for a complete list.

Basic usage is as follows:

$ gzbuilder [options] -i <inputfile> -o <outputfile>

where [options] is one or more of the following:

Parameters:

	-i	<filename> Input terrain file.
	-o	<filename> Output Gazebo terrain file.
	-e	<double> Acceptable error bound on terrain approximation (meters). Set this to zero for no approximation.
	-h	<double> Horizontal scaling factor (m).
	-v	<double> Vertical scaling factor (m).
	-n	Normalize Z-values before scaling.
	-x	<double> X offset (m).
	-y	<double> Y offset (m).
	-z	<double> Z offset (m).
	-u	<int> UTM zone. Default is 11
	-s	<double> X size of texture (meters)
	-t	<double> Y size of texture (meters)

Example: Building a maze

Maze-like environments can be built by providing gzbuilder with a simple monochrome image. The figure, for example, shows an input image and resultant terrain as visualized by the server.

Input image

Output terrain

The terrain file was generated using the following command:

$ gzbuilder -i maze.gif -o maze.gzb -n -v 1.8 -h 0.1 -e 0.1

where the options are:

-n : Normalize the input image values in the range 0 (black) to 1 (white).

-v 1.8 : Scale heights such that white pixels correspond to an elevation of 1.8m.

-h 0.1 : Scale image such that each pixel corresponds to a horizontal distance of 0.1m (i.e., a 10cm grid spacing).

-e 0.1 : Generate an approximated terrain whose maximum elevation error is no more than 0.1m.

Note changing the error parameter can radically alter the output terrain: setting this value too low will result in a slow simulation (many vertices); setting this value too high will result in a "melted" maze.

By default, the terrain is located such that the bottom-left corner of the image maps to (0, 0) in simulator coordinates. This can be offset using the xyz tag in the Terrain model.

Note also that the terrain can be arbitrarily translated and rotated by the terrain model; by

Example: Building and using a geo-registered terrain

Digital Elevation Maps (DEMs) of real environments can be obtained from various sources on the internet (some are free, some are less-than-free). These maps are generally geo-registered; i.e., they have built-in latitude, logitude and altitude offsets. The gzbuilder utility will convert these offsets into standard UTM coordinates (using the -u UTM zone option) and store this offset the terrain file. One can also take a simple image (with no lat/lon/alt data), and apply an arbitrary UTM offset using the -x -y -z options.

When using geo-registered terrains, it is necessary to define a UTM offset in the global parameters section of the world file. This offset governs the transformation between simulation coordinates and UTM coordinates; i.e., the point (0, 0, 0) in the simulation frame is mapped to point (utmOffset.x, utmOffset.y, utmOffset.z) in the UTM frame. The UTM coordinates printed by the terrain builder may be used for this purpose.

Output File Format

The binary file format is composed of a header followed by 1..VertexCount of vertex datum followed by 1..IndexCount of index datum followed by 1..ODEIndexCount of ODE index datum.

All data is in network byte order, and each value is 4 bytes in length.

A multiplication factor must be divided back out upon reading a value.

Header

Value Description Original Data Type

version number * 1e3 float

X-offset Whole int

X-offset Fractional * 1e6 float

Y-offset Whole int

Y-offset Fractional * 1e6 float

Z-offset Whole int

Z-offset Fractional * 1e6 float

Vertex Count int

Index Count int

ODE Index Count int

Header
Value Description	Original Data Type
version number * 1e3	float
X-offset Whole	int
X-offset Fractional * 1e6	float
Y-offset Whole	int
Y-offset Fractional * 1e6	float
Z-offset Whole	int
Z-offset Fractional * 1e6	float
Vertex Count	int
Index Count	int
ODE Index Count	int

For Each Vertex:

Vertex Datum

Value Description Original Data Type

S Texture Coord * 1e3 float

T Texture Coord * 1e3 float

Red Color * 1e3 float

Green Color * 1e3 float

Blue Color * 1e3 float

Alpha Color * 1e3 float

X Normal * 1e3 float

Y Normal * 1e3 float

Z Normal * 1e3 float

X Position * 1e3 float

Y Position * 1e3 float

Z Position * 1e3 float

Vertex Datum
Value Description	Original Data Type
S Texture Coord * 1e3	float
T Texture Coord * 1e3	float
Red Color * 1e3	float
Green Color * 1e3	float
Blue Color * 1e3	float
Alpha Color * 1e3	float
X Normal * 1e3	float
Y Normal * 1e3	float
Z Normal * 1e3	float
X Position * 1e3	float
Y Position * 1e3	float
Z Position * 1e3	float

For Each Index:

Index Datum

Value Description Original Data Type

Index Value int

Index Datum
Value Description	Original Data Type
Index Value	int

For Each ODE Index:

Index Datum

Value Description Original Data Type

ODE Index Value int

Index Datum
Value Description	Original Data Type
ODE Index Value	int

Last updated 12 September 2005 21:38:45