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 multiple 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 interface, 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 recommend 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 animate, 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 alphabetical 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 window) 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 window. 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 window. 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" parameter, 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 animation 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 floatvalue 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 version of animate.

[-U {t/f}]
    The "Usage-" argument will print out the usage for animate, 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) editimage(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.