
getimage(1)                  Khoros                   getimage(1)

PROGRAM
     getimage - This is a  window image dumping utility.

SYNTAX
     getimage

     -o             output image filename

     [-e]           extract image from screen?

     [-all]         get the entire screen?

     [-name]        name or id of window to dump

     [-b]           output image in bitmap format?

     [-decor]       grab the screen (WM) decoration?

     [-d]           host:display.screen

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

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

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

     [-V]           Gives the version for getimage

     [-U]           Gives the usage for getimage

     [-P]           Prompts for command line options

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

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

DESCRIPTION
          getimage is similar to 'xwd', the X window dump util-
          ity. It allows the user to store a window image
          displayed on an X11 screen (X Windows, Version 11,
          Release 4) as a Khoros viff file. It provides a con-
          venient way in which to create a Khoros viff file from
          other images that may be displayed.  It is especially
          useful when the raw image may not be readily available,
          but still displayable.  The raw image can be pulled off
          the X11 screen using getimage, and can be displayed
          with editimage (see editimage(1)), or processed with
          any of the image processing routines provided through
          Khoros.

          Note that the image created may not be a linear greys-
          cale image. Since many Khoros image routines expect to
          work on only linear greyscale images (for example, see
          vpostscr(1)), it may be necessary to linearize the
          image (see vmsquish(1)) before it can be used properly.

          getimage may be used in several ways:  (1) you may get
          a single window in its entirety from the screen, (2)
          you may get specified portion of the screen, regardless
          of the number of windows which it may include, (3) you
          may get a window by the window name or window id, (4)
          get the entire screen without prompting the user.

          The first method is quite simple.  Execute "getimage -o
          outfile".  Specify the window to be made into a Khoros
          viff file by clicking the mouse on the desired window.
          The Khoros image representation of the window will be
          stored in outfile.

          The second method is also simple.  Execute "getimage -o
          outfile -e true". Specify the image to be created by
          first clicking the mouse on the upper left hand corner
          of the desired portion of the screen.  IKeeping the
          mouse button down, move the mouse to the lower right
          hand corner of the desired portion of the screen;  the
          active portion will be indicated by rubber banding.
          The rubber-banded portion of the screen will be
          extracted into a Khoros viff file named outfile as soon
          as you release the mouse button.

          The third method will find the window with the
          appropriate name or window id and convert the contents
          of that window into a viff image.  Execute "getimage -o
          outfile -name bullwinkle" or "getimage -o outfile -name
          0xd0000d".  If the name or id of a window is unknown
          then a possible solution is to use the X11 utility pro-
          gram "xwininfo" to get the name or id of a specific
          window.  And then the output from this can then be used
          with getimage.  If the window can't be found then
          getimage will exit with an error message.  The differ-
          ence between this technique and the first is that this
          method doesn't require user intervention in selecting a
          window, which may be useful when getimage cannot grab
          the mouse or if getimage is being called from another
          program.

          The last method is to simply get the entire screen.
          Execute "getimage -o outfile -all true".  This will
          convert the entire screen without requiring the user to
          select the rootwindow.

          The other two getimage options are the bitmap "-b" and
          decoration "-decor" options.  The "-b" option simply
          takes a pixmap and dithers it down to a bit (binary)
          image before output the image.  The second "-decor"
          allows the user to select whether getimage should
          include the window decoration that most window managers
          puts on a window.  Thus, if the command "getimage -o
          outfile -decor false" is executed then only the con-
          tents of the window is dumped, and the window title
          bar, borders, etc, are left out.

REQUIRED ARGUMENTS
     -o     type: outfile
            desc: output image filename

OPTIONAL ARGUMENTS
     -e     type: boolean
            desc: extract image from screen?
            default: false

     -all   type: boolean
            desc: get the entire screen?
            default: false

     -name  type: string
            desc: name or id of window to dump
            default: null

     -b     type: boolean
            desc: output image in bitmap format?
            default: false

     -decor type: boolean
            desc: grab the screen (WM) decoration?
            default: true

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

EXAMPLES
     % getimage -o output_image.xv -e

SEE ALSO
     intro(1), verror(3), vgparms(3), vutils(3), lgetimage(3)
     putimage(1), vmsquish(1)

RESTRICTIONS
     1) Getimage will fail if it is not able to make a connection
     for the specified X display.
     2) It will also fail if it not able to grab the mouse and
     getimage needs user interaction selecting a window.  The
     mouse is instrumental in having the user select the window
     or portion of the window to extract.

     Note that images created are not guaranteed to be 100% com-
     patible with the rest of Khoros.  Some processing may be
     necessary before extracted images will be compatible with
     some Khoros routines (see description above).

     Note that 24 bit display are not yet supported.

COPYRIGHT
     Copyright 1991, University of New Mexico.  All rights
     reserved.

Khoros                    Release: 1.0                          1

