Surface Animator

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).

"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.

Lines (X and Y)

Grid

Coloured

Shaded

Cylindrical Wrap (X and Y)

Toroidal Wrap (X and Y)