
iconimage(1)                 Khoros                  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 over-
          layed 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 con-
          verted 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.  WARN-
          ING: 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 speci-
          fied.

     [-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 ver-
          sion 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" argu-
          ment 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.

Khoros                    Release: 1.0                          1

