Gazebo is able to dynamically load models into simulation either programmatically or through the GUI. Models exist on your computer, after they have been downloaded or created by you. This tutorial describes Gazebo's model directory structure, and the necessary files within a model directory.
Models in Gazebo define a physical entity with dynamic, kinematic, and visual properties. In addition, a model may have one or more plugins, which affect the model's behavior. A model can represent anything from a simple shape to a complex robot; even the ground is a model.
Gazebo relies on a database to store and maintain models available for use within simulation. The model database is a community-supported resource, so please upload and maintain models that you create and use.
The model database is a bitbucket repository found here.
You can clone the repository using:
hg clone https://bitbucket.org/osrf/gazebo_models
A model database must abide by a specific directory and file structure. The
root of a model database contains one directory for each model, and a
database.config file with information about the model database. Each model
directory also has a
model.config file that contains meta data about the
model. A model directory also contains the SDF for the model and any materials,
meshes, and plugins.
The structure is as follows (in this example the database has only one model called
This is an optional directory that contains all of the plugins for the model.
This is an optional directory that contains all of the COLLADA and/or STL files for the model.
This is an optional directory that contains all of the textures, images, and OGRE scripts for the model. Texture images must be placed in the
textures subdirectory, and OGRE script files in the
This is the
database.config file in the root of the model database. This file contains license information for the models, a name for the database, and a list of all the valid models.
database.config file is only required for online repositories. A directory full of models on your local computer does not need a
The format of this
<?xml version='1.0'?> <database> <name>name_of_this_database</name> <license>Creative Commons Attribution 3.0 Unported</license> <models> <uri>file://model_directory</uri> </models> </database>
The name of the database. This is used by the GUI and other tools.
The license for the models within the database. We highly recommend the Creative Commons Attribution 3.0 Unported license.
A listing of all the model URIs within the database.
The URI for a model, this should be
Each model must have a
model.config file in the model's root directory that contains meta information about the model.
The format of this
<?xml version="1.0"?> <model> <name>My Model Name</name> <version>1.0</version> <sdf version='1.5'>model.sdf</sdf> <author> <name>My name</name> <email>email@example.com</email> </author> <description> A description of the model </description> </model>
Name of the model.
Version of this model.
Note: This is not the version of sdf that the model uses. That information
is kept in the
The name of a SDF or URDF file that describes this model. The
version attribute indicates what SDF version the file uses, and is not required for URDFs. Multiple <sdf> elements may be used in order to support multiple SDF versions.
Name of the model author. * <email> required
Email address of the author.
Description of the model should include:
- What the model is (e.g., robot, table, cup)
- What the plugins do (functionality of the model)
All the dependencies for this model. This is typically other models.
URI of the model dependency.
Version of the model.
Each model requires a
model.sdf file that contains the Simulator Description Format of the model. You can find more information on the SDF website.
Standard SDF file which can contain ruby code embedded. This option is used to
programatically generate SDF files using Embedded Ruby code
templates. Please note that the ruby conversion should be done manually (
model.sdf.erb > model.sdf) and the final
model.sdf file must be uploaded
together with the
model.sdf.erb (this one only for reference).