xgrabsc.man

speech signal process tools

.\"========================================================================
.\"
.\" Name - xgrabsc.man
.\"
.\" Version:	1.6
.\"
.\" ccsid:	@(#)xgrabsc.man	1.6 - 7/26/91 15:15:50
.\" from: 	ccs/s.xgrabsc.man
.\" date: 	7/26/91 15:16:11
.\"
.\" Copyright (C) 1990, Bruce Schuchardt
.\" See the end of this document for full copyright information.
.\"
.\" Description:  Man page for xgrabsc
.\"
.\"========================================================================
.\"
.TH XGRABSC 1X
.\"
.SH NAME
xgrabsc \- grab rectangular screen images and store in files
.\"
.SH SYNTAX
\fIxgrabsc\fR \ [options]
.\"
.SH DESCRIPTION
\fIxgrabsc\fR lets you grab arbitrary rectangular images from an
X server and writes them to standard output in a variety of formats.
.PP
Command line options also allow reduction of colormaps, halftoning
and dithering of color images, and direct mapping of color images
to monochrome.
.PP
The default output format is gray-scale non-encapsulated Postscript.
.SH OPTIONS
.TP 8
-d \fIdisplayName\fP
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.
.TP
-g
Silence the bell that is normally rung while the screen is being accessed.
.TP
-i \fIwindow ID\fP
Dump the window with the given ID.
.TP
-n
Inhibit 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.
.TP
-o \fIoutput-file\fP
Write output to \fIoutput-file\fP instead of standard output.
.TP
-r
Dump the entire screen (root window).
.TP
-s \fIseconds\fP
Sleep for \fIseconds\fP seconds before commencing operation.  This
should be used if you need some time to get the target image ready.
.TP
-v
Display processing information on standard error output (stderr).
.TP
-w
Use \fIxwd\fP style window selection and dump selected window.
.sp 3
.TP
-b \fIpercent\fR
brighten or darken the image by \fIpercent\fR.  Percentages are given
as integers.  As in \fIxloadimage\fR, 100 is the base and a larger
number will brighten the image while a smaller number will darken the
image.
.TP
-A \fIandBits\fR
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).  \fIAndBits\fR should
be in the range [1-8] inclusive.
.TP
-O \fIorBits\fR
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.
.TP
-B
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.
.TP
-H
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.
.TP
-D
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 \fI-F\fR option is recommended.
.TP
-F
Convert the source color image to a dithered monochrome bitmap with
the Floyd-Steinberg algorithm.
.sp 3
.TP
-C
Write output in \fIPostscript\fP 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
\fI-P\fP option will give more compact output, and is the preferred format.
.TP
-P
Write output in \fIPostscript\fP format.  Output will be run-length-encoded
if encoding will result in any savings unless you use the \fI-c\fP option.
The number of bits per Postscript sample is determined by the depth of the
image.
.TP
-c
Suppress Postscript image run-length encoding.  This option is ignored
unless the \fI-P\fP Postscript-output option is also specified.
.TP
-e
Create Encapsulated Postscript output, rather than normal vanilla
Postscript.  This adds EPSF header comments and removes all scaling and
translation of the image.  You must also select the type of Postscript
output you want to have with the \fI-P\fP or \fI-C\fP options.
.TP
-W
Write output in \fIxwd\fP format.
.TP
-X
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.
.TP
-Z
Write output in a format suitable for loading into the \fIpuzzle\fP
program (see example below).
.sp 2
.SH PROCESSING ORDER
It is helpful to know the order of processing when multiple processing
options are given on the command line.
.PP
Processing is done in five phases:  1) set up, 2) obtain image,
3) process colors, 4) poly->monochrome conversions, and 5) output conversion.
.PP
The set-up phase includes processing command-line options, sleeping,
connecting to X-Windows, freezing the screen and grabbing the mouse.
.PP
After the mouse is grabbed, rubber-banding occurs until a mouse button
is released.  The image is then pulled from the screen and the mouse
and screen are released.
.PP
If the image is not monochrome, the color manipulation functions are
then applied in this order: brighten, AND, and OR.
.PP
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.
.PP
The output stream is then opened and the image is written in the selected
output format.
.sp 2
.SH ENVIRONMENT
XGRABSC - specifies command line arguments to be processed before those
actually entered on the command line.
.PP
DISPLAY - specifies the name of the display that xgrabsc should grab from.
.sp 2
.SH EXAMPLES
The simplest form of use, giving Postscript output, is
.sp
.ti +5
xgrabsc >outfile.ps
.sp
.PP
To write output in \fIPostscript\fP format and send to the printer,
use
.sp
.ti +5
xgrabsc | lpr
.sp
It is sometimes helpful to brighten an image somewhat before it is
formatted for Postscript output.  E.g., to brighten by 30%
.sp
.ti +5
xgrabsc -Pb 130 | lpr
.sp
.PP
If your printer supports color, and your display is color, you can
have xgrabsc generate color output instead of gray scale:
.sp
.ti +5
xgrabsc -C | lpr
.sp
.PP
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 \fI-e\fP
switch.  For example:
.sp
.ti +5
  xgrabsc -eC -o image1.eps
.sp
Encapsulated Postscript files may be printed on a printer, but
be aware that xgrabsc does not include the colorimage operator in
Encapsulated Postscript files, so color dumps can only be printed
on color printers.  If you know something about programming, you
can edit a non-eps dump file and extract the colorimage operator
from it and insert it into your eps file and then send the modified
file to the printer.
.PP
To select an entire window, write output in \fIpuzzle\fP format
and read into the puzzle program, use the commands
.sp
.ti +5
xgrabsc -wZ >outfile.pzl
.br
.ti +5
puzzle -picture outfile.pzl
.sp
.PP
To have xgrabsc sleep for three seconds before rubber-banding, display
processing information, and have the result displayed with xwud,
.sp
.ti +5
xgrabsc -Wvs3 | xwud
.sp
.PP
To grab an image from another server and then reduce the colormap
to three bits by ANDing, use
.sp
.ti +5
xgrabsc -dother:0.0 -A5 -X >outfile.xpm
.sp
You will, of course, have to go to the other machine to select the
image with that machine's mouse.
.sp 2
.SH LIMITATIONS
Colormaps larger than 256 entries are not currently supported. This
means that it won't work with your fancy 24-bit display.  Use xwd
and the xwd2ps utility for now.
.PP
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.
.PP
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.
.PP
X11 Pixmap format is rather verbose.
You may want to run large images through the \fIcompress\fP utility
before storing them in a file.  E.g.,
.sp
.ti +5
xgrabsc | compress >outfile.xpm.Z
.sp
.SH AUTHOR
.nf
     Bruce Schuchardt
    Servio Corporation
      [e-mail]
.fi
.sp 2
.SH ACKNOWLEGEMENTS
.PP
Some of the source code for xgrabsc came from
the xloadimage project by Jim Frost ([e-mail]) and others.  Jim's
copyright has been included both here and in the source code.
.PP
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.
.sp 2
.SH COPYRIGHT
Copyright (c) 1990, 1991 Bruce Schuchardt
.PP
\fIXgrabsc\fR 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 source 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.
.PP
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.
.s 2
.SH SEE ALSO
X(1X), xhost(1), xwd(1X), xwud(1X), xwd2ps(1X), xloadimage(1X), xpm(1X),
xpr(1X), puzzle(1X), compress(1), uncompress(1)