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:
Other elements within a world file indicate how to render a scene via the ogre declaration, attributes of the GUI via the gui declaration, and properties of the physics engine via the ode declaration. These declarations are required by Gazebo.
Each world file is encapsulated by:
<gazebo:world> ... </gazebo:world>
The contents describe a single simulation configuration. Each top level declaration is preprended by a namespace prefix that describes the declaration type. For example, the ogre declaration is prepended by rendering:
<rendering:ogre> ... </rendering:ogre>
<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.
<model:physical name="box_model"> <body:box name="box_body"> <geom:box name="box_geom"/> </body:box> </model:physical>
Note that each model, body, and geom must have a name. Unique names are highly suggested but not enforced.
The above example is simplified. Attributes that indicate the size, shape, mass, position, and texture of the model have been left out. The following is a complete box model:
<model:physical name="box_model"> <xyz>0 1.5 0.5</xyz> <rpy>0.0 0.0 0.0</rpy> <canonicalBody>box1_body</canonicalBody> <static>false</static> <body:box name="box_body"> <xyz>0.0 0.0 0.0</xyz> <rpy>0.0 0.0 0.0</rpy> <geom:box name="box_geom"> <xyz>0.0 0.0 0.0</xyz> <rpy>0.0 0.0 0.0</rpy> <mesh>default</mesh> <size>1 1 1</size> <density>1.0</density> <material>Gazebo/BumpyMetal</material> </geom:box> </body:box> </model:physical>
- xyz : Position relative to parent
- rpy : Orientation relative to parent
- canonicalBody : Body used to attached child and parent models
- static : Set to true to make the model immovable
- mesh : The "skin" of the geom, this is not used for collision detection
- size : Size of the geometry.
- density : Density of the geometry
- material : Material used to color and texture the geometry
The entire physical characteristics of a model is encapsulated within the xml. Joints are attached bettween two bodies with the same modele using:
<joint:hinge name="left_wheel_hinge"> <body1>body1_name</body1> <body2>body2_name</body2> <anchor>body2_name</anchor> <axis>0 1 0</axis> <erp>0.4</erp> <cfm>0.008</cfm> </joint:hinge>
- body1 : First body used by the joint. The parameter is the name of the body.
- body2 : Second body used by the joint. The parameter is the name of the body.
- anchor : The body to use ad the joint achor.The parameter is the name of the body.
- axis : Axis of rotation for the joint.
- erp : Error reduction parameter, see ODE
- cfm : Constraint force mixing parameter, see ODE
The above exmple creates a hinge joint between body1_name and body2_name, both of which must exist within the model.
Complex models can become quite long and cumbersome to use, especially when the same model is required numerous times in the same world. To alleviate this issue, model's can be written in separate files and included within a world.
The above model can be saved as box.model and used within the world:
<include embedded="false"> <xi:include href="box.model"/> </include>
- embedded : False if the included file does not need parameters overwritten.
- href : The location of the model file
Sometimes it is useful to include the same model with slightly different paramters. This can be accomplished by creating a new model, with a nested include:
<model:physical name="box_model1"> <xyz> 1 1 0 </xyz> <include embedded="true"> <xi:include href="box.model"/> </include> </model:physical>
Note that the include should be last within the model declaration.
See pioneer2dx.world and pioneer2dx.model for a more elaborate examples.
Each controller makes use of one or more interfaces. An interface defines what data is exposed via libgazebo. For example, the pioneer2dx_position2d controller can utilize the position interface.
The following example creates a pioneer2d_position2d controller called "controller1", that controller the left and right joints with names "left_wheel_hinge" and "right_wheel_hinge". The interface is a position interface named "position_iface_1".
<controller:pioneer2dx_position2d name="controller1"> <leftJoint>left_wheel_hinge</leftJoint> <rightJoint>right_wheel_hinge</rightJoint> <interface:position name="position_iface_1"/> </controller:pioneer2dx_position2d>
<physics:ode> <stepTime>0.03</stepTime> <gravity>0 0 -9.8</gravity> <cfm>0.008</cfm> <erp>0.2</erp> </physics:ode>
- stepTime : Number of seconds the physics simulation should progress during each update.
- gravity : Vector that describes the direction and magnitude of gravity.
- cfm : The global constraint force mixing.
- erp : The global error reduction parameter.
<rendering:gui> <type>fltk</type> <size>640 480</size> <pos>0 0</pos> </rendering:gui>
- type : Type of GUI. Currently only fltk is supported.
- size : Size of the rendering window.
- pos : Position of the rendering window.
Ambient light is specified using:
<ambient>1.0 1.0 1.0 1.0</ambient> \verbatim The material used for the sky box is specified using: \verbatim <sky> <material>Gazebo/CloudySky</material> </sky>
Fog is specified usin:
<fog> <color>0.8 0.8 0.8</color> <type>linear</type> <density>0.0</density> <linearStart>50.0</linearStart> <linearEnd>515.0</linearEnd> </fog>
- color : Color of the fog
- type : Type of fog (linear, exp, exp2)
- density : Density of the fog
- linearStart : Distance from the camera to begin rendering fog
- linearEnd : Distance from the camera to stop rendering fog
OGRE resources are specified using the following (most people should only change the path information to match where they installed Gazebo):
<plugins path="/usr/local/lib/OGRE"> <plugin>RenderSystem_GL.so</plugin> <plugin>Plugin_ParticleFX.so</plugin> <plugin>Plugin_BSPSceneManager.so</plugin> <plugin>Plugin_OctreeSceneManager.so</plugin> </plugins> <resources path="/usr/local/share/gazebo"> <bootstrap> <zip>Media/packs/OgreCore.zip</zip> </bootstrap> <general> <filesystem>Media</filesystem> <filesystem>Media/fonts</filesystem> <filesystem>Media/materials/programs</filesystem> <filesystem>Media/materials/scripts</filesystem> <filesystem>Media/materials/textures</filesystem> <filesystem>Media/models</filesystem> <filesystem>Media/overlays</filesystem> <filesystem>Media/particle</filesystem> <filesystem>Media/gui</filesystem> <zip>Media/packs/cubemap.zip</zip> <zip>Media/packs/cubemapsJS.zip</zip> <zip>Media/packs/skybox.zip</zip> </general> </resources>