putimage(1)

PROGRAM
putimage - This is a non-interactive image display program.

SYNTAX

putimage

-i  input image filename

[-ov]
    overlay image filename

[-s]
    shape mask filename

[-c]
    clip mask filename

[-x]
    x value of upper-left corner of image

[-y]
    y value of upper-left corner of image

[-update]
    update time

[-display]
    host:display.screen

[-use_cmap]
    use colormap?

[-V]
    Gives the version for putimage

[-U]
    Gives the usage for putimage

[-P]
    Prompts for command line options

[-A [file1]]
    Creates the answer file called putimage.ans or file1

[-a [file1]]
    Uses putimage.ans or file1 as the answer file

DESCRIPTION

    Putimage displays an image in Khoros VIFF format to an X11 screen, without using the graphical user interface. Clicking the mouse within the image will cause it to go away. NOTE: you *must* keep the mouse still when you click in the image in order to make the putimage program end.

    When an image too large to display within the window, putimage will display a small pan window. The white rectangle within the pan window indicates the area that is currently displayed in the display window. You may "pan" about the image by pressing the mouse in the display window, holding the mouse button down, and moving it. Alternatively, you may perform this same procedure in the little pan window; the rectangle indicating the area that is currently displayed will move with the mouse, and the display window will update according to the location of the rectangle within the pan window.

    Often, the putimage and getimage programs are used as a pair. The getimage program may be used to store any displayed window image as a Khoros VIFF file. Later, putimage may be used to re-display the image. In this way, Khoros VIFF files may be produced from raw images, and re-displayed later.

Command Line Options

[-i {input image filename}]
    This is the only required input to putimage. The file provided is must be a Khoros VIFF file. The VIFF file may be of any data type except complex.

[-ov {overlay image filename}
    If desired, a bit image may be specified to be overlayed onto the input image. It must be specified as "-ov filename" where the file provided is a Khoros VIFF file of data type BIT. NOTE: if the VIFF image passed in is NOT of type BIT, it will be automatically converted to type BIT, without prompting or warning (this is only done internally - the file itself will not be changed). ALSO: if the VIFF data file passed in is a multiband image, the first (0th) band will be taken as the overlay.

[-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), putimage 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 putimage 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>.

[-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 image to appear.

[-update {update time}]
    Suppose that while you are displaying an image with putimage, the Khoros VIFF file that is currently displayed is over-written. Putimage 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 putimage on one workstation, but display it on another. If you wish to do this, you must specify the display on which putimage will appear. It must be specified as "-display host:screen".

[-cmap_image {VIFF image w/ alternate colormap}]
    If desired, another image may be input, and its colormap will be used with the input image, instead of the input image's colormap.

[-use_cmap {t/f}]
    While the default action of putimage is to use the colormap associated with the currently displayed image, no colormap is required to be used. If the colormap associated with the input image is not wanted, specify "-use_cmap 0", or "-use_cmap false". In this case, the default colormap associated with the screen on which putimage is being run will be used.

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

[-U {t/f}]
    The "Usage-" argument will print out the usage for putimage, 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 "putimage.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 "putimage.ans" if no filename is given. Putimage 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

-i  type: infile
    desc: input image filename

OPTIONAL ARGUMENTS

-ov type: infile
    desc: overlay image filename

-s  type: infile
    desc: shape mask filename

-c  type: infile
    desc: clip mask filename

-x  type: integer
    desc: x value of upper-left corner of image
    default: -1
    bounds: -1 < [-x] < 1000

-y  type: integer
    desc: y value of upper-left corner of image
    default: -1
    bounds: -1 < [-y] < 1000

-update
    type: float
    desc: update time
    default: 0
    bounds: value >= 0.0

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

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

EXAMPLES
% putimage -i filename.xv -x 100 -y 100

SEE ALSO
intro(1), verror(3), vgparms(3), vutils(3), lputimage(3)
getimage(1)

RESTRICTIONS
1) putimage will only work on images which are in Khoros image file format (VIFF images)
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.