Gazebo logo

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 for a complete list.

Basic usage is as follows:

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

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

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

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.

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

For Each Index:
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

Last updated 12 September 2005 21:38:45