/* Stage plugin documentation file - parsed by Doxygen for the user * manual * $Id: stage.txt,v 1.14 2006/02/28 05:35:59 rtv Exp $ */ /** @mainpage The Stage Robot Simulator

Copyright Richard Vaughan and contributors 1998-2006 and beyond.

Part of the Player/Stage Project [http://playerstage.sourceforge.net] \section License This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. A copy of the license is included with the sourcecode in the file 'COPYING". Copying and redistribution is permitted only under the terms of the license. */ /** @defgroup stage Stage User Guide Stage is a provides a virtual world populated by mobile robots and sensors, along with various objects for the robots to sense and manipulate. It is usually used to provide simulated devices to the Player robot server, but it can also be used as a stand-alone robot simulation library. \section Models

Stage provides several sensor and actuator models, including sonar or infrared rangers, scanning laser rangefinder, color-blob tracking, fiducial tracking and mobile robot bases with odometric or global localization. Note: Some models from previous versions may not yet be available in this release (e.g. bumpers), but we're working on them. Let us know which ones you need. \section Design

Stage was designed with multi-agent systems in mind, so it provides fairly simple, computationally cheap models of lots of devices rather than attempting to emulate any device with great fidelity. This design is intended to be useful compromise between conventional high-fidelity robot simulations, the minimal simulations described by Jakobi [4], and the grid-world simulations common in artificial life research [5]. We intend Stage to be just realistic enough to enable users to move controllers between Stage robots and real robots, while still being fast enough to simulate large populations. We also intend Stage to be comprehensible to undergraduate students, yet sophisticated enough for professional reseachers.

Player also contains several useful 'virtual devices'; including some sensor pre-processing or sensor-integration algorithms that help you to rapidly build powerful robot controllers. These are easy to use with Stage. [@ref refs] \section Authors Stage was written by:

Many patches and bug reports have been contributed by users around the world. Stage is part of the Player/Stage Project, a community effort to develop Free Software tools for robotics research. Stage is free to use, modify and redistribute under the terms of the GNU General Public License. \section Citations If you use Stage in your work, we'd appreciate a citation. At the time of writing, the most suitable reference is:

Please help us keep track of what's being used out there by correctly naming the Player/Stage components you use. Player used on its own is called "Player". Player and Stage used together are referred to as "the Player/Stage system" or just "Player/Stage". When libstage is used without Player, it's just called "Stage". When Player is used with its 3D ODE-based simulation backend, Gazebo, it's called Player/Gazebo. Gazebo without Player is just "Gazebo". All this software is part of the "Player/Stage Project". \section Support

Funding for Stage has been provided in part by:

\section Names The names "Player" and "Stage" were inspired by the lines: @verbatim "All the world's a stage" "And all the men and women merely players" @endverbatim

from "As You Like It" by William Shakespeare. */ /** \page release Release Notes \section v2 Version 2.0.0 This is a major new release of Stage, and is intended to replace all previous versions. It requires Player-2.0.0 or later. Please report bugs to the tracker and let us know what you do with Stage. Richard Vaughan (rtv)
vaughan@sfu.ca
2006.2.26 \subsection features New Features Significant user-level changes include: - Stage is now implemented as the C library libstage. Using libstage, your programs can include a sophisticated robot simulator with a few lines of code. The Player plugin libstageplugin is a wrapper for libstage that provides simulation services to Player. Player with libstageplugin is the Player/Stage system. - Player clients can draw directly in the Stage window using the graphics2d interface. libstage programs can use the internal user graphics API. - Configurable odometry error in position model - Gripper model that can pick up anything. Any object can be made grippable/pushable by setting the the gripper_return property. - Pan-tilt-zoom (PTZ) model. - More and improved visualizations, including models leaving trails over time - Any object can now have its shape specified by a bitmap file (JPG, PNG, etc.). - Worldfile syntax has changed slightly, so you may need to edit your existing worlds to get them to work. Look at the example worlds in (stage src)/worlds to get the idea. - Worlds can be very large (thousands of meters square). */ /** @ingroup stage @defgroup help Getting Help If you're having problems and you can't find what you need in this manual, there are several places to find help. First, please check the online documentation page to make sure you have the latest documentation. In particular, check the latest online latest FAQ page. Next, you should search the playerstage_users mailing list archive to see if your questions have already been answered. Next, you should probably spend a few minutes with Google. This often works well, as it picks up P/S conversations from all over the place. If you still need help, you can send email to the mailing list playerstage_users@lists.sourceforge.net and a user or developer may reply to you. Remember that these mails go to hundreds of people, so please be polite and give as much information as you can in your email. */ /** @ingroup stage @defgroup faq FAQ: Frequently Asked Questions There are no questions about the 2.0 release yet. If you have a question, follow the advice here.

  1. [none]
*/ /** @ingroup stage @defgroup refs References [1] Brian Gerkey, Richard Vaughan, Kasper Stoy, Andrew Howard, Gaurav Sukhatme, Maja Mataric (2001) "Most Valuable Player: A Robot Device Server for Distributed Control", Proc. IEEE Int. Conf. Intelligent Robotic Systems, Maui, Hawaii. (IROS'01) [2] Richard Vaughan, Brian Gerkey, Andrew Howard (2003) "On device abstractions for portable, resuable robot code", IEEE/RSJ International Conference on Intelligent Robot Systems, Las Vegas, Nevada, USA. (IROS2003) [3] Brian Gerkey, Richard Vaughan, Andrew Howard (2003) "The Player/Stage Project: Tools for Multi-Robot and Distributed Sensor Systems", 11th International Conference on Advanced Robotics, Coimbra, Portugal (ICAR'03). [4] Nick Jakobi (1997) "Evolutionary Robotics and the Radical Envelope of Noise Hypothesis", Adaptive Behavior Volume 6, Issue 2. pp.325 - 368 . [5] Stuart Wilson (1985) "Knowledge Growth in an Artificial Animal", Proceedings of the First International Conference on Genetic Agorithms and Their Applications. Hillsdale, New Jersey. pp.16-23. */ /** @ingroup stage @defgroup install Installation Important: If you plan to use Stage with Player, Player must be properly installed before you install Stage.

Quick start

Install Player first, then Stage, using the standard GNU autotools build system: download and extract the tarballs, then ./configure ; make install.

Standard install procedure

To install Stage in the default location, follow these steps:

  1. If you plan to use Player with Stage, make sure Player is installed and working. See the Player documentation for instructions.
  2. Download the latest Stage source tarball (stage-src-\.tgz) from http://playerstage.sf.net
  3. Uncompress and expand the tarball:
    $ tar xzvf stage-\.tgz
  4. `cd' into Stage's source directory:
    $ cd stage-\
  5. To configure Stage with default settings:
    $ ./configure
  6. Compile Stage:
    $ make
  7. Test to see if Stage works by running the stest program:
    src/stest worlds/simple.world robot1
    If you see a robot running around, your build was successful. If not, you need to debug. See the website and user groups for debugging help.
  8. Install Stage. By default, Stage will be installed in /usr/local so you need to become root for this step. Remember to return to your normal user ID afterwards.
    $ make install

Using Player/Stage

Unlike some earlier versions, this version of Stage is not a program that you run standalone, and there is no binary called "Stage". Instead, Stage provides a Player extension, or "plugin", which adds simulated robots to Player. To use the Player/Stage system, you run the "player" program with appropriate configuration files. See the documentation [@ref player] for details and examples. You can also create your own custom robot simulations independently of Player by using the libstage C library directly in your code. See the documentation [@ref libstage] for details.

Customized installations

Stage follows the standard GNU autotools conventions for build and install options. To see a list of all the available configuration options, do this:

./configure --help

The most important option is --prefix, used to change the installation directory from the default (which varies from system to system, but is usually /usr/local). In general, Stage should get the same prefix you used to install Player. Prefixes must be absolute paths, i.e. a complete path starting with a '/'.

For example, you might want to install Stage your home directory because you don't have root access:

$./configure --prefix=/home/harrison/PS

These instructions assume that Player was configured with the same prefix. The command line to do this is probably the same, but you should check the Player instructions just in case. */