************************************************************************
* Project:   AERO
* Filename:  README
* Date:      Fri Aug 30 17:38:14 1996
* Author:    Hartmut, Andreas
*
* Description:
* ------------
* This file gives an overview of the xaero program
************************************************************************


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++          AERO: Animations Editor for Realistic Object motion          ++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


AERO is a tool for editing ans simulating scenes with rigid body
systems. You can use the built-in 4-view editor to create a virtual
scene consisting of spheres, cuboids, cylinders, planes and fix
points. You can link these objects with rods, springs, dampers and
bolt joints and you can connect forces to the objects. Then you can
begin the simulation and everything starts moving according to the
laws of physics (gravitation, friction, collisions). The simulation
can be viewed as animated wire frame graphics. In addition you can
use the POV-Ray raytracing program to render photo-realistic animation
sequences.

At the moment, AERO exists as an X-Windows program called xaero. It
runs on most Unix compatible machines including Linux PCs, SUN-, DEC-,
SGI-, HP-, and IBM-Workstations.

xaero was designed and implemented by Hartmut Keller (display),
Andreas Ziegler (editor), Horst Stolz (simulation) and Thomas Braeunl
(team leader). 


HOW TO OBTAIN AERO:
-------------------

The newest version of AERO can be obtained via anonymous ftp from 

   ftp.informatik.uni-stuttgart.de (currently 129.69.211.2)

in the directory /pub/AERO. There are also some documents about the
simulation algorithms and some sample scenes as GIF images, MPEG
sequences or Quicktime movies.

You can also contact us and our server via WWW:

   http://www.informatik.uni-stuttgart.de/ipvr/bv/aero/


Bugs, suggestions or problems can be reported via email to

   keller@informatik.uni-stuttgart.de  (Hartmut Keller)      or
   braunl@informatik.uni-stuttgart.de  (Thomas Braeunl)      or
   stolz@isa.de	                       (Horst Stolz)



REQUIREMENTS:
-------------

For compilation you need to have:

    - X-Windows libraries (best: X11R5 or newer)
    - Athena-Widget-Set (supplied with X-Windows)
    - FWF-library (Free Widget Foundation)
    - ANSI-C Compiler (e.g. gcc 2.3.3 or newer)

To see how to build and install xaero please refer to the file
INSTALL. 


USEFUL TOOLS:
-------------

To render the written raytracer files, you should have POV-Ray V2.x or
newer as it shows the best results. But an older version also works.
See the file README.raytracer for further information about using the
raytracer with AERO and how to get the best results. There are also
some Unix shell scripts supplied with AERO which allow the automatic
generation of images out of the generated raytracer files, even on
several machines in parallel (see below).

To further process these generated images you may want to have the
PBM+ toolkit or some MPEG software. For example the filter "tgatoppm"
of PBM+ serves well to convert the Targa (.tga) files created by
POV-Ray to the Portable Pixmap format (.ppm) which can be read by most
image processing software. There is also a tool called "animate" in
the IMAGICK package included with X11 which can be used to view a set
of images without converting them to a video sequence first. This
package (IMAGICK = ImageMagick) also includes a rather sophisticated
image display processor. There is also a freeware project called GIMP
where they are developing a modular image drawing, processing and
converting tool (http://www.xcf.berkeley.edu/~gimp/).


SCRIPTS:
--------

This release includes four script files in the "scripts" directory to
convert the raytracer output of xaero to portable images. To save disk
space it can compress the images with GNU-Zip (gzip) or Unix compress. 
Some image viewers (e.g. xv, ImageMagicks's display) can display
these compressed pictures directly. There are two versions of the
scripts: the older version creates .ppm.Z files and needs tgatoppm of
PBM+ to work. The newer version generates .tga.gz files and needs at
least xv 3.10 to view them.

Short description of the script-files:

raystart - Starts the transformation of all *.pov (raytracer source) files
	   in a specific directory into *.ppm.Z (compressed pictures).
           It is possible to specify more than one computer. The
           transformation process (that means the raymany script!) is
           invoked on every remote machine by a remote shell call.
           
raymany  - Transforms on one machine (!) all *.pov files via "povray" and 
 	   "tgatoppm" into *.ppm.Z pictures.

rayclear - clean up after an unsuccessful transformation process, e.g
           there are .tga-files left over. Also kills all scripts
           started on remote machines from the "raystart" command.

raystat  - shows statistic information of the progress of the transformation
           process.

All four scripts have a help-text, reachable via the -h option. Read those
for further explanations.

Now here is an example session to convert the directory video/pendel
full of *.pov files (generated by xaero) to rendered image files. 

To start the transformation process on four remote machines with the same
directory layout type the following in you shell:

    salvador:[~] raystart -name video/pendel -width 320 -height 160 -zippov \
	                  -computers compname1 compname2 compname3 compname4

    salvador:[~] raystat -name video/pendel -time
	            
If the transformation is complete type the following to remove all obsolete
files used by "raystart":

    salvador:[~] rayclear -cleanup




USING THE SIMULATOR KERNEL FOR OWN APPLICATIONS:
------------------------------------------------

Here are some hints for if you like to include the simulation part of
AERO in your own applications. 

The simulator is designed as a kind of library. This simulator
computes the world from a single timepoint (state) to a following
timepoint. Due to the history of AERO, the identifiers and names are
still in German (sorry). The German name is "FolgeSchrittBerechnung",
so the library generated by the Makefile is named "libfsb.a". In this
library you find all necessary routines.

Here is a table of all modules included in the FSB library and their
aim:

ausgabe				- simple text output
beruehrung			- compute the forces of touching objects
bewegungsgleichungen		- equations of motion
fehler				- error handling 
folgeschrittberechnung		- main module with the simulator
gleichungsloeser		- linear equation solver
integration			- integrator module
io				- read/write state, configuration and materials
koerper				- body initialization/definition 
kollision			- collision detection routines
kollisionsbehandlung		- collision response routines
konfig				- configuration of the simulator
kraft				- routines to add external forces to bodies
materialien			- material definitions
rev				- revision
stoss				- routines for solving the impact of bodies
vektor				- useful macros and routines for
				  vector operations

Look at the headerfiles (.h) for a specification of the single
routines.

There are also two "simple" example programs which use the FSB library
in this way. Look at the files example1.c and example2.c in the
directory fsb-examples. Type make in this directory to compile these
examples. 

The two examples do the same: They show the horizontal and vertical
position of a sphere which is falling to the ground plus drifting to the
right due to a force. example 2 uses the ReadZustand(..) function
to load the world from the file "bsp.state".

Now here's a prototype for the usage of the main simulation routines
defined in folgeschrittberechnung.h:
---------------------------------------------------------------------------
#include <folgeschrittberechnung.h>

simulate_your_world()
{
	TZustand mystate;

	/* generate a correct initialized state and material table!
         * see koerper.h, materials.h (or io.c as an example)!
         * Note: use KoeIniMech(body, materialtable) for initializing a body!
         */

	InitFBB(mystate);

        ErfrageFBB(myconfig);
	/* change configuration to your demands 
	 */
	KonfigFBB(mystate);

	/* State at starttime (0.0 normally)
	 */	
	FolgeBildBerechnung(mystate, 0.1);

	while (forever) {
	   /* state after 0.1 seconds.
	    * print/display/change the state at your own!
	    */
	
	    /* for speedup you can call this routine
	     * (don`t use after a change of the state!)
             */
	    UngeaendertFBB(mystate);	

	    /* compute next state
	     */		
	    FolgeBildBerechnung(mystate, 0.1);
	}

	EndFBB(mystate);
}	

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


