The Stage Simulator
Stage is part of the Player/Stage software package developed at the University of Southern California Robotics Research Lab and HRL Labs. Player is a device server that can be used to control robots just like Pyro. Stage is a multi-robot simulator that provides facilities for creating your own environments for experimenting with robots.
In this section, we will present the core features of Stage that you will need for building simulated worlds for your Pyro robot experiments. For more information on Player/Stage visit their web site. There is extensive documentation available for Stage. You can find it either at the Player/Stage web site, or look in the doc folder of your Player/Stage installation on your computer.
The Stage User Interface
The window below shows an example of a Stage simulated environment.
It contains several colored boxes as well as a pioneer-style robot.
In the Stage window, you can pan and zoom the world as well as manipulate entities by using your mouse. You can click your mouse buttons on the background or on the entities. The following table summarizes various mouse click bindings and actions:
Clicks on the background
|Left-click and drag||pans the window|
|Right-click and drag toward the center of the window||zooms in|
|Right-click and drag the mouse away from the center||zooms out|
Clicks on entities
|Left-click and drag||moves the entity|
|Right-click and drag||rotates the entity|
Additionally, when you move your mouse over an active entity, like a robot, you will also get a visualization of all the enabled sensors of the entity.
Every Stage world is made up of entities which can be active or passive. Passive entities are also called objects in Stage parlance. Active entities are also called devices. Objects, or passive entities, are things like models and bitmaps. Bitmaps are used to define fixed obstacles that can represent building floor plans, walls, boulders, etc. and are loaded from a PNM bitmap file. PNM is a portable any map file format. Models can be any size and can also be used to represent obstacles as well as robot enclosures. For example, if you create a large models and then place a robot inside it, the walls of the model will become the boundary for the robot. If you placed smaller models inside the larger model containing the robot, then those become blocks or obstacles.
The other kind of entity one can have in a Stage world are devices. For example, a robot is a device that can be positioned anywhere in the world. Other devices include things like a gripper, sonar, laser, ptz (pan-tilt-zoom camera), etc. Generally, these devices will be mounted on a robot device. Stage has the capability of defining composite devices. Thus you can define a robot that has a gripper and sonars, or another one that has sonars and a PTZ camera, etc.
By convention, you typically define a simulated robot for Stage worlds based on the actual robot that you have. You compose it to contain all the devices the robot carries. Then, you can create several different environments and include your robot device definition in it. For example, the Stage software includes a file named pioneer.inc that defines a typical pioneer-style robot with 16 sonars. This robot can be used in any Stage world.
Creating a World
Once we have defined a robot, we can concentrate on creating a world for it. Because Stage is currently undergoing a major upgrade, there is still not much documentation on how to create worlds. However, we can demonstrate how the simple world shown above was created.
Creating a world in Stage involves creating two files. The first is the configuration file and always ends with a .cfg extension. For example, the file tutorial.cfg is shown below.
driver ( name "stage" provides ["7000:simulation:0"] plugin "libstageplugin" worldfile "tutorial.world" ) driver ( name "stage" provides ["position:0" "sonar:0"] model "Pioneer" )
Next you must define the world file, which has a .world extension. This defines all the entities that will appear in the world. Each world file typically has the following:
A specification of units. A specification of the Stage GUI window and the coordinate system. A list of all passive entities and their attributes. A list of all robots and their attributes.
The tutorial world shown above is 5 meters wide and 5 meters high. It contains a blue rectangle, two green rectangles, and a red pioneer robot.
All commands that specify entities in Stage worlds have the following syntax:
<entity_name> ( <attribute1> <value1> ... <attributeN> <valueN>)
Where <entity_name> is the name of the entity, and that is followed by a list of attribute value pairs enclosed by parenthesis. You can format the command on a single line or multiple lines. Attributes for entities depend on the kind of entity. A rectangle (called a model), may have a color, a position and an orientation.
Specifying Units and Resolution
The above command is the proper syntax for specifying units for length. We have set it to meters. This is also the default in case you do not specify any units. However, we recommend you do this. This specification should also be consistent with your robot definition, so you should be careful and fix this once and for all. You can use meters (m), centimeters (cm), or millimeters (mm) for units of length and degrees or radians for specifying angles.
The GUI Window and the Coordinate System
You have to specify the size of the GUI window in pixels as well as the center point and scale.
window ( size [540.000 580.000] center [0.000 0.000] scale 0.01 # 1 pixel = 0.01 meters )
Since our world will be 5x5 meters, at 0.01 meters/pixel, we will need at least 500 pixels for the GUI window. We generally pad this so that the window borders are also included. The center of the window will be considered the origin.
Specifying Passive Entities
In the world that we are building there are several objects. First there is the outer box which encloses the environment. This can be defined as follows.
model ( size [5.0 5.0] color "white" pose [0.000 0.000 0.000] )
In the above definition, the box is 5x5 meters, thus defining the world boundary. It is colored white, and its position is defined by three numbers which specify the x and y coordinates of the center of the box and its orientation (in degrees). Thus the box is centered at the point (0.0, 0.0 ) and its orientation is 0 (0 degrees lies along the positive x-axis).
Next there are a series of inner boxes which represent obstacles. They can be defined as follows.
model ( size [1.0 1.0] color "blue" pose [-2.000 2.000 0.000] ) model ( size [0.1 2.5] color "green" pose [0.000 -1.250 0.000] ) model ( size [0.1 1.4] color "green" pose [0.650 0.000 90.000] )
Specifying a robot
We will use the definition of a pioneer robot:
pioneer2dx ( color "red" name "Pioneer" port 6665 pose [-2.000 0.000 90.000] )
The port attribute is very important. This is the port number that the driver program will use to connect to the robot and control it.
Copy the following files from $PYROBOT/plugins/worlds/Stage/ to your home directory:
tutorial.cfg tutorial.world pioneer.inc
Modify the world above so that the robot is pointing west when the world is loaded into Stage. In order to get Pyro to load your version of the world, be sure to press the "Home" button when the list of worlds appears.
Try modifying some other attributes of the robot (like its color). Then, create a red diamond-shaped box (a box oriented 45 degrees) as an obstacle in the environment. Move your mouse on the robot and notice its sensors. Move the robot near the obstacle and try the same thing. How would you create walls in this environment?
Now would be a good time to look at the other world files provided there. This should give you a good idea of some other features of Stage. Remember to browse the Stage Manual for more information on Stage.