/** \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 */