The Toolchest

     In the last issue of the newsletter we described the program
epsilon, a simple utility for removing floating point errors from
ascii data files.  In this issue we will continue this series with
a description of interpolate, a general tool for interpolating data
between two or more (formatted) ascii files or binary data files.

     As before the program is available via anonymous ftp from our site:

  poincare.geom.umn.edu

  Login with user name anonymous or ftp, with any non-blank password.
  (Its nice for us if you use your name and path as password.)

  The source is contained in the directory pub, usually in a tar file,
  so remember to switch to binary mode in ftp.


     Often when creating animations we want to be able to
smoothly interpolate from one "thing" to another "thing"- this may be the
positions of objects, their shapes, their surface attributes, or the
positions of cameras and lights, or even from one image to
another.  The program interpolate is designed to handle all these
cases by performing interpolations with no a priori knowledge of the 
format of the data.

     In its simplest form the program works as follows:  Suppose
we are given two ascii data files, assumed to be in the same format,
although they may contain different data.  If the files are
called "data_one" and "data_two", then the command

    interpolate  data_one   data_two   data_out

will create 10 files (the default number), called  data_out.0,...,data_out.9,
which maintain the same format as data_one and data_two and
linearly interpolate the data between them.   Interp can also accept
more that two input data files.  A complete usage message is obtained
by typing 'interpolate' with no arguments:

Usage: interpolate <options> file1 ... filen outfile
  options:
    -ASCII       (ASCII data files)
    -BINARY      (BINARY data files)
                 (default = ASCII
    -number nnn  (nnn = number output files.)
                 (default = 10)
    -skip nnn  (nnn = number lines to skip (ASCII))
               (nnn = number bytes to skip (BINARY))
               (default = 0)
    -in_time n time1 time2 ... timen
               (n = number of times, timei = times
               (default = uniform by number of input files)
    -out_time n time1 time2 ... timen
               (n = number of times, timei = times
               (default = uniform by number of output files)
    -suffix strng  (strng appended to output names)
    -chunk nnn  (process data nnn items at a time)
                (default = 1000)

With no options, interpolate will interpolate ten files between file0, 
file1,... and filen.  The data in the input files are placed on a hypothetical
"time line"- the data in file0 at time 0, in file1 at time 1, .... , in
filen at time n.  The interpolation then takes place at
ten evenly spaced times between 0 and n. The number of output files, as
well is the input and output "times" may be modified by command line
options.
 
The options may appear anywhere on the command line and have the following
effects:

1) The optional arguments -ASCII and -BINARY identify the type of file.
   The default is -ASCII, meaning all data and keywords are in ASCII
   readable format.  The -BINARY option means that the data is in binary
   format, assumed to be one byte unsigned integers.  This is useful for
   interpolating between raster images.

2) The optional argument 
        -number nnn 
   changes the number of output files produced to nnn.
   

3) The optional argument 
        -skip nnn 
   instructs the program to do no
   interpolation on the first nnn lines in the ASCII case, and first
   nnn bytes in the BINARY case. 

4) The optional argument 
         -in_time n time1 time2 ... timen
   changes the timing values of the input files.  n = number of times
   to follow, and time1,...,timen are the times.  Note that the
   number n must be equal to the number of input files listed.

5) The optional argument 
         -out_time n time1 time2 ... timen
   changes the timing values of the output files.  n = number of times
   to follow, and time1,...,timen are the times.  Note that this
   supercedes setting the number of output files by the -number option.

6) The optional argument
          -suffix strng
   appends the string strng onto the names of all the output files.  This
   is useful for file types identified by their suffixes, e.g.
   MinneView files.

7) The optional argument
           -chunk nnn
   sets the parameter chunk in the internal workings of interpolate.  The
   default value of chunk is 1000.  The
   program works by reading in chunk items of  data from all the input files
   at a time, processing them and printing out the results, and then
   reading in the next chunk items of data.  Each data item takes up 16 bytes
   (on an Iris).  For interpolations involving 
   large numbers of files, it may be necessary to decrease the value
   of chunk, depending on available memory.  For example,  if there are
   20 input data files, 100 ouput data files,  and chunk = 1000, 
   then we need at least  (20 + 100) * 16 * 1000 = 1.92 MBytes of memory
   to run efficiently.

Here are some examples of the use of interpolate.
     
1) Suppose a.quad and b.quad are two MinneView quad files containing the
   same number of quadrilaterals.  The command

   interpolate -suffix quad a.quad b.quad foo

   will produce 10 quad files foo.0.quad,....,foo.9.quad interpolating
   the shapes between a.quad and b.quad.  (These may be interactively
   played back using MinneViews sequencing capablities by typing
   MinneView foo.?.quad.)

   The command

      interpolate -out_time 5 0.0 0.1 0.2 0.6 1.0 a.quad b.quad foo

   will create five files foo.0,...,foo.4 in which the interpolation
   of a.quad to b.quad is faster toward the end than the beginning.

2)  Given two 24 bit raster files a.rgb and b.rgb of the same
    resolution, the command

    interpolate -BINARY -suffix rgb -number 30 a.rgb b.rgb foo

    will produce 30 raster files foo.0.rgb,...,foo.29.rgb which
    interpolate the images between a.rgb and b.rgb.

    These may then be converted, for example, to sgi format and played back
    using the project's smovie program, or recorded onto video tape,
    thus making a one second scene transition from a.rgb to b.rgb.

Notes:

1)    At the moment a student at the lab (Jim Larson) is working
   on adding a cubic spline interpolation option to interpolate.  After
   that, we will begin working on a method for incorporating user-
   definable routines, thus greatly increasing the scope of the program.
   Both of these developments will be reported in future Toolchest columns.

2)   The program interpolate is available via anonymous ftp from our site
   (poincare.geom.umn.edu).  The source, a makefile, and this article
   are contained in the file interpolate.tar in the directory ~ftp/pub.
   After extracting the files compile interpolate by typing 'make'.
   Comments, bug reports, suggestions should be sent to 
   orloff@poincare.geom.umn.edu.

  
