/** \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:
Ralf Der, Georg Martius, Frank Hesse, Frank Güttler\n
Former Contributors: Marcel Kretschmann, Dominic Schneider, Claus Stadler,  
 
\section General

This is a collection of algorithms, simulations, and tools 
developed by the robot group of the University Leipzig \n
(http://robot.informatik.uni-leipzig.de).
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 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 machines).
- 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 qmake version 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)

For convinience we provide a binary package with ODE and OSG compatible with most 
 linux distributions, see next section


\section Inst Installation \& Startup

You have two different ways to get the simulator to work. 
- A) download a precompiled version of the simulator libaries and the utilities. 
	This is the quick and easy way which you can try first, see \ref InstA
- B) download the source tar ball and compile the simulator youself. 
	You have still the chance to take the precompiled extra libs. 
	If way A failes or you want to modify the simulator then this is the way to go, 
	see \ref InstB

\subsection InstA Way A: Binary installation
- Download the binary and 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:
\verbatim
cd lpzrobots-0.*-extra-lib-devel*
./install.sh
# or, if you want a system wide installation
sudo ./install.sh
\endverbatim
- Install the simulator:
\verbatim
cd lpzrobots-0.*-binary-lib-devel*
make install
# or, if you want a system wide installation
sudo make install
\endverbatim
- You will be asked for the installation prefix and the installation type. The latter you have to anwser with \b u like user.
- Now you are done with the installation and you can try a sample simulation from <tt>ode_robots/simulations/</tt>. Please continue reading in section \ref RunExample.


\subsection InstB Way B: 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) 
   	- Please note, that the make call will not fail if either of them failed to make, 
 	  because they are optional.  
	  You can type <tt> make guilogger </tt> and <tt> make neuronviz </tt> to compile them seperately.
	- it creates dependency files and creates links to header files, that they can be 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 simulationsee next section.



\subsection RunExample Run example Simulations
- Simulations are located in <tt>ode_robots/simulations/?</tt> and <tt>selforg/simulations/?</tt>
- 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_onerobot simulation type:
\verbatim
cd ode_robots/simulations/template_onerobot
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)
- 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
- The ODE tutorial of Marcel Kretschmann can be found at 
  http://robot.informatik.uni-leipzig.de/students \n
  (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/osgwiki/pmwiki.php/Documentation/Documentation

*/
