/**
@page worldfile_syntax World File Syntax
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:
@verbatim
/usr/local/share/gazebo/worlds/
@endverbatim
@section worldfile_concepts 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:
@verbatim
robot1
0 0 0.40
0 0 45
@endverbatim
Associated with each model is a set of attributes such as the
model's position <xyz;> and orientation <rpy;>; see
@ref models 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:
@verbatim
robot1
0 0 0.40
0 0 45
laser1
chassis
0.15 0 0.20
0 0 0
@endverbatim
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 @ref worldfile_units
for a discussion of coordinate systems). Once attached, robot and the
laser form a single rigid body.
@section worldfile_gui 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.
@section worldfile_layout 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:
@verbatim
0.0 0.0 -9.8
@endverbatim
- GUI components:
@verbatim
userCam0
0.504 -0.735 0.548
-0 19 119
Observer
640 480
0 0
@endverbatim
- Light sources (without lights, the scene will be very dark):
@verbatim
light0
0.0 0.0 10.0
@endverbatim
- Ground planes and/or terrains:
@verbatim
ground1
@endverbatim
- Robots, objects, etc.:
@verbatim
robot1
0 0.0 0.5
laser1
0.15 0 0.20
@endverbatim
- End of world block:
@verbatim
@endverbatim
A detailed list of models and their attributes can be found in @ref models.
@section worldfile_units 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 of 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). One exception is angles and angular
velocities, which are measured in degrees and degrees/sec,
respectively.
*/