Surface Animator
Written by Paul Bourke
August 2002
Introduction
"surfanim" is an OpenGL application that interactively
displays time varying height fields distributed on a regular
grid, in particular, it does
so using either frame sequential or dual display stereo3D.
It allows the user to view the surface as it evolves in
time from any view position, change the drawing modes, and
adjust many other characteristics of the presentation.
By default
the height will be mapped to some colour ramp but support
is also provided for colour derived from an additional
scalar value (see file format -f2 and -f12) or provided
directly (see file format -f1 and -f11).
Data files
"surfanim" reads a sequence of data files that describe the surface at
each time step (-b) or a single file containing all the time steps (-bs).
The surface is assumed to be a function, that is,
one-to-one mapping or many-to-one. The plane is taken to be the x-y
plane and the height the z axis.
When the time steps are each in a separate file (-b)
the file names must contain a number ranging from 0 upwards
(this can be relaxed with the -t command line option, see later).
The exact
naming scheme for the file is presented to "surfanim" with the -b command
line option which gives a C style printf() format for the files.
- Example 1
If the time steps were stored in files called data0.dat, data1.dat,....
data100.dat then the command line option would be -b data%d.dat.
- Example 2
If the data files were called fcn0000.txt, fcn0000.txt, fcn0000.txt,....
fcn1120.txt then the option would be -b fcn%04d.txt.
There are two required command line arguments, the first is -b or -bs as
discussed above, the other is -n which indicates the size of the surface
grid (the data files don't contain the grid dimensions).
So -n 100 40 is a grid with 100 elements along the x axis and 40
samples along the y axis. In this case each file is expected to have
4000 values, one for each grid node.
The files are stored with the x axis varying most rapidly, so the
loop to write the files might be something line this.
open the file for current time step
for (y=0;y<40;y++) {
for (x=0;x<100;x++) {
write element data[x][y]
}
}
close file
File formats
There are six file formats currently supported, they are specified by the
command line argument -f0, -f1, -f2 and -f10, -f11, -f12.
The first three are ascii files and the last three are their binary
equivalents. The ascii data files are convenient for human inspection
while the binary formats can be read significantly faster by computer.
In each case the grid is assumed
to be square and so the x and y coordinates of each point need not be
supplied (See the -x and -y command line options for specifying non
square grid). By default the grid spacing is 1 in each direction and
the height field is assumed to be in the same coordinate system (see
the -z options for height scaling).
-f0
The file consists of simply a list of z values, one for each node of
the surface. The colour of the surface is mapped to the height range.
Each value can be separated by any white space character, eg: space,
return, tab, etc.
-f10
This is the binary equivalent to -f0, each height is stored as a
4 byte IEEE style float, INTEL cpu byte ordering.
-f1
Each node of the surface is represented by a height and colour triple.
This mode allows different variables to be mapped by colour into the
surface. The red, green, blue component.
-f11
This is the binary equivalent to -f1, the height and three colour
components are each stored as 4 byte floats. The r,g,b colour
components are assumed to range between 0 and 1.
-f2
Each node is represented by a height and a scalar. "surfanim" uses
this scalar to control the colour based upon a number of linear colour ramps.
There are no assumptions made about
the range of the scalar values, the entire range will be mapped
to the colour ramp.
-f12
This is the binary equivalent to -f2, the height and scalar are
each stored as a 4 byte float.
|
|
Dots
Lines (X and Y)
Grid
Coloured
Shaded
Cylindrical Wrap (X and Y)
Toroidal Wrap (X and Y)
|
Command line options
Command line arguments are listed if the program is run without
any arguments, or if incorrect command arguments are supplied.
Usage: surfanim [command line options]
Required:
-n nx ny grid dimensions
-b s name for data file sequence eg: "aa%%04d.dat"
-bs s name for single data file
Optional:
-f_ data format (default: 0)
-t n0 n1 start frame number [default: 0 to all]
-st n frame skipping [default: 1]
-f full screen
-F full half screen
-s frame sequential stereo
-ss dual screen stereo
-x x axis grid spacing (default: 1)
-y y axis grid spacing (default: 1)
-z height scale factor (default: 1)
-l enable circular looping (default: off)
-i n time interpolation factor (default: 1)
-xy n subsample in x and y axis
-dm n drawing method (default: xlines)
-c n colour ramp type (default: 1)
-lc local colour ramp (default: global)
-as start in autospin mode (default: off)
-bb show bounding box (default: on)
-ax show axes (default: on)
-gr show grid (default: on)
-sl show slider (default: on)
-fps n target frame rate (default: 25)
-bg sl sr background images (left and right)
-vf s start with view file
-d debug mode (default: off)
-h this text
Keystrokes
While the program is running the following keyboard commands
are in effect. Note that menus are presented by using the right
mouse button.
arrow keys rotate left/right/up/down
left mouse rotate left/right/up/down
middle mouse roll clockwise/anticlockwise
right mouse menus
r toggle the automatic time progression
a toggle autospin mode
h reset the camera to home position
1,2,3,4,5,6 move camera to an axis aligned view
w dump current image to disk as TGA file
W turn on continual image dumping
i,j,k,l translate camera up, down, left, right
[,] roll camera clockwise, anticlockwise
+,- move camera forward or backward
f1 toggle help
f2 toggle info
f3 toggle boundingbox
f4 toggle axes
f5 toggle axes grid
f6 toggle animation slider
f7 toggle colour ramp
<,> move forward/backwards in time
0 go to start of time series
esc,q quit
Notes
While "surfanim" was designed primarily as an investigative
tool rather than a presentation one, it does allow images
to be written to disk singly or as part of an animation.
"w" will write the current image as a tga file, "W" (use
with care) will continually write images to disk allowing
an animation to be created.
If the time steps between frames are too coarse and the animation
therefore plays very quickly there are two ways to slow it down.
The first is to use the -fps (frames per second) command line
option to set a maximum frame rate.The second is to interpolate
between time steps using the -i option. For example -i 4 will
linearly interpolate 4 frames between each given frame.
If the animation runs too slowly for large grids then the -xy
options will set a subsamnpling interval, for example, -xy 3
will only display every 3rd grid cell. In addition the -i
option can be used with a number less than 1 to play every
n'th frame. For example -xy 0.25 will play every 4'th time frame.
|