xgrabsc - grab rectangular screen images and store in files
[ -d display
] [ -colorwin windowId
[ -o outputFile
] [ -s seconds
] [ -b percent
] [ -or orBits
] [ -bell -grab
-verbose -borders -frame -key -stretch -root -click -coords
widthxheight+x+y -offset widthxheight+x+y
-reverse -bw -mdither -dither -halftone
-ps -cps -simple -xwd -ppm -xwdxy -bm -bm2 -bm3 -puzzle
-bin -comp -eps -l -limit -preview -prev -previewonly -colproc ]
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 PPM and XWD output formats and convert them to a lot of different
- -d displayName or -display displayName
Use an alternate display. If no display is specified 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.
- The display's bell is normally rung while the screen is being accessed.
This turns the bell on or off ( -nobell will turn it
- 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.
Server grabs are automatically disabled if verbose output is
requested to avoid freezing up the system.
- -o output-file or -output output-file
Write output to output-file instead of standard output. 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 support image names.
- -s seconds or -sleep seconds
Sleep for seconds seconds before commencing operation. 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.
- Display processing information on standard error output (stderr).
- -id window ID
- Dump the window with the given ID. ID numbers can be in decimal, or
hexidecimal (prefixed with "0x"). The name of a window can be
given instead of an ID number, and xgrabsc will look for the first window
with that name.
- 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.
- Dump the entire screen (root window).
- Use rubber-band rectangle to select region to grab. This is the
- Wait for a click on a window and dump the selected window.
- -coords widthxheight+x+y
- Selects the given area of the screen, without mouse or keyboard
interaction. Use this if you need to grab the same area of the screen over
and over again. Standard X coordinate notation can be used, but a width
and height must be given.
- -coords widthxheight+x+y
- Offsets the area to be grabbed by x@y and changes the area's width and
height to widthxheight. Using this you can grab a sub-area of the source
area, or even grab an area adjacent to the source area.
- -nobdrs or -noborders
Remove window borders from window images. This option applies only to
selection by ID ( -id) or xwd-style selection (-click).
Note that Motif-style window frames are not window borders. To remove these
you should use the -noframe option. The xgrab window interface's
Include Borders option removes both frames and borders.
- -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, consequently, 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 the colors in the image. The bits of each color used in the image
- Convert the source color image to a monochrome bitmap. All colors falling
below the average color intensity are mapped to black. Others are mapped
- 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
- 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.
- Convert the source color image to a dithered monochrome bitmap with the
- Turns off any dithering. Use this if your XGRABSC environment
variable specifies dithering and you want to override it to produce an
- -colorWin windowId
- Specifies a window id (in hex) whose colormap should be used for the
grabbed image. Generally xgrabsc will find the correct colormap for your
image. If you have lots of private colormaps around you may need to use
this option to ensure that xgrabsc selects the proper one.
ID numbers can be in decimal, or hexidecimal (prefixed with "0x").
The name of a window can be given instead of an ID number, and xgrabsc
will look for the first window with that name.
- Write output in Postscript format using the colorimage operator for
color printers. Color to grayscale conversion is bundled into the output
so you can actually use either color or cheaper grayscale printers. For
monochrome displays, the -ps option will give more compact
- Write output in Postscript format for greyscale printers. The
number of bits per Postscript sample is determined by the depth of the
- Write output in Portable Bitmap format. Unix image viewers such as
xv and ImageMagick can accept this format, and the
Portable Bitmap package can convert this to many other image
- Write output in xwd format. Use this if you want to convert to
another output format with Pbm+.
- Write output in xwd -xy format. This is like xwd, but allows black
- white images to be written with eight pixels per byte instead of the
default one pixel per byte. While xwud and xpr will handle this format,
some programs will not.
- 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.
- 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 format if the image is black and white, or X Pixmap format 3 if the
image is gray or color.
- Write output in a format suitable for loading into the puzzle
program (see example below).
- Enable or suppress Postscript image run-length encoding. 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
- 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.
- 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
- For Postscript output, check printer memory availability 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
- -preview or -prev
Selects Encapsulated Postscript output with an EPSI preview image in its
header. The preview image, if necessary, is dithered to black and white
either with a default dithering algorithm or one you specify on the
command line (e.g., -mdither). Programs such as Frame use preview
images to display the postscript image during editing sessions. If you
don't have a preview image, Frame will display a blank rectangle. The
image will print OK but you won't see it while editing.
- Like -preview but writes only the preview portion, not the
postscript image. This may be used to add the preview 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)
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
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 functions 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
The output stream is then opened and the image is written in the selected output
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.
The simplest form of use, giving Postscript output, is
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.
If you know the name or ID number of the window you want to snapshot you can
direct xgrabsc to that window on the command line. Utilities like xlswins or
xwininfo can be used to find the names and ID numbers of windows.
To grab an mpegplay image and display it in xwud, use xgrabsc -xwd -id
"MPEG Play" | xwud
You can also specify a sub-region to grab, as in xgrabsc -xwd -id "MPEG
Play" -offset 100x100+10+10 | xwud
Grabbing an area with the /fI-coords/fP option will use the root window's
colormap unless you specify an alternate window to use for color processing.
If your display allows more than one colormap to be installed at once and you
are displaying an mpeg video that uses a private colormap, your output using
the /fI-coords/fP command would be technicolor without a /fI-colorwin/fP
option specifying the mpeg window. E.g., xgrabsc -xwd -coords 300x300+10+10
-colorwin "MPEG Play" | xwud
Colormaps larger than 256 entries are not currently supported. 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 PseudoColor 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
utility before storing them in a file. E.g.,
xgrabsc -bm | compress >outfile.xpm.Z
GemStone Systems, Inc.
Some of the source code for xgrabsc came from the xloadimage project by Jim
Frost (firstname.lastname@example.org) 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.
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
Yves Arrouye wrote the EPS Preview and page-configuration enhancements.
Copyright (c) 1990-93 Bruce Schuchardt
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 MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE
AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
X(1X), xhost(1), xwd(1X), xwud(1X), xwd2ps(1X), xloadimage(1X), xpm(1X),
xpr(1X), puzzle(1X), compress(1), uncompress(1), xv(1X)