
animate(1)                   Khoros                    animate(1)

PROGRAM
     animate - displays an image sequence from a single VIFF
     image with multiple bands, or from several single band VIFF
     images with the same basename.

SYNTAX
     animate

     [-c]           input clip mask filename

     [-s]           input shape mask filename

     [-cmap_image]  image with alternate colormap filename

     [-use_pixmap]  Use pixmap memory

     [-use_root]    Use rootwindow to display animation

     [-use_iconic]  Creates an iconic animation when iconified

     [-use_cmap]    use colormap?

     [-x]           x location of GUI

     [-y]           y location of GUI

     [-update]      initial update time

     [-display]     host:display.screen

     [-base]        basename to a set of images
                                        -OR-

     [-i]           image to do slide show animation

     [-fn]          Specifies the font for animate (use %
                    xlsfonts for available fonts)

     [-jr file.jp]  Creates a journal recording for animate

     [-jp file.jp]  Executes a journal playback for animate

     [-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

DESCRIPTION
     Animate is an interactive image sequence display tool. This
     application allows you to input an image that contains mul-
     tiple data bands and sequence through those data bands in
     different ways.  Alternatively, you may provide a basename
     that describes a set of single band images;  these will be
     read in (if any images in the set is multiband, only the 0th
     band will be used) and cycle through the data bands as
     desired.  Currently, animate can utilize a maximum of 256
     colors.

     The display functionalities provided by animate include:

     1)   Forward and reverse sequencing.

     2)   Different sequencing mechanisms (looping, one time,
          auto reverse).

     3)   Sequencing speed.

     Animate can be executed from within cantata, or directly
     from the command line. When using the command line inter-
     face, either a single multiband image or a valid basename
     must be specified at the time of execution. This is done by
     providing one of the -i or -base option flags. The minimum
     syntax specification to run animate from the command line
     is:

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

     Recommended images for use with animate can be found in
     $KHOROS_HOME/data/sequences.

     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 first data band provided
     will immediately be displayed.  Above the image display is
     the animate master form.

     The animate master form has two subform buttons, Help and
     Quit buttons, and buttons for sequencing in the forward or
     reverse direction or stopping that appear above the image
     display window.

     From the I/O subform, you may enter a new multiband image, a
     new basename, a new clip mask, or a new shape mask.  To make
     a clip or shape mask go away, blank out the appropriate
     parameter box, and hit <cr>. In some cases,  you may have to
     hit the <cr> twice in order for the shape or clip mask to go
     away.

     The Options subform provides animation control so that one
     may loop through the data bands, make a single pass through
     the data bands, or reverse the data band sequence.  Also on
     the Options subform are logical selections where you may
     specify whether or not animate is to display the frame
     number of the data band in the display window, and whether
     or not to animate the sequence on the root window rather
     than in the display window. Finally on the Options subform,
     you may control the speed at which the data bands are
     sequenced; speed goes from 0.0 to 5.0, where 0.0 is fastest,
     and 5.0 is slowest.  NOTE: for general use, we DO NOT recom-
     mend using a speed of 0.0!  This is so fast that it is often
     very difficult to regain control of the graphical user
     interface!

     Command Line Options

     [-i {input image filename}]
          This is the one required input for animate, unless the
          [-base {basename}] flag is used.  It must be specified
          as "-i filename", where the file provided is a Khoros
          VIFF file.  The VIFF file may be of any data type
          except complex. The first data band will be the
          currently displayed image. Animate will sequence
          through the data bands in the image. 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 map will be
          ignored.

     [-base {basename}]
          If you do not have a multiband image for input to ani-
          mate, you may instead provide a basename that specifies
          a group of single band images that can be used with
          animate.  Note that images will be taken in alphabeti-
          cal order, so if you have a group of more than 9 but
          less than 100 images, all named, for example, image.x
          where x is the sequence order, you will have to make
          sure that x starts with "01" through "09".  This is
          because alphabetically, image.1 will be followed by
          image.10 and image.2 will be followed by image.20
          unless you follow the preceding naming convention.

     [-s {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  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.  Images work best as shape
          masks when they are the same size as the input data.
          $KHOROS_HOME/data/masks/ contains two images that make
          good shape masks.  To get a shape mask to go away, NULL
          out the "Shape Mask" parameter, and hit <cr>.  You may
          have to hit the <cr> key twice.  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 win-
          dow.  WARNING:  this feature will only work on X
          servers that support the Shape Extension.

     [-c {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
          animated data 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 frame
          will appear in the background color of the image win-
          dow. Images work best as clip masks when they are the
          same size as the input data.  $KHOROS_HOME/data/masks/
          contains two images that make good clip masks.  To get
          a clip mask to go away, NULL out the "Clip Mask" param-
          eter, and hit <cr>.

     [-use_pixmap {t/f}]
          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_cmap {t/f}]
          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. NOTE:  when
          "Use Colormap" is specified as false, the "-cmap_image
          filename" option detailed above WILL NOT TAKE EFFECT.

     [-use_root {t/f}]
          In obscure situations, you may prefer to see the anima-
          tion sequence on the root window.  If this is the case,
          specify [-use_root t];  the animation sequence will be
          displayed on the upper left hand corner of the root
          window.

     [-x {x value}, -y {y value}]
          If your window manager does not use manual placement,
          or you would like to over-ride the manual placement
          used by your window manager (this may not work with all
          window managers), specify the (x,y) location in device
          coordinates at which you would like the graphical user
          interface to appear.

     [-update {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 {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".

     [-V {t/f}]
          The "Version" argument will print out the current ver-
          sion of animate.

     [-U {t/f}]
          The "Usage-" argument will print out the usage for ani-
          mate, in much less detail than is given here.

     [-P {t/f}]
          The "Prompt" argument will give interactive prompting
          for each of the arguments listed above.

     Creating an Answer file
          The "[-A {filename.ans}]" argument will create an
          answer file named "filename.ans" 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.

     [-a {filename.ans}]
          Use the answer file named "filename.ans" 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.

REQUIRED ARGUMENTS
     none

OPTIONAL ARGUMENTS
     -c     type: infile
            desc: input clip mask filename

     -s     type: infile
            desc: input shape mask filename

     -cmap_image
            type: infile
            desc: image with alternate colormap filename

     -use_pixmap
            type: boolean
            desc: Use pixmap memory
            default: true

     -use_root
            type: boolean
            desc: Use rootwindow to display animation
            default: false

     -use_iconic
            type: boolean
            desc: Creates an iconic animation when iconified
            default: false

     -use_cmap
            type: boolean
            desc: use colormap?
            default: true

     -x     type: integer
            desc: x location of GUI
            default: -1
            bounds: -1 < [-x] < 1000

     -y     type: integer
            desc: y location of GUI
            default: -1
            bounds: -1 < [-y] < 1000

     -update
            type: float
            desc: initial update time
            default: 2
            bounds: value > 0.0

     -display
            type: string
            desc: host:display.screen
            default: null

     ***   These arguments are MUTUALLY EXCLUSIVE   ***
      If desired, you may provide ONE AND ONLY ONE of:

     -base  desc: basename to a set of images
            default: null

     -i     desc: image to do slide show animation

            ********

EXAMPLES
     % animate -i $KHOROS_HOME/data/sequences/bushes
     % animate -i $KHOROS_HOME/data/sequences/bush.
     % animate -i $KHOROS_HOME/data/sequences/bushes -c
     $KHOROS_HOME/data/masks/smball.bit

SEE ALSO
     intro(1), verror(3), vgparms(3), vutils(3), lanimate(3) edi-
     timage(1), putimage(1)

RESTRICTIONS
     1) If the input image contains a colormap, the map scheme
     must be SHARED, otherwise the map will be ignored.
     2) When the [-update] argument is used and the currently
     displayed image is changed when the original input file is
     over-written, the image is updated accordingly; however, the
     new image will have its colormap corrupted by the colormap
     of the previous image.

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

Khoros                    Release: 1.0                          1

