Ignition Gazebo

API Reference

Importing a Mesh to Fuel

This tutorial will explain how to import a mesh to the Ignition Fuel web application. Adding models and/or worlds to Fuel will make your content readily available to the open source robotics simulation community, and easier to use with the Ignition GUI.


To import meshes to Fuel, you need to have a user account. Go to app.ignitionrobotics.org and click Login in the top right corner of the screen, then click Sign Up. Once you verify your email address, your account will be ready.

You'll need a mesh ready before trying to import to Fuel. There are several ways to acquire a mesh. To save time, we'll use this Electrical Box model that you can download from Fuel.

Model Directory Structure

Fuel expects meshes to be contained inside model directories that follow a specific structure and format. Download and unzip the Electrical Box model mentioned above, and you should see the structure of its contents as follows:

Electrical Box
├── materials Directory for textures
└── textures
├── meshes Directory for COLLADA, STL, and Wavefront OBJ files
├── thumbnails Directory for preview images
├── model.config Meta data about the model
└── model.sdf SDF description of the model

A model directory needs to adhere to this file structure to successfully import to Fuel. The contents of each directory and file are equally as important; each part is covered below.


The materials directory is for textures. Textures are optional; they provide color or detail to a mesh. If you download a mesh online, the texture files should come with it. Otherwise, you would have to use a 3D modeling tool to correctly design a texture.

The Electrical Box's texture is under materials > textures > Electrical Box.png.


The meshes directory is where the actual mesh files go. The mesh could be one of several 3D model file types: .dae, .stl, .obj, etc. This file is produced with a 3D modeling tool.

The Electrical Box's mesh is under meshes > Electrical Box.dae


Thumbnails are .png files named 1 through 5. Each contains a view of the model from a different angle to be displayed on the image carousel on its "Fuel Model Info" page.


The model.config file is required in the root of the model directory. It contains meta data about the model in XML format. You have to create this file and add it to the model directory.

Here is the Electrical Box's model.config:

<?xml version='1.0'?>
<name>Electrical Box</name>
<sdf version='1.6'>model.sdf</sdf>
Generated with mesh_to_sdf

Customize the name and description tags to fit your model. The sdf version should ideally be the latest version. Inside the sdf tags is the name of the SDF file describing your model.


The Electrical Box's model.sdf file is as follows:

<?xml version='1.0' ?>
<sdf version='1.6'>
<model name='Electrical Box'>
<link name='link'>
<pose>0 0 0 1.57 3.14159 0</pose>
<collision name='collision'>
<uri>model://Electrical Box/meshes/Electrical Box.dae</uri>
<visual name='visual'>
<uri>model://Electrical Box/meshes/Electrical Box.dae</uri>

You can learn more about SDF here. For this tutorial, it's mostly only important to take note of the <uri> tags. Following model:// is the path within the model directory to the mesh.

Upload to Fuel

Once you have all your content accumulated in a model directory, you're ready to upload to Fuel. Click on the + button at the top right corner of the page, next to your account button, and then select Model.

Typically, you would try to ensure that the Model name field matches the name tags in both model.config and model.sdf, and the Description field matches its corresponding tag in model.config.

For the sake of this tutorial, however, we're going to enter your model name as Electrical Box Test to differentiate it from the original. In the Description field, write something like Test model for Importing a Mesh to Fuel tutorial.

Click the Add folders button, or drag and drop the Electrical Box folder you unzipped earlier into the labeled area. All the files in your model description will be listed there. Press Upload, and the "Fuel Model Info" page for your model will open.

Electrical Box Test

You can always delete a model by clicking the "Edit model" button and then selecting "Delete model" at the bottom of the page

Delete model

Include the Model in a World

With your mesh successfully uploaded to Fuel, you can now easily include it in a world SDF file.

Copy this example world code into a text editor and save it as import_mesh.sdf. This is a simple world SDF file, which you can learn more about on the SDF website.

Scroll all the way to the bottom of the file until you see the include tag section following the `` comment line.

<?xml version="1.0" ?>
<sdf version="1.6">
<world name="fuel">
<name>Electrical Box</name>
<pose>0 0 0 0 0 0</pose>
<uri>https://fuel.ignitionrobotics.org/1.0/openrobotics/models/Electrical Box</uri>

The address between the uri tags is how you include your Fuel model in the world. To include your model, not the original, change openrobotics to your Fuel username. You also need to customize the last section of the URI to match your model's name on Fuel. Change Electrical Box to Electrical Box Test.

The syntax for including any model from Fuel is:

<uri>https://fuel.ignitionrobotics.org/1.0/<user account name>/models/<model name></uri>

Launch World

To launch the world and see your mesh, run Ignition from inside the directory where you saved import_mesh.sdf:

ign gazebo import_mesh.sdf
Launch sample world with mesh