
ANIMATE(help)                Khoros                 ANIMATE(help)

     STARTING UP ANIMATE

     Animate can be executed from within cantata, or directly
     from the command line. When using the command line inter-
     face, 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.

     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
     basename would be, frames/frame. -- 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.

     The minimum syntax specification to run animate from the
     command line is:

     % animate -i filename
     -or-
     % animate -base basename

     You will be immediately prompted to place the animate master
     form.  The animate master form will have a workspace
     attached beneath it, in which the image specified will
     immediately be displayed.

     The animate 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 selec-
     tion 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.

     The subform button labeled "Options" will bring up the
     "Options" subform which contains an "Animation Control" tog-
     gle 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.

     Buttons for sequencing in the forward direction, buttons for
     sequencing in the reverse direction,  and a button for stop-
     ping the animation are provided directly on the animate mas-
     ter form above the display window.

     Other Command Line Options

     While only the [-i image] or the [-base basename] flag is
     required on the command line to execute animate, there are
     many other optional input flags that may be used.  The full
     syntax for executing animate from the command line is as
     follows:

     animate

             -i  image to do slide show animation  (infile) -OR-
             -base  basename to a set of images  (string)

             [-c]  input clip mask filename (infile) [null]
             [-s]  input shape mask filename (infile) [null]
             [-use_pixmap]  Use pixmap memory (boolean) [true]
             [-use_root]  Use rootwindow to display animation
     (boolean) [false]
             [-use_cmap]  use colormap? (boolean) [true]
             [-x]  x value of upper-left corner of image
     (integer, -1 to 1000) [-1]
             [-y]  y value of upper-left corner of image
     (integer, -1 to 1000) [-1]
             [-update]  initial update time (float, > 0.0) [2]
             [-display]  host:display.screen (string) [null]

             [-V] Gives the version for animate
             [-U] Gives the usage for animate
             [-P] Prompts for command line options
             [-A [file1]] Creates the answer file called
     animate.ans or file1
             [-a [file1]] Uses animate.ans or file1 as the answer
     file

     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.

     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 win-
          dow) will show through. It must be specified as "-s
          filename" where the file provided is a Khoros viff file
          of data type bit.

          WARNING: Only very simple bit images should be used as
          shape masks. For example, the bit image
          KHOROS_HOME/data/masks/ball.bit is a good shape mask.
          As more complicated images are used (images with many
          "holes" in them), animate 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!

     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.

     Use Root
          Provide a value of True (1) if you want the animation
          to take place on the root window.

     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.

     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.

     update time
          Suppose that while you are displaying an image with
          animate, 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 float-
          value is a floating point value which must be greater
          than zero.

     display
          You may execute animate on one workstation, but display
          it on another.  If you wish to do this, you must
          specify the display on which animate will appear.  It
          must be specified as "-display host:screen".

     Version
          The "-V" argument will print out the current version of
          animate.

     Usage
          The "-U" argument will print out the usage for animate,
          in much less detail than is given here.

     Interactive Prompting
          The "-P" argument will give interactive prompting for
          each of the arguments listed above.

     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 argu-
          ments listed above.  Note: the "-A" argument is usually
          used in conjunction with the "-P" argument.

     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.  Ani-
          mate 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.

          Copyright 1991, University of New Mexico. All rights
          reserved.

Version: 0                 Release: 1                           1

