3. The World File

The world file contains a description of the world to be simulated by Gazebo. It describes the layout of robots, sensors, light sources, user interface components, and so on. The world file can also be used to control some aspects of the simulation engine, such as the force of gravity or simulation time step.

Gazebo world files are written in XML, and can thus be created and modified using a text editor. Sample world files can be found in the worlds directory of the source distribution, or in the installed version (default install) under
/usr/local/share/gazebo/worlds/

3.1 Key Concepts and Basic Syntax

The world consists mainly of model declarations. A model can be a robot (e.g. a Pioneer2AT or SegwayRMP), a sensor (e.g. SICK LMS200), a static feature of the world (e.g. MapExtruder) or some manipulable object. For example, the following declaration will create a Pioneer2AT named ``robot1'':

  <model:Pioneer2AT>
    <id>robot1</id>
    <xyz>0 0 0.40</xyz>
    <rpy>0 0 45</rpy>
  </model:Pioneer2AT>

Associated with each model is a set of attributes such as the model's position <xyz> and orientation <rpy>; see Section 6 for a complete list of models and their attributes.

Models can also be composed. One can, for example, attach a scanning laser range-finder to a robot:

  <model:Pioneer2AT>
    <id>robot1</id>
    <xyz>0 0 0.40</xyz>
    <rpy>0 0 45</rpy>
    <model:SickLMS200>
      <id>laser1</id>
      <parentBody>chassis</parentBody>
      <xyz>0.15 0 0.20</xyz>
      <rpy>0 0 0</rpy>
    </model:SickLMS200>
  </model:Pioneer2AT>

The <parentBody> tag indicates which part of the robot the laser should be attached to (in this case, the chassis rather than the wheels). The <xyz> and <rpy> tags describe the laser's position and orientation with respect to this body (see Section 3.4 for a discussion of coordinate systems). Once attached, robot and the laser form a single rigid body.

3.2 Graphical User Interface

While Gazebo can operate without a GUI, it is often useful to have a viewport through which the user can inspect the world. In Gazebo, such user interface components are provided through special models (such as the ObserverCam) that can be declared and configured in the world file. See the documentation on the ObserverCam model for details.

3.3 Canonical World File Layout

The ``standard'' layout for the world file is can be seen from the examples included in the worlds directory. The basic components are as follows:

• XML meta-data, start of world block, more XML meta-data:

    <?xml version="1.0"?>
    <gz:world 
      xmlns:gz='http://playerstage.sourceforge.net/gazebo/xmlschema/#gz'
      ...
  

• Global parameters:

      <params:GlobalParams>
        <gravity>0.0 0.0 -9.8</gravity>
      </params:GlobalParams>
  

• GUI components:

      <model:ObserverCam>
        <id>userCam0</id>
        <xyz>0.504 -0.735 0.548</xyz>
        <rpy>-0 19 119</rpy>
        <window>
          <title>Observer</title>
          <size>640 480</size>
          <pos>0 0</pos>
        </window>
      </model:ObserverCam>
  

• Light sources (without lights, the scene will be very dark):

      <model:LightSource>
        <id>light0</id>
        <xyz>0.0 0.0 10.0</xyz>
      </model:LightSource>
  

• Ground planes and/or terrains:

      <model:GroundPlane>
        <id>ground1</id>
      </model:GroundPlane>
  

• Robots, objects, etc.:

      <model:Pioneer2AT>
        <id>robot1</id>
        <xyz>0 0.0 0.5</xyz>
        <model:SickLMS200>
          <id>laser1</id>
          <xyz>0.15 0 0.20</xyz>
        </model:SickLMS200>
      </model:Pioneer2AT>
  

• End of world block:

    </gz:world>
  

A detailed list of models and their attributes can be found in Chapters 5 and 6.

3.4 Coordinate Systems and Units

By convention, Gazebo uses a right-handed coordinate system, with x and y in the plane, and z increasing with altitude. Most models are designed such that the are upright (with respect to the z axis) and pointing along the positive x axis. The tag <xyz> is used to indicate an object's position (x, y and z coordinates); the tag <rpy> is used to indicate an objects orientation (Euler angles; i.e., roll, pitch and yaw). For example, <xyz>1 2 3</xyz> indicates a translation of 1 m along the x-axis, 2 m along the y-axis and 3 m along the z-axis; <rpy>10 20 30</rpy> indicates a rotation of 30 degrees about the z-axis (yaw), followed by a rotation pf 20 degrees about the y-axis (pitch) and a rotation of 10 degrees about the x-axis (roll).

Unless otherwise specified, the world file uses SI units (meters, seconds, kilograms, etc). The following idioms should also be noted:

• Angles and angular velocities are measured in degrees and degrees/sec, respectively.