
putimage(1)                  Khoros                   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 pro-
          gram 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 mov-
          ing it.  Alternatively, you may perform this same pro-
          cedure in the little pan window;  the rectangle indi-
          cating 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 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 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), putimage 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 putim-
          age 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/ con-
          tains two images that make good clip masks.  To get a
          clip mask to go away, NULL out the "Clip Mask" parame-
          ter, 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 float-
          value 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 color-
          map 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 ver-
          sion 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" 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: 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.

Khoros                    Release: 1.0                          1

