iconimage(1)

PROGRAM
iconimage - This program displays an iconified version of an image.

SYNTAX

iconimage

-i  input image filename

[-ov]
    overlay image filename

[-s]
    input shape mask filename

[-c]
    input clip mask filename

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

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

[-w]
    width of icon image in pixels

[-h]
    height of icon image in pixels

[-update]
    update time

[-display]
    host:display.screen

[-use_cmap]
    use colormap?

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

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

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

[-V]
    Gives the version for iconimage

[-U]
    Gives the usage for iconimage

[-P]
    Prompts for command line options

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

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

DESCRIPTION
This is a non-interactive display program which creates an "iconified" version of an image in Khoros VIFF format and displays it to an X11 screen. The image is sub-sampled according to the desired width and height, and displayed. Clicking the mouse within the iconified image will cause it to go away.

Command Line Options

-i {input image filename}
    This is the one required input for iconimage. 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. 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.

[-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 input image, the only part of the input 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 input 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), iconimage 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 input image, the only part of the iconimaged 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 iconified image to appear.

[-w {width}, -h {height}]
    The -w and -h options allow the width (in pixels) and the height (in pixels) of the icon image to be specified.

[-update {update time}]
    Suppose that while you are displaying an iconified image with iconimage, the Khoros VIFF file that is currently displayed is over-written. Iconimage 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. The update time provided is a floating point value which must be greater than zero.

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

[-use_cmap {t/f}]
    While the default action of iconimage is to use the colormap associated with the input 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 iconimage is being run will be used.

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

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

-c  type: infile
    desc: input clip mask filename

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

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

-w  type: integer
    desc: width of icon image in pixels
    default: 64
    bounds: 0 < [-w] < 1000

-h  type: integer
    desc: height of icon image in pixels
    default: 64
    bounds: 0 < [-h] < 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
% iconimage -i ball.xv -w 50 -h 50

SEE ALSO
intro(1), verror(3), vgparms(3), vutils(3), liconimage(3) , editimage(1)

RESTRICTIONS
1) iconimage will only work on images which are in Khoros image file format (VIFF files)
2) When the [-update] argument is used and the currently iconified 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 1992, University of New Mexico. All rights reserved.