/* Stage plugin documentation file - parsed by Doxygen for the user
 * manual 
 * $Id: stage.txt,v 1.18 2006/03/29 05:14:35 rtv Exp $
*/

/**
@mainpage The Stage Robot Simulator

<p>Copyright Richard Vaughan and contributors 1998-2006 and beyond.
<p>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 robot simulator. It 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

<p>Stage provides several sensor and actuator models, including sonar
or infrared rangers, scanning laser rangefinder, color-blob tracking,
fiducial tracking, bumpers, grippers and mobile robot bases with
odometric or global localization.

\section Design

<p>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.
  
<p>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:

<ul>
<li>Richard Vaughan <tt>(vaughan@sfu.ca)</tt>
<li>Andrew Howard  <tt>(ahoward@robotics.usc.edu)</tt>
<li>Brian Gerkey <tt>(gerkey@robotics.stanford.edu)</tt>
<li>Reed Hedges <tt>(hedges@mobilerobots.com)</tt>
</ul>

Many patches and bug reports have been contributed by users around the
world.

Stage is part of the <a
href="http://playerstage.sourceforge.net">Player/Stage Project</a>, a
community effort to develop Free Software tools for robotics
research. Stage is free to use, modify and redistribute under the
terms of the <a href=http://www.gnu.org/licenses/licenses.html> GNU
General Public License</a>.

\section Citations

If you use Stage in your work, we'd appreciate a citation. At the time of writing, the most suitable reference is:

<ul>
<li>
Brian Gerkey, Richard T. Vaughan and Andrew Howard. "The
Player/Stage Project: Tools for Multi-Robot and Distributed Sensor
Systems"
Proceedings of the 11th International Conference on Advanced Robotics,
pages 317-323,
Coimbra, Portugal, June 2003 <A HREF="http://www.isr.uc.pt/icar03/">(ICAR'03)</A>.
<br>
<A HREF="http://robotics.stanford.edu/~gerkey/research/final_papers/icar03-player.ps.gz">[gzipped
postscript]</A> <A HREF="http://robotics.stanford.edu/~gerkey/research/final_papers/icar03-player.pdf">[pdf]</A>  
</ul>

<p>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

<p> Funding for Stage has been provided in part by:

<ul>
 <li>NSERC (Canada)
 <li>Simon Fraser University (Canada)
 <li>DARPA (USA)
 <li>NASA (USA)
 <li>NSF (USA)
</ul>

\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

<p>from <i>"As You Like It"</i> by William Shakespeare.

*/


/** 
\page release Release Notes

\section v201 Version 2.0.1

This is mainly a bugfix and performance-enhancement release. This
release requires Player-2.0.1, released simultaneously.

The only major new feature is the addition of support for Player's
speech interface: speech bubbles show the text being "spoken" by each
robot. The text is rendered using Pango, so non-Roman alphabets are
supported.

Richard Vaughan (rtv) vaughan@sfu.ca 2006.3.24


\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:

 - <b>Stage</b> is now implemented as the C library
 <b>libstage</b>. Using libstage, your programs can include a
 sophisticated robot simulator with a few lines of code. The
 <b>Player</b> plugin <b>libstageplugin</b> is a wrapper for libstage
 that provides simulation services to Player. Player with
 libstageplugin is the <b>Player/Stage</b>
 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 <tt>(stage
src)/worlds</tt> 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 <a
href=http://playerstage.sourceforge.net/doc/doc.html>online
documentation page</a> to make sure you have the latest
documentation. In particular, check the <a
href=http://playerstage.sourceforge.net/doc/stage_user/faq.html>latest
online latest FAQ page</a>.

Next, you should search <a
href=http://sourceforge.net/mailarchive/forum.php?forum_id=8201>the
playerstage_users mailing list archive</a> to
see if your questions have already been answered.

Next, you should probably spend a few minutes with <a
href=http://www.google.com>Google</a>. 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. <b>Remember that these mails go to hundreds of people</b>, so
please be polite and give as much information as you can in your
email.

*/


/**
@ingroup stage 
@defgroup faq FAQ: Frequently Asked Questions

<b>There are no questions about the 2.0 release yet. If you have a question, <a href="group__help.html">follow the advice here</a></b>.

<ol>
<li> [none]
</ol>

*/


/**
@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

<b>Important: If you plan to use Stage with Player, Player must be
properly installed before you install Stage.</b>

<h2>Quick start</h2>

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

<h2>Standard install procedure</h2>

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

<ol>

<li>If you plan to use Player with Stage, make sure Player is
 installed and working. See the Player documentation for instructions.

<li>Download the latest Stage source tarball (stage-src-\<version\>.tgz)
from <a href=http:playerstage.sf.net>http://playerstage.sf.net</a>

<li>Uncompress and expand the tarball: <br>
    <tt>$ tar xzvf stage-\<version\>.tgz</tt>

<li>`cd' into Stage's source directory:<br>
     <tt>$ cd stage-\<version\></tt>
 
<li>To configure Stage with default settings:<br>
<tt>$ ./configure</tt><br>

<li>Compile Stage:<br>
<tt>$ make</tt>

<li>Test to see if Stage works by running the stest program:<br>
<tt>src/stest worlds/simple.world robot1</tt><br>
If you see a robot running around, your build was successful. If not,
you need to debug. See the <a href="http://playerstage.sf.net">website
and user groups for debugging help</a>.

<li>Install Stage. By default, Stage will be installed in
<tt>/usr/local</tt> so you need to become root for this step. Remember
to return to your normal user ID afterwards. <br> 
<tt>$ make install</tt>

</ol>

<h2>Using Player/Stage</h2>

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.

<h2>Customized installations</h2>

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

<p><tt>./configure --help</tt>

<p>The most important option is <tt>--prefix</tt>, used
to change the installation directory from the default (which varies
from system to system, but is usually <tt>/usr/local</tt>). 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 '/'.

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

<p><tt>$./configure --prefix=/home/harrison/PS</tt>

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

*/


/** @ingroup stage
@defgroup writingmodels Writing Stage models

TODO: steps required to add a new Stage model

*/

