Documentation for evmovie

Contents:

Introduction

Evmovie is a program that can display a series of Surface Evolver surfaces and let the user scroll back and forth through the series. Features:

Programmer: Ken Brakke, Susquhanna University, Selinsgrove, PA 17870, USA, brakke@susqu.edu.


Download and installation:

Microsoft Windows:

evmovie-Win32.zip has Download the zip file and unpack into a folder of your choosing, such as C:\evmovie.

To run the sample movie: Open the C:\evmovie folder in Windows Explorer. Drag the folder testmovie and drop it on top of evmovie.

To make the evmovie program available for your movie files, do any of the following:

Unix, Linux, Mac:

evmovie.tar has Download the tar file and unpack it in a folder.
To make the executable: Open a terminal window, change to the evmovie folder, and run "make".
To run the sample movie: Open a terminal window and change to the evmovie folder. Then run the shell command
   ./evmovie  testmovie/*.offb
To make evmovie available in movie file folders: I suggest you copy the evmovie executable file to a directory on your PATH (such as /usr/local/bin). Otherwise you can invoke it from by typing its absolute path, or, as a last resort, copy it into each folder where you have movie files.

Startup:

Evmovie can be used in drag-and-drop mode, or from a command line.

Drag-and-drop: You can drag a folder containing movie files and drop it on the evmovie program. You have to drag the folder icon itself, not some file within the folder. Evmovie will look within the folder, and assumes all the *.offb files within the folder constitute the movie. The frames will be run in alphabetical order. A command window will also pop up, used for error messages and such.

Command line: The arguments to evmovie can be either one folder name or a list of individual movie files (wildcards permitted). So if testmovie were a folder with movie files, you could do

   evmovie testmovie
or you could do
   evmovie testmovie\frame*.offb
or if you were in the testmovie directory you could
   evmovie frame*.offb
The wildcard should be expanded into an alphabetical list of files, not numerical order, so be sure your frame files are appropriately named. A name style like frame-0001.offb, frame-0002.offb, ... will work much better than freme-1.offb, frame-2.offb, ...

After evmovie starts, it reads the first lines of all the frame files, to check if they are all present and readable. With hundreds or thousands of frames possible, this may take a while, so evmovie prints out frame numbers every once in a while as it does this. Then evmovie prints a message about how many frame files it found, and how many it thinks it can fit into memory at once. The first frame file is read in and the display window popped up. Further frame files are read in on demand; if there is not enough room in memory, then the least-recently-used frame is replaced in memory. Therefore the total number of frames is limited by disk space, not RAM.


Buttons and slider:

The frame position in the movie can be controlled by clicking the left mouse button in the bottom control strip:

Menu

Right-clicking on the evmovie window will display a menu of commands, along with their keystroke shortcuts. See the following three sections for explanations of the various commands.

Movie modes

There are three modes for automatic motion: And some keys controlling movie features:

3D graphics control:

The view of the object can be controlled by left-button clicking and dragging in the main part of the display window. There are several possible modes, which can be toggled between by hitting keys or using the right-button menu: You can use the r, c, t, and z modes while clipping is on; the clipping plane will move with the object.

Other menu and keystroke commands:

Note: The smooth shading algorithm used is rather crude; to get the normal at a vertex, it just averages the normals of all adjacent facets. It assumes all facets are consistently oriented; if not, you will get funny shading bands where the orientation is inconsistent. Also, the algorithm does not understant triple lines, so those may have funny shading also.

Frame file creation

Each movie frame requires its own file. There are both ascii text and binary formats for the frame files. The binary format is preferred, since it is more compact, but I also have the ascii format since it was easier to debug with.

Frame files record the geometry of the surface only, so the particular view of the surface in Evolver graphics is irrelevant (unlike the Evolver postscript command, which uses the current view).

Built-in Evolver command: As of version 2.29, the Surface Evolver has a built-in command binary_off_file that creates a binary frame file for the current surface. The syntax is

    binary_off_file string
where string is a double-quoted string, a string variable, or a string-producing expression, typically using sprintf. Here is a simple Evolver script for producing a movie with one frame for each iteration:
   for ( frame := 1 ; frame <= 1000 ; frame += 1 )
   { binary_off_file sprintf "frame-%04d.offb", frame;
     g;
   }
Note that the %04d format generates zero-padded numbers in the frame file name, so alphabetical order is the same as numerical order.

The facets and edges that are included in the frame file are those for which the facet or edge "show" expressions are true. By default, all facets are shown, and all special edges (edges that are fixed, valence not two, on constraints, or on boundaries). Facet and edge colors are also recorded.

If special viewing modes are in effect, such as torus connected bodies, torus clipped, view transforms, or clipping planes, then these will also affect the facets and edges generated by binary_off_file.

If you have assigned values to the facets' "opacity" attribute, then the opacity format will be used, and evmovie will show translucent surfaces.

Evolver script for ASCII frame files: If, for some reason the built-in binary_off_file command does not suit your needs, you can create your own frame files. Here is a sample Evolver script:


// Surface Evolver command to print ascii OFF file.
// usage:
//   do_off >>> "filename.off"

// Surface Evolver command to print OFF file in a modified
// ascii format.  Difference is each facet is followed by
// one color index integer rather than integer plus color components.

define vertex attribute off_number integer;
do_off := {
   local inx,fcount,ecount;

   // Consecutive index numbers for vertices
   inx := 0;
   foreach vertex vv do 
   { vv.off_number := inx;
     inx += 1;
   };
   fcount := sum(facet,show);
   ecount := sum(edge,show);

   // file header is ascii
   printf "OFF\n";
   printf "%d %d %d\n",vertex_count,fcount,ecount;

   // vertex list
   foreach vertex do { printf "%f %f %f\n",x,y,z };

   // triangle list
   foreach facet ff where ff.show do 
   { printf "%d ",3;
     foreach ff.vertex vv do printf "%d ",vv.off_number;
     printf "%d\n",ff.color;
   };

   // edge list
   foreach edge ee where ee.show do 
   { printf "%d ",2;
     foreach ee.vertex vv do printf "%d ",vv.off_number;
     printf "%d\n",ee.color;
   };

}

Evolver script for binary frame files

// offb.cmd
// Surface Evolver command to print OFF file in a modified
// binary format.  Difference is each facet is followed by
// one color index integer rather than integer plus color components.
// usage:
//   do_off >>> "filename.off"

define vertex attribute off_number integer
do_offb := {
   local inx,fcount,ecount;

   // Consecutive index numbers for vertices
   inx := 0;
   foreach vertex vv do 
   { vv.off_number := inx;
     inx += 1;
   };
   fcount := sum(facet,show);
   ecount := sum(edge,show);

   // file header is ascii
   printf "OFF BINARY\n";
   binary_printf "%ld%ld%ld",vertex_count,fcount,ecount;

   // vertex list
   foreach vertex do { binary_printf "%f%f%f",x,y,z };

   // triangle list
   foreach facet ff where ff.show do 
   { binary_printf "%ld",3;
     foreach ff.vertex vv do binary_printf "%ld",vv.off_number;
     binary_printf "%ld",ff.color;
   };

   // edge list
   foreach edge ee where ee.show do 
   { binary_printf "%ld",2;
     foreach ee.vertex vv do binary_printf "%ld",vv.off_number;
     binary_printf "%ld",ee.color;
   };
}
Frame files by other programs: Frame files may be generated by other programs such as Mathematica or CAD programs, as long as you can get them to output files in one of the frame file formats described below.

File formats

The frame file format is like OFF, except each facet has a color number added. (see OFF format)

There are two formats: ASCII text, and binary. The ASCII format is good for developing frame file generating software, since it is easier to debug, but the binary format is more compact and quicker to load into evmovie.

The color indices used are copied from the Surface Evolver, and are:

   0 BLACK,  
   1 BLUE,
   2 GREEN,
   3 CYAN,
   4 RED,
   5 MAGENTA,
   6 BROWN,
   7 LIGHTGRAY,
   8 DARKGRAY,
   9 LIGHTBLUE,
  10 LIGHTGREEN,
  11 LIGHTCYAN,
  12 LIGHTRED,
  13 LIGHTMAGENTA,
  14 YELLOW,
  15 WHITE
ASCII file format:
  line 1: OFF
     with optional parameters on the same line:
          OPACITY     if the "opacity" facet attribute is being used
          BBOX        if the bounding box is to be shown at startup
          LOOP        if the looping movie mode is to be run at startup
          CYCLE       if the cycle movie mode is to be run at startup
          PLAY        if the forward movie mode is to be run at startup
          CLIP        if clip mode is to be enabled at startup. Must be
                      followed by the four coefficients for the clip plane,
                      as in Evolver's clip_coeff.
          SMOOTH      if smooth shading is to be enabled at startup
          SHOW_EDGES  if all facet edges are to be shown at startup
          FACETS_OFF  if facets are not to be shown at startup
          VIEW        gives the initial view matrix.  Must be followed
                      by 16 numbers, the components of the view matrix.
                      Can use values put out by the Evolver's
                      "print view_matrix" command.  Example (the default view):
                         VIEW 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1
          TEXT        gives a string of text to be displayed in the frame.
                      Must be followed by x,y window coordinates for the
                      lower left start of the text, then a font size number
                      (also relative to window size), and a quoted string
                      of text.  Example:
                          TEXT  0.01 0.01 0.03 "Hello World!"
  line 2: nv nf ne
    where nv is the number of vertices, 
          nf is the number of facets
          ne is the number of edges (yes, edges last)
  lines 3 to 2+nv:
    three floating point numbers per line, coordinates of a vertex
  lines 3+nv to 2+nv+nf:
    3 v1 v2 v3 c op
    where 3 is the number of vertices in the polygon (from OFF format,
      but 3 is the only number evmovie recognizes),
    v1, v2, v3 are the vertex numbers of the facet in the vertex list,
      using 0 based indexing,
    c is the color of the facet, an integer from 0 to 15, being the
      same color number used by Evolver.
    op is the opacity, value 0 for clear to 1 for opaque, if OPACITY is used.
  lines 3+nv+nf to 2+nv+nf+ne:
    2 v1 v2 c
    where 2 is the number of vertices in the edge,
    v1, v2 are the vertex numbers of the edge ends in the vertex list,
      using 0 based indexing,
    c is the color of the facet, an integer from 0 to 15, being the
      same color number used by Evolver.
    Only special edges that should always be shown should be in this list.
Binary file format:
  Line 1 is ascii, ending with newline: OFF BINARY
  with options on the first line same as in ASCII format.

  The rest of the file is the same format as the ASCII version, but
  with 4-byte ints and 4-byte floats and no newlines.  So the
  length of the file after the first line is 3 + nv*4*3 + nf*4*5 + ne*4*4 
  (or nf*4*6 if opacity is used).
  The program tries to automatically detect big-endian vs little-endian
  format by seeing which gives the correct filesize.

End of evmovie documentation.
Susquehanna University assumes no responsibility for the content of this personal Web page. Please read the disclaimer.