NAME
xgrabsc - grab rectangular screen images and store in files
SYNOPSIS
xgrabsc [-d display] [- id windowId] [ - o outputFile] [ -
s seconds] [ - post seconds] [ - b percent] [ -
and andBits] [ - or orBits] [ - page widthxheight-
hmarg-vmarg] [ - bell -grab -verbose -bdrs -nobdrs
-key -stretch -root -click
-reverse -bw -mdither -dither -halftone -bwlim RGBwidth
-ps -cps -simple -xwd -bm -bm2 -bm3 -puzzle
-bin -comp -eps -l -limit -preview -prev -pre-
viewonly -colproc]
DESCRIPTION
xgrabsc lets you grab arbitrary rectangular images from an X
server and writes them to standard output in a variety of
formats.
Command line options also allow reduction of colormaps,
halftoning and dithering of color images, and direct mapping
of color images to monochrome.
Options must be seperated with spaces or tabs. They may be
preceded with a dash, but this optional and provided for
Un*x addicts. Many may also be prefixed with 'no', or an
additional dash, to turn them off.
The default output format is gray-scale non-encapsulated
Postscript, with image compression (if image compression
significantly reduces the amount of output).
If you desire an output format not produced by xgrabsc, try
using the PBM package by Jef Poskanzer to convert xgrabsc to
that format. PBM can read xgrabsc's XWD output and convert
it to a lot of different formats.
GENERAL OPTIONS
-d displayName or -display displayName
Use an alternate display. If no display is speci-
fied on the command line, xgrabsc looks for the
environment variable DISPLAY for the name of the
display and screen to grab from. Note that you must
have permission to access the display on another
computer.
-bell The display's bell is normally rung while the screen
is being accessed. This turns the bell on or off
(-nobell will turn it off).
-grab Enable server grabs. Normally xgrabsc will "grab"
the server so that the screen is frozen while a
rectangle is selected and the image is extracted.
If the screen is not frozen, rubber-banding may
cause video droppings on portions of the screen that
are changing. Use -nograb to turn off server grabs.
-o output-file or -output output-file
Write output to output-file instead of standard out-
put. The output-file name, minus directory and
extension, is used as the internal name for the
image in formats supporting image names.
Postscript, xwd, pixmap and bitmap formats all sup-
port image names.
-s seconds or -sleep seconds
Sleep for seconds seconds before commencing opera-
tion. This should be used if you need some time to
get the target image ready.
-post seconds
Sleep for seconds seconds after window/rectangle
selection. This is commonly used to pop up menus
after a window has been selected but before xgrabsc
takes its snapshot.
-verbose
Display processing information on standard error
output (stderr).
SELECTION OPTIONS
-id window ID
Dump the window with the given ID.
-key Select the window under the mouse when the Control key
is pressed. This option is normally used in getting
images of menus. Pop up the menu, optionally move the
pointer to the window containing the menu, and strike
the Control key to begin the dump.
-root
Dump the entire screen (root window).
-stretch
Use rubber-band rectangle to select region to grab.
This is the default.
-click
Wait for a click on a window and dump the selected win-
dow.
IMAGE PROCESSING OPTIONS
-nobdrs or -noborders
Remove window-manager borders from window images. This
option applies only to selection by ID (-id) or xwd-
style selection (-click).
-bdrs or -borders
Include window-manager borders in window images. This
option applies only to selection by ID (-id) or xwd-
style selection (-click). Use -nobdrs or -noborders to
turn it off.
-b percent or -brighten percent
brighten or darken the image by percent. Percentages
are given as integers. 100 is the base and a larger
number will brighten the image while a smaller number
will darken the image.
-and andBits
Clear all colormap bits up to the given plane. This
has the effect of darkening the image somewhat and
shrinking the apparent depth of the image (and, conse-
quently, the size of the color table). AndBits should
be in the range [1-8] inclusive.
-or orBits
Set all colormap bits up to the given plane. This
brightens the image somewhat and also shrinks the
apparent depth of the image. When both -A and - O are
specified, ANDing will occur before ORing.
-reverse
Reverse the colors in the image which are "near" Black or
white. Black and white are reversed, and the colors are
maintained. Only colors nearer to black and white than -bwlim
are reversed.
-bwlim RGBwidth
Each color (RGB) has value between 0 and 65535 for each pixel.
This parameter determines how far from absolute black or white
a color has to be to retain its value and not be reversed when
the -reverse option is selected. Useful for grabbing color on
black screens for printing.
-bw Convert the source color image to a monochrome bitmap.
All colors falling below the average color intensity
are mapped to black. Others are mapped to white.
-halftone
Convert the source color image to a halftoned monchrome
bitmap. Resolution is maintained by increasing the
size of the image by a factor of four on both axes.
-mdither
Convert the source color image to a dithered monochrome
bitmap. This is like halftoning, but resolution is
sacrificed to keep the resulting image the same size as
the original. The matrix dithering algorithm used with
this option is most suitable for line-drawings and
text. For more complex graphics the -dither option is
recommended.
-dither
Convert the source color image to a dithered monochrome
bitmap with the Floyd-Steinberg algorithm.
-nodither
Turns off any dithering. Use this if your XGRABSC
environment variable specifies dithering and you want
to override it to produce an undithered image.
OUTPUT FORMAT OPTIONS
-cps Write output in Postscript format using the colorimage
operator for color printers. Color to grayscale
conversion is bundled into the output so you can actu-
ally use either color or cheaper grayscale printers.
For monochrome displays, the -ps option will give more
compact output.
-ps Write output in Postscript format for greyscale
printers. The number of bits per Postscript sample is
determined by the depth of the image.
-xwd Write output in xwd format. Use this if you want to
convert to another output format with Pbm+.
-bm Write the output in X Bitmap format if the image is
black and white, or X Pixmap format if the image is
gray or color.
-bm2 Write the output in X Bitmap format if the image is
black and white, or X Pixmap format 2 if the image is
gray or color. -bm3 Write the output in X Bitmap for-
mat if the image is black and white, or X Pixmap format
3 if the image is gray or color.
-puzzle
Write output in a format suitable for loading into the
puzzle program (see example below).
POSTSCRIPT OPTIONS
-compress
Enable or suppress Postscript image run-length encod-
ing. Postscript output is normally compressed to
minimize the size of output. If your printer can't
handle compressed output, you should use -nocompress to
turn off compression.
-eps Create Encapsulated Postscript output, rather than
normal stand-alone Postscript. This adds EPSF header
comments and removes all scaling and translation of the
image.
-l or -landscape
Use landscape layout (with page width and height
exchanged) for Postscript output. This option is
ignored if Encapsulated Postscript output is requested.
Width and height may be specified with the -page
option.
-bin Write Postscript output in binary rather than using
hexidecimal encoding. This causes the image portion of
the output to use half as much space, decreasing
transmission time to the printer. Note that not all
print spoolers can handle 8 bit binary data, so this
may not work on your system!
-limit
For Postscript output, check printer memory availabil-
ity before attempting to print an image (the code to
perform the checks is integrated into the output of
xgrabsc). This is turned off if Encapsulated
Postscript output is requested, and may be disabled
completely when building the xgrabsc program. On the
command line it may be turned off with -nolimit.
-preview or -prev
Selects Encapsulated Postscript output with an EPSI
preview image in its header. The preview image is
dithered to black and white. Programs such as xfig can
display these preview images. Ghostscript and other
Postscript interpreters can be used to preview EPS
files without generating preview images, so if you have
one of these packages there is not much point in using
this option.
-previewonly
Like -preview but writes only the preview portion, not
the postscript image. This may be used to add the pre-
view to an existing EPS file after having displayed it
using a PostScript interpreter.
-page widthxheight-marginWidth-marginHeight
Sets the size of the paper and the borders you desire
around the edge of the paper. Xgrabsc will reduce the
image if necessary to keep it within the borders you
specify. The default page size and margins are set
when xgrabsc is built. Measurements are in inches
(e.g., 8.5x11.0-0.5-0.5)
PROCESSING ORDER
It is helpful to know the order of processing when multiple
processing options are given on the command line.
Processing is done in five phases: 1) set up, 2) obtain
image, 3) process colors, 4) poly->monochrome conversions,
and 5) output conversion.
The set-up phase includes processing command-line options,
sleeping, connecting to X-Windows, freezing the screen, and
grabbing the mouse if necessary.
If the mouse is grabbed for rubber-banding, an upper-left-
corner cursor is displayed until the left mouse button is
pressed. A lower-left-corner cursor is then displayed while
drawing rubber-rectangles until the mouse button is
released.
If the mouse is grabbed for xwd-style window selection, an
xwd-style cursor is displayed until the left mouse button is
pressed.
The mouse is then released.
The bell is then run and the image is pulled from the
screen.
Following the image-grab, the bell is run twice and the
screen is released.
If the image is not monochrome, the color manipulation func-
tions are then applied in this order: brighten, AND, and OR,
reverse.
Only one polychrome to monochrome conversion is allowed. If
none of these is chosen, the color table of a polychrome
image is compressed in preparation for output conversion.
The output stream is then opened and the image is written in
the selected output format.
ENVIRONMENT
XGRABSC - specifies command line arguments to be processed
before those actually entered on the command line.
DISPLAY - specifies the name of the display that xgrabsc
should grab from.
EXAMPLES
The simplest form of use, giving Postscript output, is
xgrabsc >outfile.ps
To write output in Postscript format and send to the
printer, use
xgrabsc | lpr
It is sometimes helpful to brighten an image somewhat before
it is formatted for Postscript output. E.g., to brighten by
30%
xgrabsc -b 130 | lpr
If your printer supports color, and your display is color,
you can have xgrabsc generate color output instead of gray
scale:
xgrabsc -cps | lpr
The default Postscript output attempts to scale the image so
that it will all fit on one page, and is centered on the
page. If you are grabbing images to include in documents,
such as with FrameMaker, you should ask for Encapsulated
Postscript output with the -eps switch. For example:
xgrabsc -eps -o image1.eps
To select an entire window, write output in puzzle format
and read into the puzzle program, use the commands
xgrabsc -click -puzzle >outfile.pzl
puzzle -picture outfile.pzl
To have xgrabsc sleep for three seconds before rubber-
banding, display processing information, and have the result
displayed with xwud,
xgrabsc -xwd -verbose -s 3 | xwud
To grab an image from another server and then reduce the
colormap to three bits by ANDing, use
xgrabsc -d other:0.0 -and 5 -bm >outfile.xpm
You will, of course, have to go to the other machine to
select the image with that machine's mouse.
LIMITATIONS
Colormaps larger than 256 entries are not currently sup-
ported. This means that it won't work with your fancy 24-bit
display.
The default screen visual is used as the visual for the
image. Visuals are associated with particular windows, and
xgrabsc pretends ignorance about any windows but the root.
This software has been tested with StaticGray and 8-plane
PseudoColor on DECStations (using both UWS 2.2 and X11
Release 4). It has also been tested with 8-plane Pseu-
doColor on Sun SparcStations and various other platforms
using X11 Release 4 and Release 5.
X11 Pixmap format is rather verbose. You may want to run
large images through the compress utility before storing
them in a file. E.g.,
xgrabsc -bm | compress >outfile.xpm.Z
AUTHOR
Bruce Schuchardt
Servio Corporation
bruce@slc.com
ACKNOWLEGEMENTS
Some of the source code for xgrabsc came from the xloadimage
project by Jim Frost (jimf@saber.com) and others. Jim's
copyright has been included both here and in the source
code.
The idea for using run-length encoding for Postscript output
came from the xwd2ps project by Robert Tatar and Craig A.
McGowan, as did the colorimage hack for monochrome display
devices.
The ad2c.sed script that makes it possible to let you run
xgrab without installing XGrab.ad everywhere is part of the
ad2c package developed by George Ferguson.
CONTRIBUTORS
Johan Garpendal did the initial color postscript work.
Hal R. Brand wrote the binary Postscript enhancements.
Yves Arrouye wrote the EPS Preview and page-configuration
enhancements.
COPYRIGHT
Copyright (c) 1990-92 Bruce Schuchardt
Xgrabsc is copywritten material with a very loose copyright
allowing unlimited modification and distribution if the
copyright notices are left intact. Various portions are
copywritten by various people, but all use a modification of
the MIT copyright notice. Please check the cpyright.h for
complete copyright information. The intent is to keep the
source free, not to stifle its distribution, so please write
to me if you have any questions.
THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABIL-
ITY AND FITNESS, IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAM-
AGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TOR-
TIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE
OR PERFORMANCE OF THIS SOFTWARE.
SEE ALSO
X(1X), xhost(1), xwd(1X), xwud(1X), xwd2ps(1X),
xloadimage(1X), xpm(1X), xpr(1X), puzzle(1X), compress(1),
uncompress(1), xv(1X)
Man(1) output converted with
man2html