/* Stage plugin documentation file - parsed by Doxygen for the user
 * manual 
 * $Id: help.txt,v 1.9 2005/02/13 07:37:42 rtv Exp $
*/

/**
@mainpage Stage - a robot simulator plugin for Player

Stage is a robot simulator that works with the Player robot server. It
provides a virtual world populated by mobile robots and sensors, along
with various objects for the robots to sense and manipulate. 

<h2>Design</h2>

<p>Stage robots and sensors work like any other Player device: users
write robot controllers and sensor algorithms as `clients' to the
Player `server'. Typically, clients cannot tell the difference between
the real robot devices and their simulated Stage equivalents (unless
they try very hard). We have found that robot controllers developed as
Player clients controlling Stage robots will work with little or no
modification with the real robots and vice versa [1]. With a little
care, the same binary program can often control Stage robots and real
robots without even being recompiled [2]. Thus the Player/Stage system
allows rapid prototyping of controllers destined for real
robots. Stage can also be very useful by simulating populations of
realistic robot devices you don't happen to own [3].

<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. These were
tricky to use with previous versions of Stage, but this release makes
it simple to take full advantage of Player.

<h2>Models</h2>

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

<i>Note:
Some models from previous versions may not yet be available in this
release (e.g. gripper & puck), but we're working on them. Let us know which ones you need.
</i>

[@ref refs]

<hr>
<small>
Richard Vaughan <tt>(vaughan@sfu.ca)</tt> \$Id: help.txt,v 1.9 2005/02/13 07:37:42 rtv Exp $
</small>

*/

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

*/


/** @page faq Frequently Asked Questions (FAQ)

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

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

*/


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

*/

/**
@page install Installation

<b>Important: Stage is an extension to Player; Player must be properly
installed before you can 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>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>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>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>Remember: 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.

*/


/**
@page release Release Notes

<h2>Version 1.6.1</h2>

This is a bug-fix release that replaces 1.6.0. 

- Fixes several GUI bugs, including the [View/Fill Polygons] menu item.

- Some code clean-up and thread-safety fixes

<h2>Version 1.6.0</h2>

This release of Stage is the first after a major rewrite. There are
bound to be bugs and teething troubles, but the <a
href=http://www.cs.sfu.ca/research/groups/autonomy>Autonomy Lab</a>
has been using this code for serious work for a few months now and we
think it's useful and usable.

<h3>Significant changes visible to the user</h3>

<ol>

<li>Stage is now a Player plugin, instead of an executable. The key
benefit of this is that <b>all Player drivers are now available for
use directly with Stage</b>, including sophisticated drivers like
AMCL, without needing passthrough drivers.

<li>Stage depends on Player 1.6 or newer.

<li>Worldfile syntax has a changed, so you 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.

<li>Any object can now have its shape specified by a bitmap file

<li>Several bitmap file formats are supported, using a third-party
library. Load maps and robot bodies from JPG, PNG, etc. No more PNM
troubles.

<li>Worlds can now be very large (thousands of meters square).

<li>Several models are missing from this release - notably the gripper
and puck. These will be available soon. Meanwhile, enjoy the full
power of Player with the basic laser, sonar, position, fiducial and
blobfinder models.

<li>Stage no longer depends on libRTK.

<li>Some models from previous versions may not yet be available in
this release (e.g. gripper & puck), but we're working on them. Let us
know which ones you need.

</ol>

<h3>Significant changes under the hood</h3>

<ol>

<li>The Stage simulation engine is now a library rather than an
application. The library can be used to write custom robot
simulations. This is very useful if you need to do synchronous control
of robots (e.g for perfectly repeatable experiments), or dynamically
create and destroy robots or other objects. You can't (yet) do this
though Player. Refer to the <a
href=http://playerstage.sf.net/doc/stage_reference>libstage reference
manual</a> for the API and developer docs.</a>.

<li>Stage is now mostly written in C. A simple object-oriented system
allows one level of inheritance for writing polymorphic model code.

<li>The underlying occupancy grid model has changed from a simple
fixed-size array to a sparse array of (almost) unlimited size
(implemented with a hash table). To compensate for the performance hit
of raytracing in the hash table, a three-level multiple-resolution
approach is used. Raytracing is now usually <i>much</i> faster than in
Stage-1.3. To get an idea how this works, select the
View/Debug/Raytrace menu item while a laser or ranger is producing
data.

<li>Most home-rolled data structures have been replaced by glib
versions.

</ol>

*/

/**
@page credits Credits

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>
</ul>

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

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>


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>

*/


/** 
@page dev_simulation Simulation Device

The simulation device...

*/


/** 
@page devices Devices

Devices..

*/

/** 
@page models Models

Introduction to models...

*/

