.TH xv "" "" "X Application"
.PC "Display and manipulate images on X11 displays"
\fBxv [\fIoption ...\^\fB] [\fIfilename \fB[\fIfilename...\^\fB]]\fR
.PP
.B xv
is an X11 program that displays images in the GIF, PBM, PGM, PPM,
X11 bitmap, and PM formats on one-, four-, six-, eight-,
24-, and 32-bit X displays.
.SH Overview
.B xv
displays one image at a time in an output window.
You can arbitrarily stretch or compress the window, and the picture
will be rescaled to fit.
You can rotate the picture in 90\(de steps.
You can repeatedly crop a picture \(em that is, define a rectangular
``region-of-interest'' and ``throw away'' what lies outside that region.
You can magnify any portion of the picture by
any amount, up to the maximum size of your screen.
.PP
.B xv
lets you click on the picture to determine pixel RGB values and
X,Y coordinates.
You can perform arbitrary ``gamma correction'' on the picture
both in RGB space and HSV space.
You can specify the maximum number of colors that
.B xv
should use, for some interesting visual effects.
You can have the program produce a stippled version of the picture
using black-and-white, or any other pair of colors.  
.PP
.B xv
can write images in a variety of formats, with many of the
modifications you may have made to the picture saved as well.
You can use
.B xv
to do format conversion.
.B xv
will also automatically  uncompress \fBcompress\fP\'d files,
as well as read files from stdin.
.SH "Using the Program:
To launch
.BR xv ,
type \fBxv \fIfilename\fR, where
.I filename
is the name of the file that holds the image you wish to display
After a short delay, a window
will appear with the desired image displayed in it.
If you change the size of the window,
.B xv
rescales the picture to fit the window.
.PP
Clicking and dragging the left-mouse button inside the image window displays
pixel information.
The first two numbers are the
.B X
and
.I Y
offsets, in pixels, from the top-left corner of the image.
The first group of three
numbers are the red, green, and blue values of that pixel from the original
data (after any 24-bit to eight-bit conversions).
The second group of
three numbers are the red, green, and blue values of that pixel
.I after
any gamma correction (and the \fB\-rv\fP option).
If you actually want to measure some
pixels, it will probably help to crop to a small region, and expand that
region quite a bit, to the point where you can see individual pixels.
.PP
If you type
.B h
or
.BR ? ,
or click the right-mouse button inside this window,
the Control Box window appears.
This box lists the files you invoked on the
.B xv
command line, and a number of buttons.
.SH "The Control Box"
The following image shows an
.B xv
image window and its Control Box window:
.PH 1 1 \*(XD/xv.eps
Please note that the image window is a little out of focus because it was
dithered onto a monochrome screen.
.PP
Most of the buttons in the control box let you adjust the size of the
currently shown picture.
You can either click the button, or type a keyboard equivalent inside
.I any
.B xv
window (except the Save Box window, which is described below).
Note that the ``resizing'' controls do not modify the picture in any way:
They simply change the way the picture is displayed, by duplicating or
dropping pixels from the original picture to produce an image of the desired
size.
As you expand images, they become ``chunkier.''
.PP
The following introduces the buttons on the Control Box.
Each entry gives a button plus its keyboard equivalent:
.IP \fK(Max_Size)\fR
.IS \fBM\fR
This redraws a picture so that it completely fills the screen.
Be warned that this might take a while, depending on the speed of your machine. 
It also may cover all the other
windows on the screen, including the control window.
If this happens, you can
bring the control window back to the foreground
by clicking the right-mouse button once or twice in the picture window.
.IP \fK(Normal)\fR
.IS \fBN\fR
Return the picture to its normal size.
.B xv
defines
``normal size'' as a one-to-one mapping between pixels in the image and
pixels on the screen
(e.g., if you have a 320\(mu200 image, this command
sets its ``on-screen'' size to 320\(mu200).
.IP
The only exception to this behavior is when the image is larger than your
screen.
In this case,
.B xv
``halves'' the picture until it fits.
(For example, if you tried to display a 1000\(mu600 image on an 800\(mu600
screen,
this command would set the on-screen size to 500\(mu300.)
.IP \fK(Dbl_Size)\fR
.IS \fB>\fR
Double the width and height of the picture.
.B xv
will not make a picture larger than your screen.
For example,
if you have a 900\(mu100 image and a 1000\(mu800 screen,
doubling would result in
a picture size of 1000\(mu200 (the doubling of the ``900'' was clipped).
.IP \fK(Half_Size)\fR
.IS \fB<\fR
Halve the width and height of the picture.
.IP \fK(+10%)\fR
.IS \fB.\fR
Add 10% to the width and height of the picture.
Again,
.B xv
will not make a picture larger than your screen.
.IP \fK(-10%)\fR
.IS \fB,\fR
Subtract 10% from the width and height of the picture.  
.IP
Please note that the
.B +10%
and
.B \-10%
buttons have no concept of an ``original size''
to use as an increment/decrement basis.
They only expand or shrink the current picture by 10% of its current size.
Therefore, they are
.I not
complementary.
If, for example, you have a 100\(mu100 picture,
.B +10%
will make it into a 110\(mu110 picture.
If you then click
.BR \-10% ,
you will have a 99\(mu99 picture
(because 10% of 110 = 11 ; and 110 \- 11 = 99).
.IP \fK(4x3)\fR
.IS \fB4\fR
Resize the picture so that the ratio of width to height is equal to 4 to 3.
This is useful because most images were meant to fill the screen of
whatever they were generated on, and nearly all video
screens have an aspect ratio of 4:3.
By issuing this command, the picture
will be stretched so the proportions of things will (possibly) look correct
on your X display.
This is particularly obvious on pictures that have
bizarre sizes, e.g., the 600\(mu200 pictures presumably meant for CGA.
.IP \fK(Aspect)\fR
.IS \fBA\fR
Apply the ``default aspect ratio'' to the picture.
This is done automatically when the image is first loaded.
Normally, the default aspect ratio is 1:1, but certain GIF files may have
an aspect ratio encoded in them.
You can also set the default aspect ratio
via a command-line argument or an X resource.
Use this button to fine-tune a picture that you have stretched by hand.
.IP \fK(Maxpect)\fR
.IS \fBM\fR
Make the picture as large as will fit on the screen,
but preserve the aspect ratio.  
.IP \fK(Turn_R)\fR
.IS \fBT\fR
Rotate the picture 90\(de clockwise.
Note that when you rotate the picture, you are rotating the
.I entire
image, even if you are viewing only a small, cropped section of it.
.IP \fK(Turn_L)\fR
.IS \fBT\fR
Rotate the picture 90\(de counter-clockwise.
.IP \fK(Gamma)\fR
.IS \fBG\fR
Opens up the Gamma Box.
This box is described below.
.IP \fK(Info)\fR
.IS \fBI\fR
Open up the Info Box.
This box is described below.
.IP \fK(Save)\fR
.IS \fBS\fR
Open up the Save Box.
This box is described below.
.SH Cropping
In addition to being able to resize or rotate an entire image,
you can also resize or rotate any selected portion of an image.
To do so, press the center-mouse button in the picture window and drag it;
this draws a rectangle.
At the same time,
.B xv
writes the label of the
.B Crop
button in normal text, which indicates that
.B xv
has enabled its
.B Crop
command.
.PP
To fine-tune the cropping rectangle, use the arrow keys on your keyboard.
The arrow keys move the cropping rectangle in
the requested direction, preserving its current size.
To change the size of the cropping rectangle, press the
.B <shift>
key and an arrow key simultaneously:
.DS
.ta 0.5i 1.5i
	\fB<shift>\fR\*(LA	Makes the rectangle narrower
.sp 2p
	\fB<shift>\fR\*(UA	makes the rectangle shorter
.sp 2p
	\fB<shift>\fR\*(RA	Makes the rectangle wider
.sp 2p
	\fB<shift>\fR\*(DA	makes the rectangle higher
.DE
.PP
For precise cropping, make the Info Box visible.
This box will tell you the position and size of the cropping rectangle,
in image coordinates.
.PP
If you click the
.B Crop
button (or the
.B C
key),
.B xv
erases the parts of the picture that lie outside the rectangle,
and shrinks the window to the size of the cropped portion of the image.
It then rewrites the label of the
.B Crop
button in ``faint'' letters;
and writes the label of the
.B UnCrop
button in normal text, to show that it has enabled that command.
.PP
You can manipulate this portion of the image exactly as if it were the
entire image.
You can even draw another crop it again.
.PP
Clicking the
.B UnCrop
button (or the
.B U
key) returns the entire image to the screen.
.B xv
tries to keep the current expansion,
but if that would result in a picture larger than the screen,
it will use the normal size, as defined above in the description of the
.B Normal
button.
.PP
The
.B AutoCrop
button (or the
.B A
key) crops off any constant borders that exist in the picture.
It crops the image to smallest rectangle that encloses
the ``interesting'' section of the picture.
.SH "Multiple Files"
If, when you started
.BR xv ,
you specified more than one file name, you can use the file-selection
controls in the Control Box.
.PP
The Control Box names the files that you named on the
.B xv
command line.
It shows them without any path information, as if filtered through the command
.BR basename .
.PP
The Control Box highlights the name of the file whose image is being displayed.
If there is more than one screenful of file names,
.B xv
enables a scrollbar on this portion of the Control Box.
You can manipulate the scrollbar in the usual manner.
.PP
To display a image, double-click on its file name.
.B xv
removes the current picture and displays the one you request, if possible.
.B xv
cannot load the selected picture, it redisplays the previous picture.
.PP
If there are multiple files  and you are not at the end of the list,
.B xv
enables the
.B Next
button on the Control Box.
Clicking this button (or pressing \*(RT or \*(SP)
closes the current picture and brings up the next one.
This is the normal way to view multiple images.
.PP
If there are multiple files and you are not at the beginning of the list,
.B xv
enables the
.B Previous
button on the Control Box.
Clicking this button (or pressing the
.B <Backspace>
or
.B <del>
keys) close the current picture and brings up the previous one.
.PP
Note that all of these commands work whether or not the
Control Box is visible (although if it is not visible,
you must use the keyboard equivalents).
.SH "Quitting the Program"
To exit from
.BR xv ,
click the 
.B Quit
button or press the the `Q' key.
.SH "The Info Box"
The Info Box displays several bits of information.
In addition to credits and a revision date,
the Info Box displays information about the currently displayed picture:
its file name, format, size, and resolution.
This information is available
early in the loading process, and is displayed as soon is it is known.
The rest of the lines are filled in after the picture has been loaded.
.PP
The
.B Cropping
line displays the coordinates of the cropping rectangle.
Normally, this line says
.BR none ,
but if you draw a cropping rectangle on the picture (as described above,
in the discussion of cropping),
the Info Box displays the size and position of the rectangle
in image coordinates:
the first pair of numbers gives the width and height of the rectangle;
and the second pair of numbers gives the coordinates of the rectangle's
upper-left corner, as an offset from the upper-left corner of the entire image.
.PP
The
.B Expansion
line shows the effects of any stretching that you may have
done to the picture.
The first pair of numbers represent the stretching as
a ratio of two scaling factors.
For example, the values ``2\(mu3'' indicates that the image or sub-image
has been made twice as wide as normal and three times as high as normal.
Normally, these are ``1\(mu1'', which indicates
that one data pixel maps to one screen pixel in both X and Y axes.
The second pair of numbers
(the ones in parenthesis) simply display the current screen size of the image.
.PP
The
.B Colors
lines displays how successful the color allocation schemes were.
Normally,
.B xv
uses a three-pass color-allocation algorithm.
In the first pass, the program requests every color that the picture
requires to be displayed properly.
The results of this attempt appear on the first
.B Colors
line.
If everything worked out perfectly, this line says,
``Got all \fIx\fR desired colors.'' and may append ``(\fIy\fR unique)''.
In this string,
.I x
is the number of colors that the picture required.
If the ``unique'' string is appended, some of the colors duplicate others,
and therefore the picture only really needs (and was only allocated)
\fIy\fR colors.
.PP
If
.B xv
could not get all the colors it wanted, it run the second-pass
color-allocation routine.
In this pass, the program ask the display what colors
it has available in its color map,
determines which of those colors are ``close'' to the desired colors,
and tries to allocate those colors.
.B xv
displays the message
.DM
	Got \fIx\fP 'close' colors.
.DE
.PP
if it performed the second pass allocation.
This is so that you will know that the image is not displayed at its best.
.PP
Finally, if even that did not work,
.B xv
attempts to ``borrow'' colors from the color map
without actually allocating them.
These colors are not owned by the program, and they can change without
.BR xv 's
knowledge.
If it executes this third pass,
.B xv
displays the message:
.DM
	'Borrowed' \fIx\fP colors.
.DE
.PP
It should be noted that the options
.BR \-noglob ,
.BR \-perfect ,
and
.B \-rw
modify the way color allocation is handled in
.BR xv ,
and therefore modify what appears in the Info Box.
For example, if you specify
.BR \-noglob ,
.B xv
never borrows colors, so you will never see a third-pass line.
.PP
Finally, the Info Box displays warning messages that occur while it loads
the image.
In particular, the message
.DM
	File appears truncated, winging it
.DE
can be generated by the code that loads a GIF image.
.SH "The Gamma Box"
The Gamma Box controls image brightness and contrast, and can be used to
generate some fairly bizarre effects.
The majority of this box is taken up by a window
that displays the current gamma correction curve.
This curve defines a mapping between the input values (zero through 255)
along the
.I X
axis, and the output values (zero through 255) along the
.I Y
axis.
How these values are interpreted depends on the setting of the button
.BR "HSV/RGB Mode" .
This is described in more details below.
.PP
The gamma curve is defined by four control points, two of which are locked
at the left and right edges of the window.
These two points can be moved up and down only;
the other two points can be moved freely around the window,
subject only to the constraint that they cannot be moved past one another
on the
.I X
axis.
The ``left'' point must stay to the left of the ``right'' point.
.PP
The gamma curve can be adjusted in a variety of ways.
You can change the curve directly by clicking on one of
the control points and dragging it.
Also, you can indirectly adjust the curve by using the buttons
.BR Brighter ,
.BR Dimmer ,
.BR Sharper ,
and
.BR Duller .
The following describes each button in detail:
.IP \fK(Apply)\fR
.IS \fBP\fR
Take the current gamma curve, apply it to the
original picture data according to the setting of the button
.BR "HSV/RGB Mode" ,
and display the results.
Note that the gamma curve is always applied to the original data,
not the data currently displayed.
Thus, if you draw a gamma curve that makes pictures darker and click
.B Apply
several times, it will only
do something noticeable the first time:
it will
.I not
continue to darken the picture.
Also, note that often it is unnecessary to click the
.B Apply
button.
If you specified the command-line option
.BR \-rw ,
.B xv
automatically applies the gamma curve every time it is changed.
.IP \fK(No_Gamma)\fR
Show the original picture with no gamma correction.
This does not affect the current gamma curve:
it just ignores it.
You can use this command to do A/B
comparisions between the original picture and your ``improved'' version.
.IP \fK(Linear)\fR
Set the gamma curve to a straight line from, 0,0 to 255,255.
This displays the picture without any apparent gamma correction, much as the
.B "No Gamma"
command does; however, this command also resets the curve.
You can use this command to correct an broken gamma curve.
.IP \fK(Default)\fR
Reset the gamma curve to its default setting.
Normally, this is a straight line, exactly the same as that set by the command
.BR Linear .
However, if you use the command-line option
.B \-GAMMA
or define the resource
.BR xv.gamma ,
you can set the default gamma correction to something else entirely.
.IP \fK(Spline)\fR
Toggle how
.B xv
connects the four control points to build the gamma curve.
By default,
.B xv
connects the points with a spline curve.
Unfortunately, some gamma curves are hard to get (or impossible) in this mode.
Clicking this button toggles it to
.BR Lines ,
and
.B xv
then connects the control points with straight lines.
Clicking the button again returns it to
.BR Spline .
.IP \fK(Close)\fR
Close the Gamma Box.
To re-open this box, click the button labeled
.B Gamma
on the Control Box, described above.
.IP \fK(Brighter)\fR
Make the picture brighter.
Unless you you invoke
.B xv
with the command-line option
.BR \-rw ,
mode, you must press
.B Apply
to see the effect.
.IP \fK(Dimmer)\fR
Make the picture dimmer.
.IP \fK(Sharper)\fR
Increase the contrast of the picture.
.IP \fK(Duller)\fR
Decrease the contrast of the picture.
.IP \fK(HSV/RGB_Mode)\fR
This button toggles how
.B xv
uses the gamma curve, between
.B "HSV Mode"
(the default) and
.BR "RGB Mode" .
.IP
In HSV mode,
.B xv
converts the colors of the picture from the RGB model (red, green, and blue)
into the HSV model (hue, saturation, and value).
.B xv
applies the gamma curve to the ``value'' (brightness) of the
HSV colors; then converts the modified HSV colors back to RGB colors for
re-display.
In this mode,
.B xv
makes colors brighter or dimmer, according to the curve,
but does not change their hue or saturation.
This is generally the more desirable way to apply gamma correction to color
pictures.
.IP
The RGB mode is mainly for amusement value.
In this mode,
.B xv
applies the gamma curve to each of the RGB components (red, green, and blue)
separately.
This can have some interesting effects,
particularly when you use a drastic gamma-correction curve.
For example, assume a gamma curve that is a straight line from 0,255 to
255,0 (that is, top-left to bottom-right, instead of the normal bottom-left
to top-right).
In HSV mode, this curve merely lightens dark colors and vice-versa;
for example, light blue becomes dark blue, and so on.
The RGB mode, this complements the colors:
that is blue is reversed with yellow, red with cyan, and green with violet.
.IP
Both modes exchange black and white.
Therefore, when you view grayscale images, it makes no difference
whether you are in HSV or RGB mode:
both modes behave exactly the same.
Also, note that when you use the command-line option
.BR \-rw ,
gamma correction  is performed
.I after
the reversal.
.IP \fK(1)\fR
.IS \fK(2)\fR
.IS \fK(3)\fR
.IS \fK(4)\fR
.B xv
has four vaguely useful curves built into it.
To invoke one of them, clicking on one of the buttons labelled
.BR 1 ,
.BR 2 ,
.BR 3 ,
or
.BR 4 .
You can also save the current gamma curve in one of these buttons:
to do so, click the button
.B Set
and then click the numbered button under which you wish to store the curve.
.B xv
stores your curve until you overwrite it or exit the program.
.IP
Note that the Spline/Lines
and HSV/RGB settings are
.I not
stored in the presets.
You can specify your own default settings for
the presets by setting the X resources
.BR xv.gamma1 ,
.BR xv.gamma2 ,
and so on.
.IP \fK(Undo)\fR
Undo the last change to the gamma curve.
Currently, the undo buffer is eight slots long, so you can undo up
to the last eight changes; however, there is no way to ``undo an undo''.
As with presets,
.B xv
does not save the Spline/Lines and HSV/RGB settings, nor are they 
considered changes.
.PP
At the top of the Gamma Box are six numbers that define the current gamma
correction curve.
The numbers are, in order, the Y coordinate of the first
control point, the X and Y coordinates of the second and third control points,
and the Y coordinate of the fourth control point.
These numbers appear in the same order that they would be specifed
to the command-line option
.B \-GAMMA
or the resources
.B xv.gamma
and
.BR gamma[1-4] .
.SH "The Save Box"
When you click the
.B Save
button in the Control Box (or press `S' in any of the \fIxv\fP windows),
.B xv
displays its Save Box.
With this, you can write the current file to disk.
The file consist of the currently visible portion of the picture.
By default this is the entire picture, but if you have cropped
the image, then it saves only the cropped portion.
If you have rotated the picture,
.B xv
also writes the rotation into the file.
If you have applied a gamma curve to the image,
.B xv
saves it with the corrections set by that curve.
.PP
As noted elsewhere,
.B xv
stores images internally as eight-bit color-mapped images.
If you load a 24-bit color image,
.B xv
converts it to an eight-bit image immediately,
and throws away the 24-bit version.
As such, you do not really want to use
.B xv
to modify (crop, rotate, etc.) 24-bit images,
as much of the information will be lost in the translation.
.PP
Saved images are not affected by the display that they were saved on.
For example, if you displayed a full-color image on a one-bit B/W display, it
would be dithered in black and white.
If you save the image, by default
.B xv
saves it as a full-color image:
all the data will still be there.
.PP
When you open the Save Box, it displays the contents of the current
directory in a scrollable list.
Next to each file name is an icon that marks its file type:
for example, sub-directories are shown as ``file folders''. 
.PP
To go down enter a sub-directory, either double-click on its name, or
click on its name and then click the button
.BR Open .
To move up the directory tree,
press the left-mouse button on the button at the very top of the Save Box.
.B xv
displays a pop-up menu that shows shows the current directory
followed by its parent directories.
Drag the mouse to any directory in this list and release the mouse button:
.B xv
switches to that directory.
.PP
Once you are in the correct directory, you can save the file by typing a
simple file name (no slashes, please), and then clicking
.B Save
or pressing \*(RT.
To clear the line, type
.B <ctrl-U>
or
.BR <ctrl-K> .
.PP
By default,
.B xv
saves the file as a full-color GIF file, in normal size.
The buttons at the buttom of the Save Box let you choose the format in which
.B xv
writes the image.
Note that some combinations are not possible; for example,
X11 Bitmaps can only be saved as
.BR "B/W Dithered" .
Also, the formats
.B "PBM (raw)"
and
.B "PBM (ascii)"
actually cover all PBM, PGM, and PPM formats.
The particular format is chosen according to the setting of 
the control
.BR Colors .
.PP
The button
.B Cancel
gets rid of the Save Box.
You must issue the
.B Save
command to make it visible again.
.PP
The button
.B Quit
exits
.BR xv .
It is provided as a convenience, as you will
often want to quit immediately after saving a file.
.PP
Note that because the Save Box expects you to type a file name, you cannot
execute keyboard commands while the keyboard focus is in this window.
.SH "Command-line Options"
.B xv
recognizes many command-line options.
This section discusses them, by category.
.PP
The first set of command-line options relate to general topics:
.IP \fB\-help\fR
Print a description of the available command-line options.
Any unrecognized option does this as well.
.IP \fB\-display\fR
Specifify the display to which
.B xv
should connect.
If you do not specify a display,
.B xv
uses the one named in the environment variable
.BR $DISPLAY .
.IP "\fB\-fg \fIcolor\fR"
Set to
.I color
the foreground color used by the windows.
(Resource
.BR foreground ,
of type string.)
.IP "\fB\-bg \fIcolor\fR"
Set to
.I color
the background color used by the windows.
(Resource
.BR background ,
of type string.)
.IP "\fB\-bw \fIpixels\fR"
Set to
.I pixels
the width of the window border.
Your window manager may choose to ignore this, however.
(Resource
.BR borderWidth ,
of type integer.)
.PP
The next set of options control window sizing:
.IP "\fB\-geometry \fIstring\fR"
Set to
.I string
the geometry of the image window \(em that is, the window's size and its
placement on the screen.
It is most useful when you only specify a position and let
.B xv
choose the size.
If you specify a size as well,
.B xv
will create a window of that size, unless you also specify the command-line
option
.BR \-fixed .
(Resource name
.BR geometry ,
type string.)
.IP "\fB\-fixed\fR"
This option is used with the option
.BR \-geometry .
If you specify a window's size with the
.B \-geometry
option,
.B xv
normally stretches the picture to exactly that size.
This is not always desirable,
as it may seriously distort the aspect ratio of the picture.
Specifying
.B \-fixed
corrects this behavior.
When you do this,
.B xv
uses the geometry size as a
.I maximum
window size.
It will, however, preserve the original aspect ratio of the
picture.
For example, if you give a rectangular geometry of 320\(mu240,
and you try to display a square picture of 256\(mu256, the
window opened will actually be 240\(mu240, which is the largest square
that still fits within the 320\(mu240 rectangle that was specified.
(Resource name
.BR fixed .)
.IP "\fB\-expand \fIfactor\fR"
Set the picture's expansion or compression factor to
.IR factor ,
which must be an integer.
Values greater than one multiply the picture's dimensions
by the given factor.
(For example, an expansion factor of three make a 320\(mu200
image display as 960\(mu600.)
If
.I factor
is less than zero,
.B xv
treats it as a reciprocal.
(For example, an expansion factor of \-4 makes the picture
one-fourth its normal size.)
Zero is not a valid expansion factor.
(Resource name
.BR expand .)
.IP "\fB\-aspect \fIX\^\fB:\fIY\fR"
Set the picture's aspect ratio.
.B xv
draws the picture in aspect ratio \fIX\^\fB:\fIY\fR,
and stores this aspect ratio as the default used by the
.B Aspect
control.
.IP
The aspect ratio of nearly every X display is 1:1.
This means that pixels appear to be `square':
that is, a box 100 pixels wide by 100 pixels high appears square on the screen.
Unfortunately, this is not the case with some screens, as well as with
many digitizers.
You can use this command-line option
to stretch the picture and so correct its appearance.
.IP
Unlike the other size-related options, this one does not care what the
size of the overall picture is.
It operates on a pixel-by-pixel basis, stretching each image pixel slightly,
in either width or height, depending on the ratio.
Aspect ratios greater than greater than one make the picture
wider than normal.  Aspect ratios less than one make the picture taller than
normal.
For example, a 512\(mu480 image that was supposed to fill
a standard 4\(mu3 video screen should be displayed with an aspect ratio
of 5:4.)
(Resource name
.BR aspect ,
of type string.)
.PP
The next options manipulate colors:
.IP "\fB\-ncols \fInumber\fR"
Set to
.I number
the maximum number of colors that
.B xv
will use.
Normally, this is set to ``as many as it can get'' (i.e.,
two to the power of the screen's depth).
However, you can set this to smaller values for interesting effect.
Most notably, if you set it to zero,
.B xv
displays the picture by dithering with black and white.
(The actual colors used can be set by options
.B \-black
and
.BR \-white ,
described below.)
(Resource name
.BR ncols ,
type integer.)
.IP \fB\-nglobal\fR
Do not use global colors.
This adjusts the way
.B xv
behaves when it cannot
get all the colors it requested.
Normally, it will search the display's
default color map and ``borrows'' any colors it deems appropriate.
However,
.B xv
does not own these borrowed colors; and as such, they can be changed without
.BR xv 's
permission or knowledge.
If this happens, the displayed picture changes, usually for the worse.
If you specify the option
.BR \-nglobal ,
option,
.B xv
will not borrow global colors:
it will only use colors that it successfully allocated,
which makes it immune to any color changes.
(Resource name
.BR nglobal ,
type boolean.)
.IP 
.BR xv 's
default is to use global colors, mainly because
color changes usually are not a problem
if you are only using
.B xv
to display a picture for a short time.
Color changes can become a problem if you use
.B xv
to display a picture that you will be keeping around for a while,
for example, when you use
.B xv
to display an image on the root window.
In such cases you will want to specify
.BR \-nglobal .
.IP
Note that using the options
.B \-ncols
or
.B \-root
automatically turns on
.BR \-nglobal .
.IP \fB\-rw\fR
Tell
.B xv
to use read/write color cells.
Normally,
.B xv
allocates colors read-only, which allows it to share colors with
other programs.
f you use read/write color cells, no other program can use
the colors that
.B xv
is using, and vice-versa.
The only reason to do such a thing is that using read/write color cells allows 
the
.B Apply
function in the Gamma Box to operate many times faster.
(Resource name
.BR rwColor ,
type boolean .)
.IP \fB\-perfect\fR
Make
.B xv
try ``extra hard'' to get all the colors it wants.
In particular,
.B xv
allocates and installs its own color map if (and only if)
it could not allocate all the desired colors.
This option is not allowed with the option
.BR \-root .
(Resource name
.BR perfect ,
type boolean.)
.IP \fB\-ninst\fR
Stop
.B xv
from installing its own color map when the
.B \-perfect
option is in effect.
Instead of installing the color map, it
asks the window manager, nicely, to take care of it.
This is the correct way to install a color map;
however, it does not seem to work with many window managers,
so the default behavior is for
.B xv
to handle installation itself.
Note that this is
.I only
relevant if option
.B \-perfect
has been specified, and ifn
.B xv
ran out of colors and generated its own color map.
(Resource name
.BR ninstall ,
type boolean.)
.PP
The following options control the conversion of 24-bit color.
They apply only if you are using
.B xv
to display 24-bit RGB data
(PPM files, color PM files, and the output of
.BR bggen ).
They have no effect whatsoever on how
it displays GIF pictures or eight-bit greyscale images.
.IP \fB\-slow24\fR
Use the alternate 24-bit to eight bit conversion algorithm.
The default algorithm dithers the picture using a fixed set
of colors that roughly approximate all displayable colors.
The algorithm
.B \-slow24
pick the best colors on a per-image basis, and dithers with those.
This algorithm often produces better looking pictures; but it runs
about half the speed of the default algorithm.
Because
.B xv
chooses the colors on a per-image basis,
it cannot be used to display multiple images, as each image
will almost certainly want a different set of 256 colors.
The default algorithm, however, uses the same exact colors for all images,
so it can display many images simultaneously without running out of colors.
Also, the
.B \-slow24
algorithm occasionally produces worse-looking pictures than the
default algorithm, particularly on displays with very few colors.
The default algorithm produces nice, dependably ``okay'' pictures.
(Resource name
.BR slow24 ,
type boolean.)
.IP \fB\-noqcheck\fR
Turn off a ``quick check'' that is normally made.
Normally, before running either of the 24-bit to eight-bit
conversion algorithms,
.B xv
determines whether the picture to be displayed has more than 256
unique colors in it.
If the picture does not,
.B xv
treats the picture as an eight-bit color-mapped image (i.e., GIF)
and does not run either of the conversion algorithms.
It displays the pictures ``perfectly,''
whereas if they went through either of the conversion algorithms,
they would be dithered.
.IP
This approach often uses a lot of colors,
which limits the ability to view multiple images at once.
(See the
.B \-slow24
option, above, for further infoformation about color sharing.)
(Resource name
.BR noqcheck ,
type boolean.)
.PP
The following options control how
.B xv
manipulates the root window.
.B xv
can display images on the root window of an X display;
the default is for it to open its own window.
When using the root window,
.B xv
is somewhat limited because it cannot
receive input events (key press and mouse clicks) from the root window.
As a result, you cannot track pixel values, crop, or use keyboard commands.
.IP \fB\-root\fR
Display images in the root window.
.B xv
displays the image in the upper left corner of the screen,
and repeats it as often as necessary to fill the entire screen.
.IP "\fB\-tile \fItile\fR
Shrink the image so that they fit onto the screen
.I tile
times.
.I tile
must be an integer.
The defualt behavior is generally to cohp off the bottom and right
sides of the images along the bottom and right sides of the screen.
.IP
Note that this slightly changes the aspect ratios of the images.
(Resource name
.BR tile ,
type boolean.)
.IP \fB\-center\fR
Center the image in the root window.
If the image is smaller than the root window,
the area around it will be determined by the settings of
.BR \-rpat ,
.BR \-rfg ,
and
.BR \-rbg .
(Resource name
.BR centerPic ,
type boolean.)
.IP "\fB\-rpat \fItype\fR"
Set to
.I type
the pattern to fill the rest of the root window when option
.B \-center
is in effect.
.I type
can be one of the following:
.DS
	0	A solid background color (the default)
	1	Add radial lines to the solid background
	2	A brick pattern
.DE
.IP
(Resource name
.BR rootPattern ,
type integer.)
.IP "\fB\-rfg \fIcolor\fR
Sets to
.I color
the foreground color used in the various
.B \-rpat
patterns.
(Resource name
.BR rootForeground ,
type string.)
.IP "\fB\-rbg \fIcolor\fR"
Set to
.I color
the background color used in the various
.B \-rpat
patterns.
(Resource name
.BR rootBackground ,
type string.)
.IP \fB\-max\fR
Automatically stretch the image to the full size of the screen.
This is mostly useful when you want
.B xv
to display a background.
If you use this option when you are not using option
.BR \-root ,
the behavior is slightly different.
.B xv
makes the image as large as possible while preserving the normal aspect ratio.
.IP \fB\-quit\fR
Display the first file named on the command line, and exit.
Because images displayed on the root window
remain there until explicitly cleared, this is very useful for having
.B xv
display background images on the root window in some sort of start-up script.
Needless to say, this is only useful if you are 
also using option
.BR \-root .
.IP \fB\-clear\fR
Clear the root window of any extraneous
.B xv
images.
Although there are other ways of clearing the root window of an X display,
such as using the command
.BR xsetroot ,
use the
.B \-clear
option to free up the other resources allocated by
.BR xv ,
in particular, the color-map entries.
Note that it is not necessary to run
.B "xv \-clear"
before displaying another picture in the root window.
.B xv
detects that there is an old
.B xv
image in the root window and automatically clears it out
(and free the associated colors).
.PP
The next options help control
.BR xv 's
windows.
.B xv
consists of four main windows, plus one window for the image.
Of those four, three of them (the Control Box, the Info Box,
and the Gamma Box) may be automatically mapped and positioned
when the program starts.
.IP \fB\-cmap\fR
Map the Control Box.
(Resource name
.BR ctrlMap ,
type boolean.)
.IP \fB\-cgeom\fR
Set the initial geometry of the Control Box.
Note that only the position information is used.
The Control Box is of fixed size.
(Resource name
.BR ctrlGeometry ,
type string.)
.IP \fB\-imap\fR
Map the Info Box.
(Resource name
.BR infoMap ,
type Boolean.)
.IP \fB\-igeom\fR
Set the initial geometry of the Info Box.
Note that only the position information is used.
The Info Box is of fixed size.
(Resource name
.BR infoGeometry ,
type string.)
.IP \fB\-gmap\fR
Maps the Gamma Box.
(Resource name,
.BR gammaMap ,
type Boolean.)
.IP \fB\-ggeom\fR
Sets the initial geometry of the Gamma Box.
Note that only the position information is used.
The Gamma Box is of fixed size.
(Resource name
.BR gammaGeometry ,
type string.)
.PP
Finally,
.B xv
recognizes the following miscellaneous options:
.IP \fB\-rv\fR
Reverse the colors of the image, so that white becomes
black and black becomes white.
This has ``interesting'' effects on color 
images; for example, red (255,0,0) becomes cyan (0,255,255).
(Resource name
.BR reverseVideo ,
type Boolean.)
.IP \fB\-mono\fR
Forces the image to be displayed as a gray scale.
This is most useful when you are using certain gray-scale X displays.
Although
.B xv
attempts to determine if it is running on a grayscale display,
many X displays lie and claim to be able to do color.
(This is often because they have color graphics boards hooked up to
monochrome monitors.)
On these displays, if you do not specify
.BR \-mono ,
what you will see is a grayscale representation of one
of the RGB outputs of the system.
Option
.B \-mono
corrects this behavior.
(Resource name
.BR mono ,
type Boolean.)
.IP "\fB\-white \fIcolor\fR"
Use
.I color
as the ``white'' color when the picture is stippled in monochrome
(that is, when option
.B "\-ncols\fP 0
is specified).
(Resource name
.BR white ,
type string.)
.IP "\fB\-black \fIwhite\fR"
Use
.I color
as the ``black'' color when the picture is stippled in monochrome
(that is, when option
.B "\-ncols\fP 0
is specified).
The command
.DM
	xv -ncols 0 -bl red -wh yellow \fIfilename\fP
.DE
.IP
generates some late '60s-style psychedelic effects.
(Resource name
.BR black ,
type string.)
.IP \fB\-GAMMA\fR
Set up the default gamma-correction curve.
It can be used to control contrast or brighness.
The curve defines a transformation between input pixel-intensity values
(from the picture) and output pixel-intensity values (which are displayed).
The curve is specified by four points in the range 0,0 to 255,255.
The points must be in strict left-to-right order.
The first point is fixed at \fIX\fR=0, and the last at \fIX\fR=255.
The parameters to this option are, in order, the
.I Y value
of the first point, the
.I X
and
.I Y
values of the second point, the
.I X
and
.I Y
values of the third point, and the
.I Y
value of the last point.
These are the same numbers that appear above the gamma-correction
curve in the Gamma Box, as described above.
(Resource name
.BR gamma ,
type six integers.)
.IP
You can also specify default values for the four gamma ``presets'
in the Gamma Box.
The format is the same as above, and the resource names 
are
.BR gamma1 ,
.BR gamma2 ,
.BR gamma3 ,
and
.BR gamma4 .
.IP \fB\-autogamma\fR
Apply the default gamma correction,
either as set by the option
.B \-GAMMA\fR
or by the resource
.BR gamma ,
to the image automatically, before the image is ever displayed.
(Resource name
.BR autoGamma ,
Type Boolean.)
.IP \fB\-fish\fR
Display some animated fish whenever
.B xv
is loading or resizing an image.
Please note this option may cause X
Protocal Errors on slower X displays.
.IR "Caveat utilitor" .
(Resource name
.BR fish ,
type Boolean.)
.IP "\fB\-wait \fIseconds\fR"
Wait
.IR seconds ,
then automatically display the next image.
This implements a simple ``slide-show'' feature.
The program still accepts commands, so you can
use the
.B Next
command to abort the current picture without waiting the full time specified.
.IP \fB\-bfc\fP 12
Toggle the color-freeing behavior.
If you experience X protocol errors
when you apply gamma corrections or load multiple images,
try using this option.
Normally, this option turns on some workarounds for
broken X servers, but if
.B xv
was built with the workarounds on by
default, this option turns them off.
(Resource name
.BR brokeFreeCols ,
type Boolean.)
.SH Shortcuts
The following table gives
.B xv
command and the keystrokes that invoke them:
.DS
.ta 0.5i 2.5i
	Next picture:	\*(SP, \*(RT
	Previous Picture:	<backspace>, <del>
	Quit XV:	\fBq\fR
	Open/Close Control Box:	\fBh\fR, \fB?\fR, right-mouse button
	Open/Close Info Box:	\fBi\fR
	Open/Close Gamma Box:	\fBg\fR
	Open Save Box:	\fBs\fR
	Aspect:	\fBa\fR
	Turn Right:	\fBt\fR
	Turn Left:	\fBT\fR
	4x3:	\fB4\fR
	Crop:	\fBc\fR
	Uncrop:	\fBu\fR
	AutoCrop:	\fBA\fR
	Normal:	\fBn\fR
	Max Size:	\fBm\fR
	Maxpect:	\fBM\fR
	Shrink 10%:	\fB,\fR
	Grow 10%:	\fB.\fR
	Half Size:	\fB<\fR
	Double Size:	\fB>\fR
	Apply Gamma:	\fBp\fR
.DE
.SH "See Also"
.B
X applications
.R
.SH Notes
.B xv
will not work on displays that are not one, four, six, eight, 24, or 32 bits
deep.
Luckily, that should still cover nearly every display out there.
It may not work on certain six- or 24-bit displays.
.PP
.B xv
displays only the first image in a GIF file that contains multiple 
images.
.PP
As for PM pictures, this program only displays one-plane PM_I pictures, or
one-, three-, or four-plane PM_C pictures.
.PP
The PM format is a file format that we use at the GRASP Lab for our
image-processing work.
If you aren't at Pennsylvania, you are unlikely to ever run into
a PM-format file, so don't worry about it.
Please ignore all references to PM.
.PP
.II "Bradley, John"
.B xv
was written by John Bradley (bradley@cis.upenn.edu).
.PP
.II "Naughton, Patrick J."
GIF-reading code based on
.BR gif2ras.c ,
by Patrick J. Naughton (naughton@wind.sun.com).
.PP
.II "Maudlin, Michael"
GIF-writing code is essentially unchanged from code written
by Michael Maudlin (mlm@cs.cmu.edu).
