/** \file
 * This file is used for the doxygen documentation. 
 */


/** \mainpage Documentation of lpzrobots
\par Organization:
	University Leipzig \n
	Institute for Computer Science  \n
	Dept. Intelligent Systems \n
	Prof. Dr.  Ralf Der \n
        Research Group: Neuroinformatics und Robotic\n
	&nbsp; &nbsp; and \n
	Max-Planck Institute for Dynamics and Self-organzation\n
	Bernsteincenter for Computational Neuroscience Goettingen \n
	Bunsenstr.10, 37073 Goettingen, Germany\n
	Georg Martius\n
        Research Group: Self-organization in Adaptive Systems

\par People:
Georg Martius, Ralf Der, Frank Hesse, Frank Güttler, Jörn Hoffmann\n
Former Contributors: Marcel Kretschmann, Dominic Schneider, Claus Stadler,  
 
\section General

This is a collection of algorithms, simulations, and tools 
developed by the Robotics Group for Self-Organization of Control
(http://robot.informatik.uni-leipzig.de).\n
It consists of the following directories (click for details):
  - \ref selforg : controllers together with a small framework for using them,
	developed in the robotic group of Leipzig university
	yielding at self-organized behaviour for various kinds of machines. 
  - \ref ode_robots : physics simulator based on ODE 
	(Open Dynamics Engine, see http://www.ode.org). 
	This includes such as robots, obstacles, utils, stuff for visualization with OSG 
        (OpenSceneGraph, see http://www.openscenegraph.org) and so on.
  - \ref ga_tools : genetic algorithms framework that can be used to together with 
        ode_robots or for independent simulations
  - \ref guilogger : application that coordinates multiple gnuplot 
	windows and allows for an interactive display of data that is sent per pipe from another program 
  - \ref neuronviz : application that displays neural networks
  - \ref webots : directory with a webots simulation using the selforg lib
  - \ref opende : directory with a snapshot of the open dynamics engine (release 0.9)
		(please follow the link for installation hints)


\section Requirements
 
You need the following software and libraries installed (Tested on Linux x86 and MAC Leopard).
- ODE see http://www.ode.org which is now in the opende directory 
   (please follow the instrutions printed by the Makefile in lpzrobots)
- OpenSceneGraph http://www.openscenegraph.org (version >= 2.2.0) 
- (\a optional) Qt library from http://www.trolltech.com for guilogger (version > 4.0)
	- make sure you install the devel packages
	- make sure the correct version of qmake is in your path. If you have both qt3 and qt4 installed you have to take care of that. Use qmake --version to find out. On Debian and Ubuntu use the alternatives system http://www.debian-administration.org/articles/91
- (\a optional) Java JDK for neuronviz (version >= J2SE 1.5.0)

\subsection Linux
 For convinience we provide a binary package with ODE and OSG compatible with most 
  linux distributions, see next section
\subsection MAC
 We recommend to install the ODE and OSG via macports (http://www.macports.org)
 (after installation of macports type on a console 
 <tt>sudo port install osg OpenSceneGraph</tt>)

\section Inst Installation \& Startup

You have tree different ways to get the simulator to work. 
- A) Download a binary version of the simulator and the utilities. 
     This is the quick 'n' easy way which does not require root permissions, see \ref InstA
- B) Use an .rpm or .deb package if possible. This is easiest way but requires root
  permissions, see \ref InstB.
- C) Download the source tar ball and compile the simulator youself. 
  You have still the chance to take the precompiled extra libs. 
  If way A and B fails or you want to modify the simulator then this is the way to go, 
  see \ref InstC

\subsection InstA Way A: Binary installation
- Download the binary and maybe the extra-lib tar balls from 
  http://robot.informatik.uni-leipzig.de/software .
- Unpack the files (with <tt>tar -xvzf file.tgz</tt>)
- Install extra libs (ODE >= 0.8 and OSG > 2.2)
          - Check first whether you can get packages for your distribution. Make sure you get the development version (-devel or -dev).
          - debian/ubuntu name: libopenscenegraph-dev, libode0-dev
          - if there are none then install the extra libs from us as described below 
          or follow the appropriate part of \ref InstC.
\verbatim
cd lpzrobots-0.*-extra-lib-devel*
sudo ./install.sh
\endverbatim
The files are stored under <tt>/usr/local/</tt>.
- Install the simulator:
\verbatim
cd lpzrobots-0.*-binary-lib-devel*
make install
# or, if you want a system wide installation
sudo make install
\endverbatim
- Now you are done with the installation and you can try a sample simulation. 
  There are located in the <tt>ode_robots/simulations/</tt> 
  folder and are also
  copied to <tt>/usr/local/share/lpzrobots/</tt>.
  Please continue reading in section \ref RunExample.

\subsection InstB Way B: Package installation
- Download a package that fits your system from http://robot.informatik.uni-leipzig.de/software and use the
  package manager of your linux distribution. (Mostly automatically opens when downloading the package)
- Just in case for rpm-based system (Redhat,SuSe):
\verbatim
su
rpm -i lpzrobots-0.X...rpm
\endverbatim
- On Debian-based systems (e.g. also Ubuntu):
\verbatim
sudo dpkg -i lpzrobots-0.X...deb
\endverbatim
- Now you can copy the sample simulations from
  <tt>/usr/local/share/lpzrobots/</tt> to your home directory and 
  continue reading in section \ref RunExample.


\subsection InstC Way C: Installation from source
- Download source tar ball from 
  http://robot.informatik.uni-leipzig.de/software .
- Unpack file.
- Change into <tt> lpzrobots </tt> directory
- Call <tt> make </tt> to get a help display and continue with
  <tt> make prepare</tt>, which will do the following:
	- it creates a configuration makefile (Makefile.conf) with your interaction
	- it compiles \ref neuronviz (not strictly necessary, only for displaying neuronal network online) 
	- it compiles \ref guilogger (not strictly necessary, only for displaying parameters online (recommended)) 
   	- Please note, that the make call will not fail if either of them failed to compile, 
 	  because they are optional.  
	  You can type <tt> make guilogger </tt> and <tt> make neuronviz </tt> to compile them separately.
	- it creates dependency files and creates links to header files, such that thay are found.
	- it prints some information how to install the ODE residing in the \ref opende directory.
- Now you have to install the extra libs namely ODE and OSG. 
	-  To install the ODE please follow the instructions printed by the makefile. If nothing is printed then the libode was found. In case it is not the correct version do the following:
\verbatim
cd opende 
sh autogen.sh
./configure --enable-release --enable-double-precision
make
sudo make install
\endverbatim
	- To install the OSG, please refere to their homepage: http://www.openscenegraph.org/ 
- After finishing the installation of ODE and OSG you can procede with the installtion of th simulator.
- Call in the directory <tt> lpzrobots/ </tt>
\verbatim
make libs
make install
# or, if you want a system wide installation
sudo make install
\endverbatim
This will compile the libaries and install the tools.
- Now you are done with the installation and you can try a sample simulation see next section.



\subsection RunExample Run example Simulations
- Simulations are located in <tt>ode_robots/simulations/</tt>,<tt>ode_robots/examples/</tt>, and <tt>selforg/simulations/</tt>. This folders you can find in the lpzrobots tar files or if installed on your system under <tt>/usr/local/share/lpzrobots</tt>. In the latter case copy the simulations to your home directory first.
- To start a simulation go into a simulation directory. 
- If you installed from source you have to call <tt>make</tt>.
- You can start the simulation by <tt>./start</tt>.
- For example when you want to start the template_sphererobot simulation type:
\verbatim
cd ode_robots/simulations/template_sphererobot
make # if installed from source
./start 
\endverbatim
- for optimisation you can also use <tt>make opt</tt> which produces and <tt>start_opt</tt>(might need a make clean before). This is very recommended to use after testing the code. 
- The following command line options are available 
  (type ./start -h for a full list of options): \n
\verbatim
Usage: ./start [-g [interval]] [-f [interval]] [-r seed] [-x WxH] [-fs]
                 [-pause] [-shadow N] [-noshadow] [-drawboundings] [-simtime [min]] [-threads N]
                 [-odethread] [-osgthread] [-savecfg]
        -g interval     use guilogger (default interval 1)
        -f interval     write logging file (default interval 5)
        -n interval     use neuronviz (default interval 10)
        -s "-disc|ampl|freq val"        use soundMan
        -r seed         random number seed
        -x WxH          * window size of width(W) x height(H) is used (default 640x480)
        -fs             fullscreen mode
        -pause          start in pause mode
        -nographics             start without any graphics
        -noshadow       disables shadows and shaders (same as -shadow 0)
        -shadow [0..5]]         * sets the type of the shadow to be used
                        0: no shadow, 1: ShadowVolume, 2: ShadowTextue, 3: ParallelSplitShadowMap
                        4: SoftShadowMap, 5: ShadowMap (default)
        -shadowsize size        * sets the size of the shadow texture (default 2048)
        -drawboundings  enables the drawing of the bounding shapes of the meshes
        -simtime min    limited simulation time in minutes
        -savecfg        safe the configuration file with the values given by the cmd line
        -threads N      number of threads to use (default is the number of processors)
        -odethread      * if given the ODE runs in its own thread. -> Sensors are delayed by 1
        -osgthread      * if given the OSG runs in its own thread (recommended)
        * this parameter can be set in the configuration file ~/.lpzrobots/ode_robots.cfg
\endverbatim
- Have a look at the console after starting the program, 
  there you will find some further information for the usage of the program.
- E. g. with Ctrl+C (on the terminal) you get a interactive console interface 
  which can be used to modify  parameters on the fly.
- For starting your own simulation see paragraph "How to Start Your Own Simulation" 
  in \ref ode_robots.
- For a well documented examples of a main.cpp of a simulation and a robot .cpp file click 
  the tab "Examples" at the top of this page.


\section Documentation

- This manual can be found at http://robot.informatik.uni-leipzig.de/software
- More informations on the used self-organization algorithm is available at  
  http://robot.informatik.uni-leipzig.de/research
- An ODE tutorial by Marcel Kretschmann can be found at 
  http://robot.informatik.uni-leipzig.de/students \n However, 
  the simulator builds a small layer on top of ODE so that you should better look at the
  existing robots to find out how it works.
  (Tar ball with pdf and example code also there available.) 
- The original ODE documentation can be found at http://www.ode.org/ode-docs.html 
- The OSG documentation can be found at http://www.openscenegraph.org/projects/osg/wiki/Support

*/
