Note: This tutorial assumes that you have completed the previous tutorials: Bring up TurtleBot in stage.
(!) Please ask about problems and questions regarding this tutorial on Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Customizing the Stage Simulator

Description: Explains how to use your own map with the stage simulator for turtlebot and adjust configurations for your needs

Tutorial Level: INTERMEDIATE

Set environment variables, Modifying a map and robot, add/remove objects.


The following files in the turtlebot_stage folder are all the preset launch and configuration files:

$ launch/turtlebot_in_stage.launch
$ maps/maze.png
$ maps/maze.yaml
$ maps/stage/
$ maps/stage/
$ rviz/robot_navigation.rviz 

The rviz file is basically a big dump of rviz settings and won't be touched in this tutorial. "" defines the layout of the turtlebot and its sensor and will just be mentioned at the end of the tutorial.

For this tutorial we'll use the preset config files and modify these. For this make a copy of the files "world", "yaml" and "png" file to a folder of your choice. In the example below we use "~/stageTutorial/".

cp maps/maze.png ~/stageTutorial/tutorial.png
cp maps/maze.yaml ~/stageTutorial/tutorial.yaml
cp maps/stage/ ~/stageTutorial/

Modifiying a map

To modify the map simply use your favourite image editor and open "tutorial.png" (which you created in the setup chapter). The copy of the "world" and "yaml" file still points to the old file names so we have to make some edits.

In the "tutorial.yaml" file change in the followorldw line the default map from "maze.png" to "tutorial.png" or the path to the file if it is not in the same folder:

  image: maze.png

And also edit the following 2 lines in "" where the first is just an abitrary name and the second the path to the "tutorial.png" file:

  name "tutorial"world
  bitmap "../tutorial.png"

Also the path to the "" file has to be adjusted as it was relative to the "world" file:

include ""

Now simply start the simulator and rviz up with following line:

roslaunch turtlebot_stage turtlebot_in_stage.launch map_file:="~/stageTutorial/tutorial.yaml" world_file:="~/stageTutorial/"

If you want to use the same "world" and "yaml" file without having to put them in as arguments all the time you can change the environment variables for them:

export TURTLEBOT_STAGE_MAP_FILE=~/stageTutorial/tutorial.yaml
export TURTLEBOT_STAGE_WORLD_FILE=~/stageTutorial/

You can also add it to your shell setup, so it does get set everytime you source your setup file:

echo export TURTLEBOT_STAGE_MAP_FILE=~/stageTutorial/tutorial.yaml >> devel/
echo export TURTLEBOT_STAGE_WORLD_FILE=~/stageTutorial/ >> devel/

Modifiying robot position

As you modify the map it could happen that your robot ends up starting in a wall. In this case the robot starting position has to be changed. As we use rviz and the stage simulator we have to change the position in both.

The robot position in the stage simulator is defined in the "" file. Simply change the pose parameters [x, y, z, theta] to what you need (z doesn't seem to change anything, theta is in degree):

  pose [ 2.0 2.0 0.0 0.0 ]
  name "turtlebot"
  color "black"

The same position has to be set via arguments when calling roslaunch:

roslaunch turtlebot_stage turtlebot_in_stage.launch map_file:="~/stageTutorial/tutorial.yaml" world_file:="~/stageTutorial/" initial_pose_x:=2.0 initial_pose_y:=2.0 initial_pose_a:=0.0

Adding Objects and Includes

To add moveable objects which can represent dynamic obstacles we can define a new block in a seperated file we call "":

define block model
  size [0.500 0.500 1.500]
  gui_nose 0

Size defines the basic size of the model which is in our case squared and 1.5m high. "gui_nose" says if the model should have an indicator of the direction it is facing towards. More properties are listed here:

The model file has to be included in our world file and we can then insert models of the type block into our map:

include ""

#adding blocks
block( pose [ 2.000 4.000 0.000 0.000 ] color "green")
block( pose [ 4.000 4.000 0.000 0.000 ] color "red")

Further Modifications

Map changes

Changing the map always needs adjustment of both the corresponding "yaml"-file and the "world"-file. The parameters of both files are different and have to aligned. In the "world"-file you need to specify the location of the center of the map but in the "yaml"-file the position of the lower left corner / "orgin". "yaml" wants a resolution whereas the "world"-file needs the size of the full map in meters.

Changing anything else

The launch file has the settings for the navigation, sensors, etc. Refer to the corresponding wiki entries for information on these.

The actual specification of the robot (size, position of sensor) for the simulator is in the "".

What Next?

Wiki: turtlebot_stage/Tutorials/indigo/Customizing the Stage Simulator (last edited 2016-01-10 07:44:44 by Yoonseok Pyo)