Point Animator

Written by Paul Bourke
December 2000


"pointanim" (point animator) is an OpenGL application to visualise, in stereo3D, point datasets that vary in time. The exact specifications have evolved to meet the needs of the local research projects. Two stereo3D modes modes are supported, frame sequential that typically runs at 120Hz and uses active shutter glasses, and dual display which normally uses a two pipe OpenGL card and passive polaroid glasses. Various data formats are supported (see later), some are ASCII and other binary. The binary formats while less convenient are normally used because they can be read significantly faster. The basic element of a data file is a series of x,y,z triples, each one is drawn as a point with some colour. The colour can either be derived from geometric features such as curvature, velocity, etc, or a scalar variable can be specified and this will be mapped onto one of a number of colour ramps, or it can be explicitly specified in the data file.

The normal use of "pointanim" involves launching the application with a variety of command line arguments, once loaded the point data is repeatedly drawn for each time step. The user may control almost all aspects of the camera, position, orientation, etc as well as control time (run forward, backwards, stop, jump to arbitrary position).

Command line arguments

Typing "pointanim" on the command line will present the following (since none of the required arguments are provided).

Usage: pointanim [command line options]
          -np n      number of points to read from each file
          -f_        read in different formats (currently 0..5)
          -b s       printf name for files eg: "aa%%04d.dat"
          -f         full screen
          -F         full half screen
          -s         frame sequential stereo
          -ss        dual screen stereo
          -l         circular looping (default: off)
          -dn n      the subsampling rate (1..)
          -i n       interpolation factor (1..)
          -da n      draw as symbol (default: 1)
          -os n      object size (default: 1)
          -c n       colour ramp (default: 1)
          -C n       colour attribute (default: -1)
          -as        start in autospin mode (default: off)
          -bb        show bounding box (default: off)
          -ax        show axes (default: off)
          -gr        show grid (default: off)
          -sl        show slider (default: off)
          -fps n     target frame rate (default: 25)
          -bg sl sr  background images (left and right)
          -vf s      start with view file
          -d         debug mode
          -h         this text

There are three required arguments, the number of points "-np" in each file (it isn't generally stored with the file), the format "-b" for the name of the data files, and the format of the files themselves "-f". The format for the file name follows standard C format specifications for printf().

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

As an example of the minimum command line to run "pointanim", assume the data files are called galaxy000.pnt, galaxy001.pnt, galaxy002.pnt, etc, each contains 10,000 points and and each point is defined by a vertex and colour then the minimal command line would be

   pointanim -np 10000 -f3 -b galaxy%03d.pnt

Keyboard commands

Once the program is running the following keyboard commands are supported.

  arrow keys   rotate left/right/up/down
  left mouse   rotate left/right/up/down
middle mouse   roll clockwise/anticlockwise
           a   toggle autospin
           h   move the camera to the default position
           r   toggle automatic progression of time
     i,j,k,l   translate up,down, left, right
         [,]   roll clockwise, anticlockwise
         +,-   move forward or backward
         <,>   move forward/backwards in time
          f1   toggle help
          f2   toggle info
          f3   toggle boundingbox
          f4   toggle axes
          f5   toggle axes grid
          f6   toggle animation slider
          f7   toggle colour ramp
           0   go to the first frame
         1,2   decrease/increase frame rate
           w   dump current image to disk as TGA file
       esc,q   quit
File Formats

"pointanim" expects each time step to be stored in a separate file. The file name must contain an integer from 0 upwards that indicates the time sequence order. Otherwise, since "pointanim" is given the C printf() format string for the file names, the file names can be formatted however one likes. The following formats specified by the "-f" option are currently supported.

f0 binary Simplest binary format, 3 floats for each x,y,z triple.
f1 ascii Ascii version of the above, triples x y z separated by any white space. Read as fscanf(fptr,"%f %f %f",&x,&y,&z);
f2 binary Same as -f0 except for two differences. short ints are used for each x,y,z and the file starts with an int giving the number of points. Note "pointanim" ignores the number of points and expects the number given on the command line.
f3 ascii Each point is expected to have a coordinate triple and an rgb colour triple. These colours will be used for each point although they may be overwritten within the application by the user (see menus).
fscanf(fptr,"%f %f %f %f %f %f",&x,&y,&z,&r,&g,&b);
f4 ascii Each point is expected to have a x,y,z triple and a scalar value. This scalar value will be mapped onto various colour maps within the application.
fscanf(fptr,"%f %f %f %f",&x,&y,&z,&c);
f5 binary Same as -f0 but with additional r,g,b colours as floats.


  • Assuming the n'th point in each file corresponds to the same object (although at a different position) then smoother animations can be achieved by interpolating between frames, see the "-i" option. So for example, "-i 4" will generate 4 frames between every data frame.

  • While "pointanim" is designed as a data investigation tool rather than a presentation one, it does allow single images or animation sequences to be written to disk, see the "w" or "W" (use with care) keyboard commands. The window size menu allows some of the animation standard frame sizes to be chosen.

  • The stereo3D modes are mostly expected to be run in full screen mode.

  • In order to maintain reasonable frame rates all the data must be able to reside in RAM.

  • The number of points in each data file must be constant.

  • The interpolation command line option (-i n) assumes the points between files match, that is, point 100 in frame 5 is the same as point 100 in frame 6 and so on. Some of the line drawing options also assume this for them to make sense.

  • The colour attribute options are destructive, that is, they overwrite colour or scalar information that may have been provided in the data files.