/**
\page tutorial_model Model Creation Tutorial
This tutorial will describe how to create your own custom model. The contents of this page include:
- \ref tutorial_model_create : Basics of creating a model
- \ref tutorial_model_create_mesh : Change a model's skin
- \ref tutorial_model_create_material : Change a model's material
- \ref tutorial_model_joints : Add joints to a model
- \ref tutorial_model_geoms : Add multiple geometries to a body
- \ref tutorial_model_controller : Add controllers to a model
- \ref tutorial_model_include : Separating models into separate files. Allows for easy inclusion of models into a world.
- \ref tutorial_model_nesting : Connect models in a parent-child relationship
\section tutorial_model_overview Overview
Models form the core of the Gazebo simulation. They encompass all physical entities and sensors. Since models are so important, they should be easily created and modified. Gazebo utilizes XML to define all the physical aspects of a model.
This tutorial will first describe how to create a new model using Gazebo's xml language, and then how to controll the model using interfaces and controllers.
\section tutorial_model_create Physical Construction
All physical aspects of a model are defined within an XML file. This includes position, orientation, density, joints, etc. There are a few basic rules to follow when constructing a model:
- Name everything : All models, bodies, and geoms must have names. These names hshould be unique, but this is not strictly enforced.
- A model must contain a body.
- A body can contain only senors and/or geometries.
\subsection tutorial_model_create_simple Simple Shape
We'll start with a simple example by create a model a box. A box model consists of one body that contains one geometry.
\verbatim
0 1.5 0.5
0.0 0.0 0.0
box1_body
false
0.0 0.0 0.0
0.0 0.0 0.0
0.0 0.0 0.0
0.0 0.0 0.0
default
1 1 1
1.0
Gazebo/BumpyMetal
\endverbatim
In this example the starting position of the model is 1.5 meters up (Z-axes), and 0.5 meters along the Y axis. The model has no rotation.
The canonicalBody tag defines which body within a model should be used when nesting models. Nesting occurs when a model is defined withing another model. This creates a parent-child relationship, and a joint attached the two models together by connecting their respective canonical bodies. If this tag is left out, the first body in the model is automatically used as the canonical body.
The static flags indicates whether this model is affected by physics. If set to false, then the model will never move, but will still collide with other moving objects. If set to true, then the physics engine will update the model according to it mass, position, collisions, etc.
This model contains one body that is not offset from the model's position. Contained within this model is one geometry that is not offset from the body's position. The mesh tag is used to attach a 3D mesh to the geometry. This is mesh is used for visualization only. By setting mesh to default the internal mesh is used for the geometry.
The size tag indicates how big the geometry should be. The density tag is used to calculate the mass of the geometry. Finally, the material tag indicates what texture should be applied to the geometry.
\subsection tutorial_model_create_mesh Changing the Mesh
By changing the mesh tag a new "skin" can be applied to a geometry. The value of the mesh tag should match one of the OGRE models. Contained within the Gazebo sources at gazebo/Media/models is a set of predefined meshes.
If you would like to use a different mesh, say the fish mesh, then modify the mesh tag:
\verbatim
fish
\endverbatim
Take a look at the \ref tutorial_mesh for info on creating your own mesh.
\subsection tutorial_model_create_material Changing the Material
The material applied to a geometry can also be changed through OGRE. The list of available materials are contained withing gazebo/Media/materials/scripts/Gazebo.material
If you want to use a different material, say FlatBlack, then change the material tag accordingly:
\verbatim
Gazebo/FlatBlack
\endverbatim
\section tutorial_model_joints Creating Joints
Joints connect two bodies together. These are useful for attaching wheels to a car body, or creating an articulated arm. The types of joints available are:
- \ref gazebo_ball_joint
- \ref gazebo_hinge_joint
- \ref gazebo_hinge2_joint
- \ref gazebo_universal_joint
- \ref gazebo_slider_joint
If a model is being created to simulate a Pioneer2DX robot, two hinge joints should be attached between two wheel bodies and on chassis body. Additionally, a rear castor wheel must be connected to the chassis using a ball joint. Read the ODE manual for a description of the various joints.
Suppose this pioneer2dx model has the following named bodies:
- left_wheel_body
- right_wheel_body
- castor_body
- chassis_body
The left hinge joint would be:
\verbatim
left_wheel
chassis_body
left_wheel
0 1 0
0.4
0.008
\endverbatim
The right hinge joint would be:
\verbatim
right_wheel
chassis_body
right_wheel
0 1 0
0.4
0.008
\endverbatim
The axis tag in the above two joints indicates the axis of motion. In this case the two wheels will rotate around the Y-axis. The erp and cfm tags indicate the error reduction parameter and constrain force mixing parameter. See the ODE manual for more insight into these parameters.
And the castor joint would be:
\verbatim
castor_body
chassis_body
castor_body
0.4
0.008
\endverbatim
Since a ball joint rotates in all directions, no axis tag is used.
\section tutorial_model_geoms Bodies with Multiple Geometries
A body can contain one or more geometries, thereby allowing for complex shapes. Each geometry within a body can have a unique position on rotation relative to the parent body.
In this example we will create a cylindrical wheel that contains a box at the hub.
\verbatim
0.1 -0.17 -0.0725
0 90 90
default
0.075 0.05
0.5
Gazebo/Black
default
0.0 0.0 -0.010
0.05 0.05 0.05
0
Gazebo/White
\endverbatim
Note that the cylinder geom has no position and orientation offset from the parent body, while the box geom is translate -0.01 meters along the Z-axis.
\section tutorial_model_controller Controllers
Many models will require movement and/or the ability to publish sensor data.
Controllers make this functionality possible by simulating a physical
device. For example, a Pioneer2DX model should have a controller that
allows it move around, and a SickLMS-200 model should have a controller that
publishes laser data.
Controllers are compiled into gazebo, and are linked to model using XML:
\verbatim
left_wheel_hinge
right_wheel_hinge
\endverbatim
The above example creates a position controller for a pioneer2dx. The first
two children, leftjoint and rightJoint, tell this
controller which two joints make up the drive train. The last child
parameter, defines what libgazebo interface the controller will read
commands from and write data to.
Each controller requires it's own unique set of parameters, depending on
it's functionality. The interface parameter is required to link a controller
to a libgazebo interface. Without this link the controller cannot receive
command and publish data.
\section tutorial_model_include XML Include
A model can be defined in a seperate file, and included within another world
file. This mechanism creates the possiblity of including the same model many
times within one world without duplicating code.
The seperate model file should only contain the definition of the model. See gazebo/worlds/pioneer2dx.model for an example.
A model can be included within a world using two different methods. The first assumes that the included model does not require any modifications.
\verbatim
\endverbatim
If an included model should have some slight modfications, such as a name or position change, then use this method:
\verbatim
1 0 0.25
0.0 0.0 0.0
left_wheel_hinge
right_wheel_hinge
\endverbatim
In the above example the pioneer2dx model has had a controller added to it, and it's position changed. Note that the included model file should be last within the model declaration.
\section tutorial_model_nesting Nesting Models
Models can be nested together, allowing for arbitrarily complex models. This
is most useful when attaching sensors to a robot. In this example we will
connect a SickLMS laser to a Pioneer2dx robot.
If we have use the pioner2dx.model and the sicklms200.model provided in the Gazebo sources (gazebo/worlds), out nested model would look like:
\verbatim
0 0 0.5
0 0 0.2
\endverbatim
*/