.PP
\fBAnimate\fP can be executed from within \fBcantata\fP, or directly from 
the command line. When using the command line interface, an image must 
be specified at the time of execution.  
This is done by providing the [-i filename] option flag, specifying the
VIFF multiband image containing the data bands that will provide the 
sequence of frames to be animated.  The VIFF image file may be of any data 
type except complex. If a colormap is to be used, the input image must have a
map type of SHARED. If the map type is not SHARED, the colormap will be ignored.
.PP
Alternatively, you may provide a basename that describes a set of single band 
images located in the same directory, and use these as input to animate.  
For example, you might have a directory called "frames" that contains 30 
single band images named "frame.01" to "frame.30".  In this case, the 
\fIbasename\fP would be, \f(CWframes/frame.\fP -- in other words, the part 
of the directory path and filename that all the images to be input have in 
common.  In this case, the single band images are combined into an internal 
multiband image before being sequenced through as they would in the first case.
.PP
The minimum syntax specification to run 
\fBanimate\fP from the command line is:
.sp
\f(CW
% animate -i filename
.br
-or-
.br
% animate -base basename
\fP
.sp
.PP
You will be immediately prompted to place the \fBanimate\fP master form.
The \fBanimate\fP master form will have a workspace attached beneath it,
in which the image specified will immediately be displayed.
.PP
The \fBanimate\fP master form has a subform button labeled "Input" which
provides four selections in which to enter input files.  These include an 
"Image" input file selection in which a new image may be input, a "basename"
string selection in which a new basename may be input, a "Clip" input file 
selection in which an image may be provided to act as a clip mask, and a 
"Shape" input file selection in which an image may be specified to act as 
a shape mask.  
.PP
The subform button labeled "Options" will bring up the "Options" subform
which contains an "Animation Control" toggle which gives a choice of three 
sequencing mechanisms: looping, single stepping, or autoreverse. 
Below these are the "Rootwindow" and "Show Band" logical selections.
The default value for both is false; however, if you would like to
see the animation on the root window, or would like the number of the image 
band currently being displayed to be shown in the upper left hand corner of
the animation display,  click on the appropriate logical button. 
Finally, the "Options" subform has a float selection with which one may 
specify the speed of the animation, where "0" is as fast as possible, and
"5" is very slow.  
.PP
Buttons for sequencing in the forward direction, buttons for sequencing in 
the reverse direction,  and a button for stopping the animation are provided
directly on the animate master form above the display window.
.sp
.SH
Other Command Line Options
.PP
While only the [-i image] or the [-base basename] flag is required on the 
command line to execute
\fBanimate\fP, there are many other optional input flags that may be used.
The full syntax for executing \fBanimate\fP from the command line is as follows:
.sp
animate
.sp
        -i  image to do slide show animation  (infile) -OR-
.br
        -base  basename to a set of images  (string)
.sp
        [-c]  input clip mask filename (infile) [null]
.br
        [-s]  input shape mask filename (infile) [null]
.br
        [-use_pixmap]  Use pixmap memory (boolean) [true]
.br
        [-use_root]  Use rootwindow to display animation (boolean) [false]
.br
        [-use_cmap]  use colormap? (boolean) [true]
.br
        [-x]  x value of upper-left corner of image (integer, -1 to 1000) [-1]
.br
        [-y]  y value of upper-left corner of image (integer, -1 to 1000) [-1]
.br
        [-update]  initial update time (float, > 0.0) [2]
.br
        [-display]  host:display.screen (string) [null]
.sp
        [-V] Gives the version for animate
.br
        [-U] Gives the usage for animate
.br
        [-P] Prompts for command line options
.br
        [-A [file1]] Creates the answer file called animate.ans or file1
.br
        [-a [file1]] Uses animate.ans or file1 as the answer file
.sp 2
.IP "clip mask filename"
If desired, a bit image may be input and used as a clip mask.
When an image is used as a clip mask for the currently displayed image,
the only part of the current image that will appear normally
is that part defined by the pixels in the clip mask image that have a value
of (1). All other parts of the current image will appear in the background
color of the image window. 
It must be specified as "-c filename" where the file provided is a Khoros
viff file of data type bit.
.IP "shape mask filename"
If desired, a bit image may be provided to act as a shape mask. When an image
is used as a shape mask for the currently displayed image, the only part of the
currently displayed image that will be visible is that part defined by the 
pixels in the shape mask image that have a value of (1).  All other parts of
the currently displayed image will "disappear", and the background (the part
of the screen behind the image  display window) will show through. 
It must be specified as "-s filename" where the file provided is a Khoros
viff file of data type bit.
.IP
WARNING: Only very simple bit images should be used as shape masks.  
For example, the bit image \f(CWKHOROS_HOME/data/masks/ball.bit\fP 
is a good shape mask. As more complicated images are used (images with 
many "holes" in them), \fBanimate\fP will become incredibly slow as the 
X server  has to do much additional work in order to map the image to the 
window.  WARNING: This feature will only work on X servers that support X11 R4!
.IP "Use Pixmap"
The default action of animate is to convert all images into pixmaps
before animating the different images.  It you set use_pixmap to false
then animate will convert all images into ximages instead. Note that
converting images into pixmaps is a much faster operation, which is why
this is the default behavior.
.IP "Use Root"
Provide a value of True (1) if you want the animation to take place on the
root window.
.IP "Use Colormap"
While the default action of animate is to use the colormap associated with
the currently displayed image, no colormap is required to be used.
If the colormap associated with the currently displayed image is not wanted,
AND the "-cmap_image filename" is not used, specify "-use_cmap 0", or
"-use_cmap false".  In this case, the default colormap associated with the
screen on which animate is being run will be used.
.IP "x, y"
When your window manager does not have manual placement of windows, you may
specify the (x,y) position of the desired location for the automatic placement
of animate's graphical user interface. 
.IP "update time"
Suppose that while you are displaying an image with \fBanimate\fP, the Khoros
viff file that is currently displayed is over-written.  Animate will 
automatically register the fact that the input file has been changed, and 
update the currently displayed image accordingly.  Using this argument, you
can determine how often the input file is checked for any potential 
modifications.    It must be specified "-update floatvalue", where floatvalue
is a floating point value which must be greater than zero.
.IP "display"
You may execute \fBanimate\fP on one workstation, but display it on another.
If you wish to do this, you must specify the display on which \fBanimate\fP will
appear.  It must be specified as "-display host:screen".
.IP "Version"
The "-V" argument will print out the current version of \fBanimate\fP.
.IP "Usage"
The "-U" argument will print out the usage for \fBanimate\fP, in much less 
detail than is given here.
.IP "Interactive Prompting"
The "-P" argument will give interactive prompting for each of the arguments
listed above.  
.IP "Creating an Answer file"
The "-A [filename]" argument will create an answer file named "filename" if
the filename option is specified, or named "animate.ans" if no filename
is given.  An answer file stores the values specified of all arguments listed 
above.  Note: the "-A" argument is usually used in conjunction with the "-P"
argument.
.IP "Using an Answer file"
The "-a [filename]" argument will use the answer file named "filename"
if the filename option is specified, or named "animate.ans" if no filename
is given.  Animate will use the answer file to get values for all
arguments listed above.  No other arguments should be necessary when the "-a"
argument is used.
