Simulation Player
Version 1.6
by Patrick McNeill

The Simulation Player (or Player) is a program that uses OpenGL to replay 3D
simulations.  When replaying a simulation, the user can control in which 
direction playback occurs, the orientation of the terrain, the position of the
camera, and many other attributes.  The Player also allows the user to monitor
the positions of individual agents.  A listing of all the commands and their
purpose is printed when the Player is started.

Files:

Player - The actual simulation player
makecolors - Processes the terrain file and generates a color map file
t - The terrain file
tclrs - The color map file
uavpos - Log file generated by a simulation, used as input to Player
sightlines - Log file generated by the simulation, lists when and where to draw
	lines between objects

Required Libraries:

Player requires some form of OpenGL.  It has been tested with both OpenGL 1.0 on
an SGI Indy and Mesa 2.2 on Solaris and Linux.  Mesa can be obtained at:
iris.ssec.wisc.edu in the pub/Mesa directory.  After installing Mesa, either 
glaux.h needs to be linked to aux.h or the include line in the source file needs
to be changed (The first is recommended so it will still compile on SGI 
platforms using OpenGL).  To link the file, go to the directory where the 
Mesa include files were installed and type:

	ln -s glaux.h aux.h

This will create a "symbolic link" from aux.h to glaux.h -- in other words,
anything that tries to access aux.h will actually access glaux.h.  One 
warning -- if you are on an SGI, do not link the file because SGIs should 
already have OpenGL and linking aux.h may override the real one.

Installation:

Installation of the Player should be fairly simple.  Most of the work should be
in getting the required libraries set up (if they do not already exist).  Once 
the libraries are set up, only two things need to be done:

(1) Choose a glgcc that works for your system.  "glgcc" is a simple shell
script that compiles OpenGL programs.  It's easier than having to remember
which libraries are needed, plus it helps to keep the Makefile system 
independent.  Three glgcc files have been included (for Linux, Solaris, and 
Irix) that have been tested.  If none of these work, a new one may need to
be created.  After one has been selected, link it to glgcc.  The command should 
be:
	ln -s [glgcc file] glgcc

(2) Run 'make'.

Make will build the Player and makecolors.  It should now be ready to run.

File Formats:

The terrain file, t, is used to associate an elevation value with coordinates
on the terrain.  The first two lines of the file should contain the number of
rows and the number of columns.  After that, simply begin listing the 
elevations.  The ordering is fairly basic - each line of text represents one 
row on the terrain.  Some example files have been included in the 'ts' 
directory.  Here's a generic schema for a t file:

<Number of Rows>
<Number of Cols>
<Elevation 1,1> <Elevation 1,2> ... <Elevation 1, col>
<Elevation 2,1> <Elevation 2,2> ... <Elevation 2, col>
...
<Elevation row, 1> <Elevation row, 2> ... <Elevation row, col>


Related to the terrain files are the color map files.  This file lists the RGB
color values that are associated with each point on the terrain.  The format is
almost the same - the RGB values are listed one row per line, space delimited.
Valid values are in the range 0.0 to 1.0.  Some example files have been included
in the 'ts' directory.  Here is the generic schema:

<R 1, 1> <G 1, 1> <B 1, 1> ... <R 1, col> <G 1, col> <B 1, col>
<R 2, 1> <G 2, 1> <B 2, 1> ... <R 2, col> <G 1, col> <B 1, col>
...
<R row, 1> <G row, 1> <B row, 1> ... <R row, col> <G row, col> <B row, col>

The script file, uavpos, contains the information about where the objects are
located.  The first line should contain the number of objects in the simulation,
followed by the number of time steps on the second line.  After that, each line
should contain an entry for an object.  Each object entry contains eight fields,
the first is the objects id number, the next three are XYZ coordinates, and the
next are RGB color values.  The last item is for a class id.  It is preceded by
"cls" followed by the classid number (without a space).  I did it this way to 
make it easier for debugging -- my simulation wasn't logging enough entries, so 
it was useful (with grep and wc) to find which object was in error.  It is 
important that the outputting in each turn (for the objects) takes place in the 
same order.  If it does not, the probed object may change between turns.  The 
number of lines should be the number of turns times the number of objects.
Here is the generic schema:

<Number of Objects (p)>
<Number of Time Steps (q)>
<ID 1> <X 1 1> <Y 1 1> <Z 1 1> <R 1 1> <G 1 1> <B 1 1> cls<ClassID 1>
...
<ID p> <X p 1> <Y p 1> <Z p 1> <R p 1> <G p 1> <B p 1> cls<ClassID p>
<ID 1> <X 1 2> <Y 1 2> <Z 1 2> <R 1 2> <G 1 2> <B 1 2> cls<ClassID 1>
...
<ID p> <X p 2> <Y p 2> <Z p 2> <R p 2> <G p 2> <B p 2> cls<ClassID p>
...
...
<ID 1> <X 1 q> <Y 1 q> <Z 1 q> <R 1 q> <G 1 q> <B 1 q> cls<ClassID 1>
...
<ID p> <X p q> <Y p q> <Z p q> <R p q> <G p q> <B p q> cls<ClassID p>

The lines files, sightlines, contains information about when and where to draw
"sight lines," or lines to visually represent communications or object 
sightings.  The format is simply the number of sightings on the first line,
followed by a list where each line contains (in columns) the turn number to
display the line, two id numbers to identify the objects to draw the line
between, and finally an RGB value to display the line in.  All should be space
delimited.  If the simulation does not need lines, simply create the sightlines
file with only a '0' in it (to indicate no lines).  Here's the generic schema:

<Number of lines (l)>
<Object x1> <Object y1> <R 1> <G 1> <B 1>
...
<Object xl> <Object yl> <R l> <G l> <B l>
Note: x and y can be any object ID number (from the uavpos file)

Agent View:

Agent View is an experimental mode in the Player.  The purpose of Agent View is
to show what the agent would see at any point in the simulation.  The author
is still working on the implementation of this feature.  It can be enabled
by hitting the 'u' key while the simulation is being replayed.
