xv(l) xv(l)
NAME
xv - interactive image display for the X Window System
SYNTAX
xv [options] [filename [filename...]]
NOTE
This man page is merely the text portion of the
(PostScript) xv docs, without the figures, and without the
appendicies. As such, it is highly recommended that you
get your hands on the *real* documentation.
DESCRIPTION
xv is an X11 program that displays images in the GIF,
JPEG, TIFF, PBM, PGM, PPM, X11 bitmap, Utah Raster Toolkit
RLE, PDS/VICAR, Sun Rasterfile, and PM formats on 1-, 2-,
4-, 6-, 8-, 16-, 24-, and 32-bit X displays. xv will also
read compress-ed versions of these files.
SECTION 1: OVERVIEW
xv version 2.10 lets you do a large number of things (many
of them actually useful), including, but not limited to,
the following:
o display an image in a window on the screen
o display an image on the root window, in a variety of
styles
o grab any rectangular portion of the screen and turn it
into an image
o arbitrarily stretch or compress the image
o rotate the image in 90-degree steps
o flip the image around the horizontal or vertical axes
o crop a rectangular portion of the image
o magnify any portion of the image by any amount, up to
the size of the screen
o determine pixel values and x,y coordinates in the image
o adjust image brightness and contrast with a gamma cor-
rection function
o apply different gamma functions to the Red, Green, and
Blue color components, to correct for non-linear color
response
o adjust global image saturation
Rev: 2.10 Feb 26, 1992 1
xv(l) xv(l)
o perform global hue remapping
o perform histogram equalization
o edit an image's colormap
o reduce the number of colors in an image
o dither in color and b&w
o smooth an image
o crop off solid borders automatically
o convert image formats
o generate Encapsulated PostScript
Unfortunately the Automatic Checkbook Balancing Module
still isn't completely debugged, and is not included in
this distribution.
SECTION 2: STARTING XV
Note: unless explicitly stated otherwise, the term click
means "click with the Left mouse button."
Start the program up by typing 'xv'. After a short delay,
a window will appear with the default image (the xv logo,
credits and revision date) displayed in it. If you change
the size of the window (using whatever method your window
manager provides), the image will be automatically
stretched to fit the window.
Section 2.1: Displaying Pixel Values
Clicking (and optionally dragging) the Left mouse button
inside this window will display pixel information in the
following format:
196, 137 = 191,121,209 (287 42 81 HSV)
The first pair of numbers (196,137) are the x and y posi-
tions of the cursor, in image coordinates. These numbers
remain the same regardless of any image resizing, or crop-
ping. For example, if you click on the eye of the fish on
the right side of the default image, you'll get (approxi-
mately) 251,129 regardless of the size of the displayed
image. This allows you to zoom in for precise measure-
ments.
The first triplet of numbers (191,121,209) are the RGB
values of the selected pixel. The components will have
integer values in the range 0-255. The values displayed
Rev: 2.10 Feb 26, 1992 2
xv(l) xv(l)
are prior to any HSV/RGB modification, but after any col-
ormap changes. See "Section 5: The Color Editor" for
details.
The second triplet of numbers (287 42 81) are the HSV val-
ues of the selected pixel. The first component will have
integer values in the range 0-359, and the second and
third components will have integer values in the range
0-100. The values displayed are prior to any HSV/RGB mod-
ification, but after any colormap changes. See "Section
5: The Color Editor" for details. Also, see "Appendix D:
RGB and HSV Colorspaces" for more information about what
these numbers mean.
Note: If you actually want to measure some pixels, it will
probably help to crop to a small region of your image, and
expand that region to the point where you can see the
individual pixels.
This string is automatically copied to your X server's cut
buffer whenever you measure pixel values. This lets you
easily feed this information to another program, useful if
you're doing manual feature extraction, or something. Try
it: measure a pixel's value, and then go click your Middle
mouse button in an xterm window.
Section 2.2: Cropping
Bring up the xv controls window by typing the '?' key or
clicking the Right mouse button inside the image window.
Clicking and dragging the Middle button of the mouse
inside the image window will allow you to draw a cropping
rectangle on the image. If you're unhappy with the one
you've drawn, simply click the Middle button and draw
another. If you'd like the rectangle to go away alto-
gether, click the Middle button and release it without
moving the mouse.
You can determine how large the cropping rectangle is (in
image coordinates) by bringing up the xv info window. Do
this by clicking the Info button in the xv controls window
or by typing the 'i' key into any open xv window.
The xv info window will display, among other things, the
current size and position of the cropping rectangle in
terms of image coordinates. For example, if it says:
114x77 rectangle starting at 119,58
that would mean that the current cropping rectangle is 114
image pixels wide, 77 image pixels high, and its top-left
corner is located 119 image pixels in from the left edge
of the image, and 58 image pixels in from the top edge.
Rev: 2.10 Feb 26, 1992 3
xv(l) xv(l)
These values will be updated as you drag the cropping
rectangle around.
If you want to set the size or position of the cropping
rectangle precisely, you can use the arrow keys on your
keyboard. First, make the xv info window visible as
described above (if it's not already visible). Second,
use the mouse to draw a rough approximation of the crop-
ping rectangle that you want. You can now use the arrow
keys to move the cropping rectangle around the image.
Once you've gotten the top and left sides of the cropping
rectangle precisely where you want them, you can move the
bottom-right corner of the cropping rectangle (only) by
holding the <shift> key down while using the arrow keys.
Pressing the up arrow will make the rectangle shorter, and
pressing the down arrow will make the rectangle taller.
Once you have a cropping rectangle that you can live with,
you can proceed with the actual cropping operation. Click
the Crop button in the xv controls window, or type the 'c'
key in any open xv window. The image window will shrink
to show only portions of the image that were inside the
cropping rectangle.
Note: if you are running a window manager such as mwm,
which decorates windows with a title bar, resizing
regions, and such, it is quite possible that the aspect
ratio of the cropped image will get screwed up. This is
because certain window managers enforce a minimum window
size. If you try to crop to a rectangle that is too
small, the window manager will create the smallest window
it can, and the image will be stretched to fit this win-
dow. If this happens, you can press the Aspect button in
the xv controls window, or type the 'a' key in any open xv
window. This will expand the image so that it has the
correct aspect ratio again.
You can crop a cropped image by repeating the same steps
(drawing a new cropping rectangle and issuing the Crop
command), ad infinitum.
You can return to the original, uncropped image by using
the UnCrop command. Simply click the UnCrop button or
type the 'u' key in any open xv window. Note that using
the UnCrop command will turn off image smoothing (the
Smooth) command), due to the potentially long time it can
take to generate a large, smoothed image.
Note that if you try to make the cropping rectangle too
small in either width or height (under 5 screen pixels),
it'll just turn itself off. If you want to crop a very
small portion of an image, you'll probably have to do it
in two passes. First, crop to a small (but large enough
to still be enabled) rectangle, expand that region, then
Rev: 2.10 Feb 26, 1992 4
xv(l) xv(l)
crop again.
Section 2.3: Zooming
You can zoom in by a factor of two (or four, eight, etc.)
on any rectangular region of the image by holding down the
<ctrl> key on your keyboard and clicking the Left mouse
button in the image. A rectangle will flash, centered
around the cursor position, and the region inside that
rectangle will be doubled in size. The image window
should remain the same size, and in the same position.
You can repeat this operation to zoom in by a factor of
four, or eight, or whatever, as many times as you wish.
You can zoom out by a factor of two (if possible) by hold-
ing down the <ctrl> key on your keyboard and clicking the
Right mouse button inside the image window. You can not
zoom out beyond the point where the entire image fill the
window.
SECTION 3: THE CONTROL WINDOW
The xv controls window is the central point of control for
the program, hence the name. It provides controls to
resize the current image, flip and rotate it, load and
save different files, and bring up the other xv windows.
It can be brought up by clicking the Right mouse button in
the image window, or by typing the '?' key inside any open
xv window. Doing either of these things while the xv con-
trols window is visible will hide it.
All of the following commands may be executed by either
clicking the appropriate command button, or typing the
keyboard equivalent (where given) into any open xv window.
Section 3.1: Resizing Commands
Note that none of the 'resizing' commands modify the image
in any way. They only affect how the image is displayed.
The image remains at its original size. This allows you
to arbitrarily stretch and compact the image without com-
pounding error caused by earlier resizing. In each case,
the displayed image is recomputed from the original inter-
nal image.
Normal (Keyboard equivalent 'n')
Attempts to return the image to its normal size,
where one image pixel maps to one screen pixel.
For example, if the image (or the current cropped
portion of the image) has a size of 320x200, this
command will attempt to make the image window be
320 screen pixels wide by 200 screen pixels high.
Rev: 2.10 Feb 26, 1992 5
xv(l) xv(l)
This command may fail in two cases. If you're run-
ning a window manager (such as mwm) that enforces a
minimum window size, and the 'normal' size is too
small, the image may get distorted. See the note
in "Section 2.2: Cropping" for more information.
Also, if the image is larger than the size of your
screen, it will be 'halved' until it fits on the
screen. For example, if you try to display a
1400x900 image on a 1280x1024 screen, the Normal
command will display a 700x450 image.
Max Size (Keyboard equivalent 'm')
This command will make the displayed image be the
same size as the screen. If you are running a win-
dow manager that puts up a titlebar, you'll find
that the titlebar is now off the top of the screen.
To get the titlebar back, simply shrink the image
to anything smaller than the size of the screen.
The window will be moved so that the titlebar is
once again visible.
Maxpect (Keyboard equivalent 'M')
Makes the image as large as possible, while pre-
serving the aspect ratio. This avoids the gener-
ally unwanted image distortion that Max Size is
capable of generating. For example, if you have a
320x200 image, and an 1280x1024 screen, doing the
Maxpect command will result in an image that is
1280x800. Max Size, on the other hand, would've
generated an image of size 1280x1024, which would
be appear 'stretched' vertically.
Dbl Size (Keyboard equivalent '>')
Doubles the current size of the image, with the
constraint that neither axis is allowed to be
larger than the screen. For example, given a
320x200 image and a 1280x1024 screen, the image can
be doubled once (to 640x400), a second time (to
1280x800), but a third time would make the image
1280x1024. You'll note that on the third time, the
width didn't change at all, since it was already at
its maximum value. Also note that the height
wasn't allowed to double (from 800 to 1600), but
was truncated at its maximum value (1024).
Half Size (Keyboard equivalent '<')
Halves the current size of the image, with the con-
straint that neither axis is allowed to have a size
less than 1 pixel. Also, you may run into 'minimum
Rev: 2.10 Feb 26, 1992 6
xv(l) xv(l)
size' problems with your window manager. See the
note in "Section 2.2: Cropping" for more informa-
tion.
Note that the window size is maintained as a pair
of integers. As a result you may see some integer
round-off problems. For example, if you halve a
265x185 image, you'll get a 132x92 image, which is
just fine. However, if you Dbl Size this image,
you'll get a 264x184 image, not the 265x185 image
you might have expected.
+10% (Keyboard equivalent '.')
Increases the current size of the image by 10%,
subject to the constraint that the image cannot be
made larger than the screen size (in either axis).
For example, issuing this command on a 320x200
image will result in a 352x220 image.
-10% (Keyboard equivalent ',')
Decreases the current size of the image by 10%.
Neither axis of the image is allowed to shrink
below 1 pixel. Also, you run the risk of running
into 'minimum window size' problems with your win-
dow manager.
It should be noted that the +10% and -10% commands
have no concept of an 'original size'. They simply
increase or decrease the current image size by 10%.
As a result, they do not undo each other. For
example, take a 320x200 image. Do a +10% and the
image will be 352x220. If you issue the -10% com-
mand now, the image will be made (352 - 35.2)x(220
- 22), or 316x198.
4x3 (Keyboard equivalent '4')
Attempts to resize the image so that the ratio of
width to height is equal to 4 to 3. (e.g.,
320x240, 400x300, etc.) This is useful because
many images were meant to fill the screen of what-
ever system they were generated on, and nearly all
video tubes have an aspect ratio of 4:3. This com-
mand will stretch the image so that things will
probably look right on your X display (nearly all
of which, thankfully, have square pixels). This
command is particularly useful for images which
have really bizarre sizes (such as the 600x200
images presumably meant for CGA, and the 640x350
16-color EGA images).
Rev: 2.10 Feb 26, 1992 7
xv(l) xv(l)
Aspect (Keyboard equivalent 'a')
Applies the 'default aspect ratio' to the image.
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. See 'Section 9: Modifying XV Behav-
ior' for more info. The idea behind this command
is that you'd stretch the image manually (via your
window manager) to roughly the size you'd like, and
then use the Aspect command to fix up the propor-
tions.
Normally Aspect expands one axis of the image to
correct the aspect ratio. If this would result in
an image that is larger than the screen, the Aspect
command will instead shrink one of the axes to cor-
rect the aspect ratio.
Section 3.2: Rotate/Flip Commands
Turn CW (Keyboard equivalent 't')
Rotates the image 90 degrees clockwise.
Turn CCW (Keyboard equivalent 'T')
Rotates the image 90 degrees counter-clockwise.
Flip H (Keyboard equivalent 'h')
Flips the image horizontally (around the vertical
center-line of the image).
Flip V (Keyboard equivalent 'v')
Flips the image vertically (around the horizontal
center-line of the image).
Section 3.3: Smoothing Commands
Raw (Keyboard equivalent 'r')
Returns the displayed image to its 'raw' state
(where each pixel in the displayed image is as
close as possible to the corresponding pixel in the
internal image). In short, it turns off any
dithering or smoothing. When dithering or smooth-
ing haven't been done, this command is disabled.
Dither (Keyboard equivalent 'd')
Regenerates the displayed image by dithering with
the available colors in an attempt to approximate
the original image. This is only relevant if the
Rev: 2.10 Feb 26, 1992 8
xv(l) xv(l)
color allocation code failed to get all the colors
it wanted. If it did get all the desired colors,
the Dither command will just generate the same dis-
play image as the Raw command. On the other hand,
if you didn't get all the desired colors, the
Dither command will try to approximate the missing
colors by dithering with the colors that were
obtained. If you're running xv on a 1-bit display
the Dither command will be disabled, as the image
will always be dithered for display.
Smooth (Keyboard equivalent 's')
Smooths out distortion caused by integer round-off
when an image is expanded or shrunk. This is gen-
erally a desirable effect, however it is fairly
time-consuming on large images on most current
workstations. As such, by default, it is not done
automatically. See "Section 9: Modifying XV Behav-
ior" for more details.
Section 3.4: Cropping Commands
Crop (Keyboard equivalent 'c')
Crops the image to the current cropping rectangle.
This command is only available when a cropping
rectangle has been drawn on the image. See "Sec-
tion 2.2: Cropping" for further information.
UnCrop (Keyboard equivalent 'u')
Returns the image to its normal, uncropped state.
This command is only available after the image has
been cropped. See "Section 2.2: Cropping" for fur-
ther information.
AutoCrop (Keyboard equivalent 'A')
Crops off any constant borders that exist in the
image. It will crop to the smallest rectangle that
encloses the 'interesting' section of the image.
It may not always appear to work because of minor
invisible color changes in the image. As such, it
works best on computer-generated images, and not as
well on scanned images.
Section 3.5: The Display Modes Menu
In addition to displaying an image in a window, xv can
also display images on the root (background) window of
your X display. There are a variety of ways that xv can
display an image on the root window. The Display Modes
popup menu lets you select where (and how) xv will display
the image.
Rev: 2.10 Feb 26, 1992 9
xv(l) xv(l)
Click on the Display Modes button in the xv controls win-
dow, and hold the mouse button down. This will cause the
Display Modes menu to pop up. The current display mode
will be shown with a check mark next to it. To select a
new mode, drag the mouse down to the desired mode, and
release the mouse button.
It is not possible for xv to receive button presses or
keyboard presses in the root window. As such, there are
several functions that cannot be used while in a 'root'
mode, such as pixel tracking and image cropping. If you
want to do such things, you'll have to temporarily return
to 'window' mode, and return to 'root' mode when you're
finished. Also, when you are in a 'root' mode, you will
not be able to get rid of the xv controls window. At best
you can iconify it (using your window manager). (The rea-
son for this is that if you ever got rid of it there'd be
no way to get it back.)
Window Displays the image in a window. If you were previ-
ously in a 'root' mode, the root window will also
be cleared.
Root: Tiled
The image is displayed in the root window. One
image is displayed aligned with the top-left corner
of the screen. The image is then duplicated
towards the bottom and right edges of the screen,
as many times as necessary to fill the screen.
Root: Integer Tiled
Similar to Root: Tiled, except that the image is
first shrunk so that its width and height are inte-
ger divisors of the screen's width and height.
This keeps the images along the bottom and right
edges of the screen from being Normal, Dbl Size,
etc.) will lose the 'integer'-ness of the image.
Root: Mirrored
Tiles the original image with versions that have
been horizontally flipped, vertically flipped, and
both horizontally and vertically flipped. This
gets rid of the sharp dividing lines where tiled
images meet. The effect is quite interesting.
Root: Integer Mirrored
Like Root: Mirrored, but also does the integer-
ization described under the Root: Integer Tiled
entry.
Rev: 2.10 Feb 26, 1992 10
xv(l) xv(l)
Root: Center Tiled
Like Root: Tiled, but it positions the images so
that one of them is centered on the screen, and the
rest are tiled off in all directions. Visually
pleasing without the image size distortion associ-
ated with Root: Integer Tiled.
Root: Centered
Displays a single image centered in the root win-
dow, surrounded by black.
Root: Centered, Warp
Displays a single image centered in the root win-
dow, surrounded by a black and white 'warp' pat-
tern, which produces some mildly visually pleasing
Moire effects.
Root: Centered, Brick
Displays a single image centered in the root win-
dow, surrounded by a black and white 'brick' pat-
tern.
Note: The three 'centered' modes (Root: Centered, Root:
Centered, Warp, and Root: Centered, Brick, but not Root:
Center Tiled) require the creation of a Pixmap the size of
the screen. This can be a fairly large request for
resources, and will fail on a color X terminal with insuf-
ficient memory. They can also require the transmission of
considerably more data than the other 'root' modes. If
you're on a brain-damaged X terminal hanging off a slow
network, you should probably go somewhere else. Barring
that, you should certainly avoid the 'centered' modes.
Also note: If you quit xv while displaying an image on the
root window, the image will remain in the root window, and
the colors used by the image will remain allocated. This
is generally regarded as correct behavior. If you decide
you want to get rid of the root image to free up
resources, or simply because you're sick of seeing it, the
quickest route is to use run 'xv -clear', which will clear
the root window, release any allocated colors, and exit.
Alternately, xsetroot and any other X program that puts
things in the root window should be able to do the trick
as well.
Section 3.6: The 24-bit Conversion Menu
xv can currently only operate on 8-bit images. Whenever
you load a 24-bit image (such as JPEG, TIFF, PPM, etc) it
is immediately converted into an 8-bit colormapped image
Rev: 2.10 Feb 26, 1992 11
xv(l) xv(l)
using one of three algorithms.
Fast Converts 24-bit images into 8-bit images by dither-
ing with a fixed 6x6x6 RGB colormap. It is the
quickest of the three algorithms, but also gener-
ally produces the worst images. It can also be
selected via the '-quick24' command-line option or
X resource.
Slow The default algorithm. Takes about twice as long
as the fast algorithm. Uses the median-cut algo-
rithm to pick a set of 256 colors, and then dithers
using these colors. It can be selected via the
'-slow24' command-line option or X resource.
Best By far and away the slowest of the algorithms. It
can take up to ten times as long as the 'slow'
algorithm. It uses a cleverer version of the
median-cut algorithm to pick a better set of colors
than the slow algorithm. It does not dither. This
might look best if you're going to be expanding the
image by very much, as the dithering in the other
two algorithms becomes very noticable. You can
also select this option via the '-best24' command-
line option or X resource.
Section 3.7: Working With Multiple Files
xv provides a a set of controls that let you conveniently
operate on a list of images. To use the following com-
mands, you'll have to start up xv with a list of file-
names. For example, you could type 'xv *.gif' (assuming,
of course, that you have a bunch of files that end with
the suffix '.gif' in the current directory).
The filenames are listed in a scrollable window. The cur-
rent selection is shown in reverse video. If there are
more names than will fit in the window, the scrollbar will
be enabled.
Section 3.7.1: Operating a List Window
The scrollbar operates as follows:
o clicking in the top or bottom arrow of the scrollbar
scrolls the list by one line in the appropriate direc-
tion. It will continue to scroll the list as long as
you hold the mouse down.
o The thumb (the small white rectangle in the middle of
the scrollbar) shows roughly where in the list you are.
Rev: 2.10 Feb 26, 1992 12
xv(l) xv(l)
You can change your position in the list by clicking
and dragging the thumb to another position in the
scrollbar. The list will scroll around as you move the
thumb.
o You can scroll the list up or down a page at a time by
clicking in the grey region between the thumb and the
top or bottom arrows.
If you click on a name in the list, that name will become
highlighted. You can drag the highlight bar up and down,
and the list will scroll appropriately.
It is also possible to control the list window from the
keyboard. In all cases, you must make sure that the win-
dow sees the keypress. Generally, this means you have to
have the cursor inside the window, though your window man-
ager may also require you to click inside the window
first.
o The up and down arrow keys move the highlight bar up
and down. If the bar is at the top or bottom of the
window, the list will scroll one line.
o The page up and page down keys scroll the list up or
down a page at a time.
o Pressing the home key will jump to the beginning of the
list. Pressing the end key will jump to the bottom of
the list.
Section 3.7.2: The File Commands
You can directly view any image in the list by double-
clicking on its filename. If xv is unable to load the
file (for any of a variety of reasons), it'll display an
error message and put up the default image, the xv logo.
Next (Keyboard equivalent <space>)
Attempts to load the next file in the list. If it
is unable to load the next file, it will continue
down the list until it successfully loads a file.
If it gets to the bottom of the list without suc-
cessfully loading a file, it will put up the
default image.
Previous (Keyboard equivalent <backspace>)
Attempts to load the previous file in the list. If
it is unable to load the previous file, it will
continue up the list until it successfully loads a
file. If it gets to the top of the list without
successfully loading a file, it will put up the
Rev: 2.10 Feb 26, 1992 13
xv(l) xv(l)
default image.
Delete (Keyboard equivalent <ctrl-D>)
This command lets delete the currently selected
file from the list (and optionally delete the asso-
ciated disk file). Note that the currently
selected file is the one with the highlight bar on
it. While this is generally the same as the cur-
rently displayed image, it doesn't have to be.
The Delete command will pop-up a window asking you
what you want to delete. Your choices are:
o List Entry, which will remove the highlighted
name from the list. (Keyboard equivalent: the
enter key)
o Disk File, which will remove the highlighted
name from the list and also delete the associ-
ated disk file. This removes unwanted images,
just like manually typing 'rm <filename>' in
another window. (Keyboard equivalent: <ctrl-D>)
o Cancel, which lets you get out of the Delete
command without actually deleting anything.
(Keyboard equivalent: the esc key)
Section 3.7.3: Image Reloading
It is occasionally desirable to reload an image file
because the contents of the file have changed. For exam-
ple, you could be downloading a file, and you might want
to keep reloading the file to check on the progress of the
download. Or perhaps you have a program that generates
images, and you'd like to view these images without any
manual intervention.
XV provides a way to reload an image via an external sig-
nal. If you send the xv process a SIGQUIT signal ('kill
-QUIT pid', or currently selected file. (The one that is
currently highlighted in the xv controls window filename
list.) This behavior is exactly the same as hitting
'<return>' in the xv controls window. If xv is currently
in a state where hitting '<return>' in the controls window
won't load an image (ie, some pop-up dialog box is grab-
bing all such events), then sending this signal wonUt work
either.
An idea: You could write a 'clock' program that, once a
minute, generates a really spiffy looking picture of the
current time (with color gradations, 3d extruded numbers,
whatever), then sends xv the signal to reload the gener-
ated image.
Rev: 2.10 Feb 26, 1992 14
xv(l) xv(l)
Section 3.8: The Grab Command
The Grab command works as follows: click on the Grab but-
ton in the xv controls window, or type a <ctrl-G> key in
any active xv window (except for the JPEG, PostScript, and
TIFF 'save' dialog boxes). The terminal will beep once,
and the cursor will change to a cross. The screen will
remain frozen until you complete the Grab command.
You can Grab an arbitrary region of the screen by clicking
the Left mouse button and dragging a rectangle in exactly
the same way you draw a cropping rectangle. When you let
go of the mouse button, the contents of this rectangle
will be read from the screen and loaded into xv.
Alternately, you can grab the entire contents of a window
(including its frame) by clicking the Middle mouse button
anywhere inside the chosen window. If you click the Mid-
dle mouse button somewhere on the root window, the entire
screen will be loaded into xv.
Or, alternately, you can simply abort the Grab command by
clicking the Right mouse button anywhere on the screen.
You can use the Grab command for a wide variety of pur-
poses. For example, you can use it to print the contents
of any window (or the whole screen) by grabbing the appro-
priate image and then saving it as a PostScript file.
You can use the Grab command, in conjunction with the Zoom
and UnZoom commands, as an effective replacement for the
xmag program.
You can also use the Grab command to pick 'just the right
colors' for any application. Simply start the application
in question, Grab the window into xv, and use the colormap
editor to twiddle the colors around to your heart's con-
tent.
Note: The Grab command does not work on Macintoshes run-
ning MacX in a rootless mode, which isn't too surprising,
if you think about it...
Section 3.9: Other Commands
Info (Keyboard equivalent 'i')
Opens and closes the xv info window. See "Section
4: The Info Window" for more details.
ColEdit (Keyboard equivalent 'e')
Opens and closes the xv color editor window. See
"Section 5: The Color Editor" for more details.
Rev: 2.10 Feb 26, 1992 15
xv(l) xv(l)
Load (Keyboard equivalent <ctrl-L>)
Opens the xv load window. See "Section 6: The Load
Window" for more details.
Save (Keyboard equivalent <ctrl-S>)
Opens the xv save window. See "Section 7: The Save
Window" for more details.
Quit (Keyboard equivalent 'q')
Quits out of the program.
SECTION 4: THE INFO WINDOW
Section 4.1: Overview
xv provides a window to display information about the cur-
rent image, color allocation, expansion, cropping, and any
error messages. This window can be opened by issuing the
Info command. (Click on the Info button in the xv con-
trols window, or type 'i' in any open xv window.) You can
close the window by using the Info command while the win-
dow is open. You can also close the window by clicking
anywhere inside it.
The top portion of the window displays the program name,
revision date, and patchlevel. It also shows the Univer-
sity of Pennsylvania shield, the GRASP Lab logo, the copy-
right notice, and of course, the author's name.
Section 4.2: The Fields
The "Filename" field displays the name of the currently
loaded file. The name is displayed without any leading
pathname. If there is no currently loaded image (you're
looking at the default image) this field will display
"<none>".
The "Format" field displays information describing what
image format the file is stored in, and how large the file
is (in bytes).
The "Resolution" field shows the width and height (in
image pixels) of the loaded image. Note that this does
not necessarily have anything to do with the size of the
image currently displayed on your screen. These numbers
do not change as you modify the display image.
The "Cropping" field displays the current state of any
cropping activity. If you are looking at the entire
(uncropped) image, and there is no cropping rectangle
drawn, this field will show "<none>". If you draw a crop-
ping rectangle, or if you are viewing cropped portion of
image, this field will display something like "247x128
Rev: 2.10 Feb 26, 1992 16
xv(l) xv(l)
rectangle starting at 132,421". See "Section 2.2: Crop-
ping" for more details.
The "Expansion" field gives you information about how the
image is displayed. It will display something like "1.58
x 1.37 (505 x 273)". This tells you that the current dis-
played image is 505 pixels wide and 273 pixels high, and
that it is 1.58 times wider and 1.37 times higher than the
internal image (which, in this case, had a size of
320x200).
The "Colors" field gives you detailed information on how
well (or poorly) color allocation went. If everything
went reasonably well it will display something like:
Got all 67 desired colors. (66 unique)
This means that 67 entries in the image's colormap were
used in the image, but that only 66 of these colors were
different, as far as the X server was concerned.
See "Appendix E: Color Allocation" for a complete discus-
sion of how colors are allocated, and what the "Colors"
field can tell you.
Note that the fields are filled in as information becomes
available. As such, they can be used as a rough 'progress
indicator' when loading images. When you begin loading,
all the fields are cleared. Once the image has been suc-
cessfully loaded, the top three fields (Filename, Format,
Resolution) are filled in. Once the colors have been
allocated, and the display image generated, the bottom
three fields are shown (Cropping, Expansion, and Colors).
Section 4.3: Status Lines
The bottom two lines in the info window display various
error messages, warnings, and status information. These
two lines are also duplicated in the xv controls window.
The upper line is the more commonly used. It normally
displays a one-line summary of the current image and color
allocation success. If an error occurs, it will be dis-
played on this line as well.
The lower line is used to display warning messages.
SECTION 5: THE COLOR EDITOR
Section 5.1: Overview
The xv color editor provides a powerful system for manipu-
lating color images. Since there are many different rea-
sons why a person would want to modify an image's colors,
and many different types of images that may need
Rev: 2.10 Feb 26, 1992 17
xv(l) xv(l)
modification, there is no one color manipulation tool that
would be 'best' for all purposes. Because of this prob-
lem, xv gives the user three different color tools, all of
which can be used simultaneously.
o Colormap Editing: This tool lets you arbitrarily modify
individual colormap entries. Useful for modifying the
color of captions or other things that have been added
to images. Also works well on images that have a small
number of colors, such as images generated by 'drawing'
or CAD programs. It's also an easy way to spiff up
boring 1-bit black and white images.
o HSV Modification: This tool lets you alter the image
globally in the HSV colorspace. (See "Appendix D: RGB
and HSV Colorspaces" for more info.) Here are examples
of the sort of things you can do with this tool:
o turn all the blues in an image into reds
o change the tint of an image
o change a greyscale image into a mauve-scale image
o increase or decrease the amount of color saturation
in an image
o change the overall brightness of an image
o change the overall contrast of an image
o RGB Modification: This tool lets you route the red,
green, and blue color components of an image through
independent mapping functions. The functions can
either be the standard gamma function, or any arbitrary
function that can be drawn with straight line segments
or a cubic spline. See "Section 5.3.4: The Intensity
Graph" for more info about graph functions.
The major use of the RGB Modification tool is to correct
for the differing color response curves of various color
monitors, printers, and scanners. This is the tool to use
when "the image is too red", for instance.
These three tools are tied together in a fixed order. The
Colormap Editing tool operates on the original colors in
the image. The output of this tool is piped into the HSV
Modification tool. Its output is piped into the RGB Modi-
fication tool. The output from the RGB Modification tool
is what actually gets displayed.
In addition there is a collection of buttons that control
the xv color editor as a whole (more or less).
Rev: 2.10 Feb 26, 1992 18
xv(l) xv(l)
Don't Panic! It's not as complicated as it looks.
Section 5.2: The Colormap Editing Tool
The top portion of this window shows the colormap of the
current image. There are 16 cells across, and up to 16
rows down, for a maximum of 256 color cells. Only cells
actually used somewhere in the image are shown in this
array.
The currently selected color cell is shown with a thick
border. You can change the selection by clicking anywhere
in the array. If you drag the mouse through this area,
you'll see the dials at the bottom change to track the
current pixel values.
You can also select a color cell by clicking anywhere in
the image window. Whichever pixel value you were on when
you let go of the mouse will become the new selected color
cell.
You can define a smoothly gradated range of colors by Left
clicking on the color cell that marks the 'start' of the
range, and Middle clicking on the color cell that marks
the 'end' of the range. Intervening color cells will be
interpolated between the colors of the
As an example:
o View the 'default' image by running xv without specify-
ing any filenames.
o Open the xv color editor window, and Left click on the
first color cell.
o Turn this color cell red by setting the RGB dials to
255,0,0.
o Left click on the 64th color cell (the rightmost color
cell in the last complete row).
o Turn this color cell yellow by setting the RGB dials to
255,255,0.
o Middle click on the first color cell. A smooth series
of yellowish-reds will be generated from the 64th color
cell to the first color cell. Note that the 'direc-
tion' doesn't matter.
Since certain images will have many colors that are the
same, or nearly the same, it is sometimes convenient to
group color cells together. Grouped color cells all take
on the same color, and changing any one of them affects
all of the other colors in the group.
Rev: 2.10 Feb 26, 1992 19
xv(l) xv(l)
To group color cells together, do the following:
o Hold down the <shift> key.
o Left click on one color cell that you would like to be
in the group
o Right click on other color cells that you wish to be in
this group. (Right clicking on cells that are already
selected will de-select them.)
o Release the <shift> key when you're done.
You can create as many groups as you like.
You can use this grouping/ungrouping technique to copy
colors from one color cell to another. Left click on the
source color cell, Right click on the destination color
cell, and Right click on the destination color cell again
(to ungroup it).
Section 5.2.1: Using the Dial Controls
At the bottom the Colormap Editing tool are three dials
that let you set the color of the current color cell (or
group of cells). By default, the dials control the Red,
Green, and Blue components of the RGB colorspace, but they
can also control the Hue, Saturation, and Value components
of the HSV colorspace. (The RGB/HSV button controls
this.)
Regardless of what they control, all dials in xv work the
same way. Clicking on the single arrows increase/decrease
the value by 1. Clicking on the double arrows
increase/decrease the value by a larger amount (16 in this
case). If you click on one of the arrows, and hold the
mouse button down, the increase/decrease will repeat until
you release the mouse button.
You can also click in the general area of the pointer and
simply drag it to the position you want. The further your
mouse cursor is from the center of the dial, the more pre-
cise the control will be. While dragging, you do not have
to keep the cursor inside the dial window.
Section 5.2.2: Colormap Editing Commands
ColUndo
Undoes the last change made to the colormap that
resulted in a color cell changing value. This
includes grouping and ungrouping color cells, and
changing any of the dials.
Rev: 2.10 Feb 26, 1992 20
xv(l) xv(l)
Revert Undoes all color changes. Returns the colormap to
its original state. Destroys any groups that you
may have created.
RGB/HSV
Toggles the Colormap Editing dials between editing
colors in terms of Red, Green, and Blue, and edit-
ing colors in terms of Hue, Saturation, and Value.
Grey Turns color images into greyscale images by chang-
ing the colormap. This replaces each color cell
with a greyscale representation of itself. Use the
Revert command to restore the colors.
RevVid This command behaves differently, depending on the
setting of the RGB/HSV mode. (You can tell which
mode you're in by the titles on the dials.)
In RGB mode, each color component is separately
'inverted'. For example, Yellow (which is composed
of full red, full green, and no blue) would turn to
Blue (no red, no green, full blue).
In HSV mode, only the Value (intensity) component
is 'inverted'. The Hue and Saturation components
remain the same. In this mode, bright colors turn
to dark versions of the same color. For example, a
Yellow would turn Brown.
Random Generates a random colormap. This is of question-
able usefulness, but it will occasionally come up
with pleasing color combinations that you never
would've come up with yourself. So it stays in.
It works best on images with a small number of col-
ors. Note that it respects cell groupings, so if
your image has a lot of colors, you can create a
few large groups and then use the Random command.
Note: It is HIGHLY RECOMMENDED that if you're using the
Colormap Editing tool, you do NOT use the HSV Modification
tool or the RGB Modification tool as well. If you do, the
results can be quite confusing. For example, you might
edit a color cell, and set its color values to produce a
purple. However, because of HSV/RGB Modification further
down the line, the actual color displayed on the image
(and in the color cell) is yellow. Very confusing,
indeed.
Rev: 2.10 Feb 26, 1992 21
xv(l) xv(l)
Section 5.3: The HSV Modification Tool
There are four separate controls in the HSV Modification
tool. At the top of the window are a pair of circular
controls that handle hue remapping. Lower down is a cir-
cular control that maps 'white' (and greys) to a specified
color. There is a dial control that lets you satu-
rate/desaturate the colors of the current information.
Finally, at the bottom there is a graph window that lets
you modify intensity values via an arbitrary remapping
function.
Section 5.3.1: Hue Remapping Controls
These two dials are used to define a source and a destina-
tion range of hue values. Every hue in the source range
(defined in the From dial) gets mapped to the value of the
corresponding point in the destination range (defined in
the To dial).
Each dial has a pair of radial lines with handles at their
ends. Between the two lines an arc is drawn with an arrow
at one end. The wedge drawn by these lines and the arc
defines a range of values (in degrees). The direction of
the arc (clockwise, or counter-clockwise) determines the
direction of this range of values (increasing or decreas-
ing).
Distributed around the dial are tick marks and the letters
'R', 'Y', 'G', 'C', 'B', and 'M'. These letters stand for
the colors Red, Yellow, Green, Cyan, Blue, and Magenta,
and they show where these colors appear on the circle.
The range is shown numerically below the control. By
default the range is '330, 30 CW'. This means that a
range of values [330, 331, 332, ... 359, 0, 1, ... 28, 29,
30] has been defined. Note that (being a circle) it wraps
back to 0 after 359.
The range can be changed in many different ways. You can
click on the 'handles' at the end of the radial lines and
move them around. If you click inside the dial, but not
on one of the handles, you'll be able to drag the range
around as a single object. There are also 5 buttons below
the dial that let you rotate the range, flip the direction
of the range, and increase/decrease the size of the range
while keeping it centered around the same value.
In its default state, the To dial is set to the same range
as the From dial. When the two dials are set to the same
range, they are effectively 'turned off', and ignored.
An example of hue remapping:
o As a simple example of the sort of things you can do
Rev: 2.10 Feb 26, 1992 22
xv(l) xv(l)
with the hue remapping control, we'll change the back-
ground color of the default (xv logo) image without
changing any other colors in the image. Since the
background is composed of a gradient of 64 colors, you
would not want to do this with the Colormap Editing
tool. It would take forever.
o First, get the default image up on the screen by run-
ning 'xv' without giving any filenames. Open up the xv
color editor window via the ColEdit command.
o Next, click the mouse in the image window and drag it
around. You'll see that all the background pixels have
the same Hue component value (240).
o To remap this hue, simply adjust the From dial so that
its range includes this Hue value. The background
should change from 'blue' to a reddish color, assuming
the To dial is still set to its default range (centered
around 'R'). If more than the background changed
color, you can shrink the From range so that it covers
fewer colors. In fact, it's possible to shrink the
range to the point where it only covers only a single
value.
Note that the values printed when you are tracking pixel
values in the image are the values before the HSV Modifi-
cation tool is applied. For example, the background of
the default image will still claim to be blue, regardless
of what color you may have changed it to. This is so that
you know what Hue value you will need to remap if you want
to change its color again.
If you press the Reset button that is located near the hue
remapping controls, it will effectively disable the hue
remapping by setting the To range equal to the From range.
Below the hue remapping controls are a group of 'radio
buttons'. You can have up to six different hue remappings
happening simultaneously. Higher numbered mappings take
precedence over lower number mappings.
An example of multiple hue remappings:
o Draw a From range that is a complete circle. The easi-
est way to do this is to draw a range that is nearly a
full circle, then click and hold down the 'increase
range' button located below the From range dial until
the range stops getting bigger.
o Copy this range to the To range by pressing the Reset
button.
o Rotate the To range slightly, by either clicking and
Rev: 2.10 Feb 26, 1992 23
xv(l) xv(l)
dragging anywhere in the To range dial, or by using the
'rotate clockwise' and 'rotate counter-clockwise' but-
tons located below the To range.
o You've just built yourself what is effectively a tint
control.
o Now, suppose, you'd like to adjust the background color
of your (tint-modified) image, without affecting any-
thing else. Clicking on the background in the image
window reveals that the background still has an (origi-
nal) hue of 240. To modify this hue without affecting
anything else, we'll need a second hue remapping.
o Click on the 2 radio button. The dials will change to
some other default setting. As before, set the From
range to encompass the value 240, preferably as
'tightly' as possible, and set the To range to produce
the desired background color.
Note that the six hue remappings are not 'cascaded'. The
output of one remapping is not fed as input into any of
the other hue remappings. The hue remappings always oper-
ate on the hue values in the original image. In this
example, if remapping #1 adds 32 to all hue values,
thereby mapping the blue background (value 240) into a
purple-blue (value 272), remapping #2 still sees the back-
ground at 240, and can remap it to anything it likes.
Similarly, in the same example, if remapping #1 has mapped
a green-blue color (value 208) into blue (value 240),
remapping #2 will not map this into another color. As far
as remapping #2 is concerned, that green-blue is still
green-blue.
If it seems complicated, I'm sorry. It is.
Section 5.3.2: The White Remapping Control
In the HSV colorspace, 'white' (including black, and all
the greys in between) has no Hue or Saturation components.
As such, it is not possible to use the hue remapping con-
trols to change the color of white pixels in the image,
since they have no 'color' to change.
The white remapping control provides a way to add Hue and
Saturation components to all the whites in the image. It
consists of a movable point in a color dial. The angle of
the dot from the center of the dial determines the Hue
component. The distance of the dot from the center of the
dial determines the Saturation component. The further the
dot is from the center of the dial, the more saturated the
color will be.
You can control the white remapping control in several
Rev: 2.10 Feb 26, 1992 24
xv(l) xv(l)
ways. You can click on the handle and drag it around with
the mouse. There are also four buttons provided under the
dial. One pair allows you to rotate the handle clockwise
and counter-clockwise without changing its distance from
the center. The other pair of buttons lets you change the
distance between the handle and the center without chang-
ing the angle.
The current Hue and Saturation values provided by the con-
trol is displayed below the dial. The first number is the
Hue component, in degrees, and the second is the Satura-
tion component, as a percentage.
There is also a checkbox that will let you turn off the
white remapping control. This lets you quickly compare
your modified 'white' with the original white. You can
also effectively disable the white remapping control by
putting the handle back in the center of the control. The
easiest way to do this is to click and hold the 'move
towards center' button until the saturation gets down to
0%.
Example:
o Press the Grey control in the Colormap Editing tool.
This turns all the colors in the image into shades of
grey.
o Drag the handle in the white remapping control halfway
down towards the 'R' mark. The Hue and Saturation val-
ues should be roughly 0-degrees and 50%. The image
should now be displayed in shades of pink.
Section 5.3.3: The Saturation Control
The saturation control lets you globally increase or
decrease the color saturation of the image. In effect, it
is much like the 'color' control on most color televi-
sions.
The saturation control is a dial that operates exactly
like the dials described in "Section 5.2.1 Using the Dial
Controls". In short, you can click and hold down any of
the four buttons in the bottom of the control to increase
or decrease the control's value. You can also click on
the dial itself and move the pointer around directly.
The saturation control has values that range from '-100%'
to '+100%'. At its default setting of '0%', the satura-
tion control has no effect on the image. As the values
increase, the colors become more saturated, up to '+100%'
where every color is fully saturated. Likewise, as values
decrease, the colors become desaturated. At '-100%',
every color will become a completely desaturated (i.e., a
Rev: 2.10 Feb 26, 1992 25
xv(l) xv(l)
shade of grey). Note that this control is applied after
the the White Remapping control, so if you 'greyify' the
image by completely desaturating it, you will not be able
to color it using the White Remapping control.
Unless you're trying for some special effects, the useful
range of this control is probably '+/-20%'. Also note
that the control will have no effect on shades of grey, as
they have no color to saturate.
Section 5.3.4: The Intensity Graph
The intensity graph allows you to change the brightness of
the image, change the contrast of the image, and get some
unique effects.
The intensity graph is a function that lets you remap
intensity values (the Value component in HSV Colorspace)
into other intensity values. The input and output values
of this function both range from 0 to 255. The input val-
ues range along the x axis of this graph (the horizontal).
For every input value (point along the x axis) there is a
unique output value determined by the height of the graph
at that point. In the graph's default state, the function
is a straight line from bottom-left to top-right. In this
case, each input value produces an equivalent output
value, and the graph has no effect.
There are a number of 'handles' along the graph. These
provide your major means of interacting with the graph.
You can move them around arbitrarily, subject to these two
constraints: the handles at the far left and far right of
the graph can only be moved vertically, and handles must
remain between their neighboring handles for the graph to
remain a proper function.
The handles are normally connected by a spline curve. To
see this, move one of the handles by clicking and dragging
it. (Note that the x,y position of the current handle is
displayed while the mouse button is held down.) The func-
tion will remain a smoothly curved line that passes
through all the handles. You can change this behavior by
putting the function into 'lines' mode. Press the 'lines'
button (the second button down from the top). The func-
tion will change to a series of line segments that connect
the handles. Press the 'spline' button (the top button)
to go back to 'spline' mode.
The next two buttons let you add or delete handles. The
'add handle' button will insert a handle into the largest
'gap' in the function. The 'delete handle' button will
remove a handle from the smallest 'gap' in the function.
You can have as little as 2 handles, or as many as 16.
Note that as the number of handles gets large, the spline
Rev: 2.10 Feb 26, 1992 26
xv(l) xv(l)
will start getting out of control. You may wish to switch
to 'lines' mode in this case.
The 'Reset' button puts everything back on a straight line
connecting bottom-left to top-right (a 1:1 function). It
does not change the number of handles, nor does it change
the x-positions of the handles.
The 'Gam' button lets you set the function curve by enter-
ing a single number. The function is set equal to the
gamma function:
Y = 255 * (I/255) ^ (1/g)
where I is the input value (0-255), g is the gamma value,
and Y is the computed result.
Gamma values (for our purposes) can range between 0 and
10000, non-inclusive.
o A gamma value of '1.00' results in the normal 1:1
straight line.
o Gamma values of less than 1.00 but greater than 0.00
result in 'exponential' curves, which will dim the
image.
o Gamma values greater than 1.00 result in 'logarithmic'
curves, which will brighten the image. Try it and see.
There is a shortcut for the 'Gam' button. Type 'g' while
the mouse is inside the graph window.
Also, touching any of the handles after a 'Gam' command
will put the graph back into its 'normal' mode. (Either
'spline' or 'lines' depending on which of the top two but-
tons is turned on.)
Generally, whenever you move a graph handle and let go of
it, the image will be redrawn to show you the effects of
what you've done. This can be time-consuming if you
intend to move many points around. You can temporarily
prevent the redisplay of the image by holding down a
<shift> key. Continue to hold the <shift> key down while
you move the handles to the new position. Release the
<shift> key when you're done, and the image will be redis-
played.
Section 5.4: The RGB Modification Tool
The RGB Modification tool is a collection of three graph
windows, each of which operate on one of the components of
the RGB colorspace. This tool lets you perform global
color-correction on the image by boosting or cutting the
Rev: 2.10 Feb 26, 1992 27
xv(l) xv(l)
values of one or more of the RGB color components. You
can use this to correct for color screens that are 'too
blue', or for color printers that produce 'brownish' out-
put, or whatever.
The graphs work exactly as explained in "Section 5.3.4:
The Intensity Graph".
Neat Trick: In addition to color-correction, you can use
the RGB modification tool to add color to images that
didn't have color to begin with. For instance, you can
'pseudo-color' a greyscale image.
An example of pseudo-coloring:
o Adjust the Red graph so that there is a strong red
presence on the right side of the graph, and none on
the left, or in the middle.
o Adjust the Green graph so that there is a strong green
presence in the middle of the graph, and none on the
left or right.
o Adjust the Blue graph so that there is a strong blue
presence on the left side of the graph, and none on the
left, or in the middle.
You now have a transformation that will take greyscale
images and display them in pseudo-color, using a 'tempera-
ture' color scheme. Neato!
Section 5.5: The Color Editor Controls
These buttons provide general control over the whole xv
color editor window. You can display the image with or
without color modification, save and recall presets, and
undo/redo changes. Also, convenience controls are given
for performing some of the most common operations on the
Intensity graph.
Apply (Keyboard equivalent 'p')
Displays the image using the current HSV and RGB
Modifications. Also turns the 'Display with
HSV/RGB mods' checkbox on. (See below.)
This is only useful when the 'Auto-apply HSV/RGB
mods' checkbox is off.
NoMod Displays the image without any HSV or RGB Modifica-
tions. Also turns the 'Display with HSV/RGB mods'
checkbox off.
Rev: 2.10 Feb 26, 1992 28
xv(l) xv(l)
Reset (Keyboard equivalent 'R')
Resets all HSV and RGB controls to their default
settings. Doesn't affect the Colormap Editing
tool.
Undo Undoes the last change to the HSV or RGB controls.
It may be helpful to think of xv as maintaining a
series of 32 'snapshots' of the HSV and RGB con-
trols. You are normally looking at the last frame
in this series. The Undo control moves you back-
wards in the series.
Redo Only available after you've hit Undo. Moves you
forward in the 'snapshot' series described above.
Note that if you have hit Undo a few times (i.e.,
you're now looking at some frame in the middle of
the series), and you change an HSV or RGB control,
all subsequent frames in the series are thrown
away, and the current state becomes that last frame
in the series.
1,2,3,4
Pressing any of these buttons recalls a preset (a
complete set of values for the HSV and RGB con-
trols).
Set Used in conjunction with the Reset,1,2,3,4 buttons
to store the current settings of the HSV and RGB
controls into a preset. To do so, press the Set
button, and then press one of the Reset,1,2,3,4
buttons. The current HSV and RGB control settings
will be stored in that preset, as long as xv con-
tinues running. The values will be lost when the
program exits. It is also possible to save these
values permanently. See the CutRes button (below)
and "Section 9: Modifying XV Behavior" for more
details.
CutRes Copies the current settings of the HSV and RGB con-
trols, as text, into the X server's cut buffer.
You can then use a text editor to paste these val-
ues into your '.Xdefaults' (or '.Xresources') file.
This lets you save the current settings 'perma-
nently'. See "Section 9: Modifying XV Behavior"
for more details.
Close This button closes the xv color editor window.
Rev: 2.10 Feb 26, 1992 29
xv(l) xv(l)
Brite Brightens the image by moving all the handles in
the Intensity graph up by a constant amount.
Dim Darkens the image by moving all the handles in the
Intensity graph down by a constant amount.
Sharp Increases the contrast of the image by moving han-
dles on the left side of the Intensity graph down,
and handles on the right side up.
Dull Decreases the contrast of the image by moving han-
dles on the left side of the Intensity graph up,
and handles on the right side down.
Norm (Keyboard equivalent 'N')
Normalizes the image so that the darkest pixels in
the image are given an intensity of '0', and the
brightest pixels in the image are given an inten-
sity of '255'. Intermediate colors are interpo-
lated accordingly. This forces the image to have
the full (maximum) dynamic range.
HistEQ (Keyboard equivalent 'H')
Runs a histogram equalization algorithm on the cur-
rently displayed region of the image. This is, if
you're cropped, it will only run the algorithm on
the cropped section. Note, however, that the only
modification it makes to the image is to generate a
bizarre corrective Intensity curve. As such, if
you HistEQ a section of the image, then UnCrop, the
rest of the image will probably not be what you'd
want. Also note that the histogram curve will 'go
away' if you touch any of the handles in the Inten-
sity graph window, just like a 'gamma' curve would.
The 'Display with HSV/RGB mods' checkbox tells you whether
or you're looking at a modified image (checked) or the
'raw', unmodified image (unchecked). The Apply and NoMod
buttons change the setting of this checkbox, and you can
also change the checkbox directly by clicking on it.
The 'Auto-apply HSV/RGB mods' checkbox controls whether or
not the program regenerates and redisplays the image after
each change to an HSV or RGB control. By default, this
checkbox is turned on, so that you can easily see the
results of your modifications. However, in the case that
you want to make a large number of changes at once, it
might be preferable to turn automatic redisplay off for a
Rev: 2.10 Feb 26, 1992 30
xv(l) xv(l)
while, to speed things up.
The 'Auto-reset on new image' checkbox controls whether or
not the HSV and RGB controls are Reset back to their
default values whenever a new image is loaded up. By
default, this is also turned on, as when you're playing
with the HSV/RGB controls, you probably only want to
affect the current image, and not all subsequently loaded
images as well.
SECTION 6: THE LOAD WINDOW
The xv load window lets you load and view images interac-
tively, without specifying them on the command line when
you start xv.
The load window shows the contents of the current direc-
tory in a scrolling window. The files will be sorted
alphabetically, with all the directories (and symbolic
links to directories, if your operating system supports
them) displayed first.
This list window operates in the same way that the one in
the xv controls window works. (See "Section 3.7.1: Oper-
ating a List Window" for details.) In short, you can
operate the scroll bar, drag the highlight bar around the
window, and use the up-arrow, down-arrow, Home, End, Page
Up, and Page Down keys on your keyboard.
Whenever you click on a name in the list (or otherwise
change the position of the highlight bar), the name of the
highlighted file is copied to the "Load file" text entry
region, located below the list window. Pressing the Ok
button (or typing <return>) will cause the program to
attempt to load the specified file. If the load attempt
is successful, the load window will disappear, and the new
image will be displayed. Otherwise, an error message will
be displayed, and the load window will remain visible.
The Browse checkbox overrides this behavior, and keeps the
load window visible until it is explicitly closed via the
Cancel button. This is handy if you're using xv to 'wan-
der around a directory tree', and plan to be using the
Load command quite often.
If the image is successfully loaded, its name will be
added to the xv controls window list. This will let you
quickly reload it later without have to go through the xv
load window again.
You can also load a file by double-clicking on its name in
the file list.
If the specified filename begins with a '!' or '|'
Rev: 2.10 Feb 26, 1992 31
xv(l) xv(l)
character, the filename will be interpeted as a shell com-
mand to run. The leading '!' or '|' gets stripped off,
and the rest of the line is fed to the default system
shell. The command is expected to generate an image in
one of the formats that xv recognizes. This image is
expected to be the stdout of the specified command. If
the command returns non-zero, it is assumed that the com-
mand failed, and no image is loaded. You can pipe multi-
ple commands together. For example, loading "! xwd | xwd-
topnm" would run xwd to generate a window dump, pipe that
to xwdtopnm to convert it to a PPM file, which in turn is
piped to xv.
If the specified file is a directory, xv will figure that
out and (instead of loading it) will 'cd' to that direc-
tory, and display its contents in the list window.
Above the list window is a pop-up menu button, much like
the Display Modes button in the xv controls window. It
normally displays the name of the current directory. If
you click this button, and hold the mouse down, the com-
plete path will be shown, one directory per line. You can
go 'up' the directory tree any number of levels, all the
way up to the root directory, by simply selecting a direc-
tory name in this list.
For those who prefer the direct approach, you can simply
type file or directory names in the "Load file" text entry
region. If you type a directory name and hit <return>, xv
will 'cd' to that directory and display its contents in
the list window. If you type a file name and hit
<return>, xv will attempt to load the file. You can enter
relative paths (relative to the currently displayed direc-
tory), absolute paths, and even paths that begin with a
'~'.
The "Load file" text entry region supports a number of
emacs-like editing keys.
Ctrl-F moves the cursor forward one character
Ctrl-B moves the cursor backward one character
Ctrl-A moves the cursor to the beginning of the
line
Ctrl-E moves the cursor to the end of the line
Ctrl-D deletes the character to the right of the
cursor
Ctrl-U clears the entire line
Ctrl-K clears from the cursor position to the
Rev: 2.10 Feb 26, 1992 32
xv(l) xv(l)
end of the line.
If the filename is so long that it cannot be completely
displayed in the text entry region, a thick line will
appear on the left or right side (or both sides) of the
region to show that "there's more over this way".
Pressing the Rescan button will rescan the current direc-
tory. While the contents of the current directory are
read each time the load window is opened, it is perfectly
possible (given a multitasking operating system) that some
other program may add, delete, or rename files in the cur-
rent directory. XV would not know if this happened. The
Rescan button gives you an easy way of 'kicking' xv into
looking again.
SECTION 7: THE SAVE WINDOW
The xv save window lets you write images back to disk,
presumably after you've modified them. You can write
images back many different formats, not just the original
format. Warning! Images are saved as they are currently
shown (at the current size, with the current color modifi-
cation, rotation, cropping, etc. applied). The only
exception to this rule is if you are on a 1-bit B/W dis-
play. The fact that images have to be stippled in black
and white in order to be displayed on such a screen
doesn't count as 'modification', and the file won't be
saved 'as displayed'. You can manipulate and save full-
color images on such a display, even if you can't really
see them.
For the most part, the xv save window operates exactly
like the xv load window. (See "Section 6: The Load Win-
dow" for details.) Only the differences are listed here.
When the window is opened, it should have the filename of
the currently loaded file already entered into the text
entry region. If you change directories, or click on a
file name in the list window, this name will be cleared
and replaced with the new name.
At the bottom of the window are a list of possible formats
in which you can save the file. If you click on one of
these formats, and your filename has a recognized suffix
(i.e., '.gif', '.GIF', '.pbm', etc.), the suffix portion
of your filename will be replaced with the new, appropri-
ate suffix for the selected format.
You can pipe output from xv to other programs by using the
xv save window. If the first character of the specified
filename is '!' or '|', the rest of the filename is inter-
preted as a command to pipe the output to, in the cur-
rently selected image format. A fine use for this feature
Rev: 2.10 Feb 26, 1992 33
xv(l) xv(l)
is directly printing images to a PostScript printer by
selecting 'PostScript' in the formats list, and typing
something like "| lpr" as the filename. In this case, xv
will create a temporary file, write the PostScript to that
file, and cat the contents of that file to the entered
command. XV will wait for the command to complete. If
the command completed successfully, the xv save window
will disappear. If the command was unsuccessful, the win-
dow will remain visible. In any event, the temporary file
will be deleted.
There is a 'Save at normal size' checkbox. Normally, when
you save an image, it will be saved at the current expan-
sion (ie, one screen pixel will map to one image pixel in
the saved file. Sometimes, however, it is desirable to
save an image at its original size. This is most relevant
when you're viewing images larger than your screen. By
default, xv will automatically shrink images so that they
fit on the screen. If you save these images, you'll find
that you've lost a lot of data, that maybe you wanted to
keep. That's what this checkbox is here for. Note: cer-
tain operations, such as Smooth and Dither only affect the
displayed image. If you choose to save an image at its
normal size, these effects will not be in the saved image.
At the bottom right side of the window there is a list of
possible 'Color' variations to save. Most file formats
support different 'sub-formats' for 24-bit color, 8-bit
greyscale, 1-bit B/W stippled, etc. Not all of them do.
Likewise, not all 'Color' choices are available in all
formats.
In general, the 'Color' choices do the following:
Full Color
Saves the image as currently shown with all color
modifications, cropping, rotation, flipping, resiz-
ing, and smoothing. The image will be saved with
all of its colors, even if you weren't able to dis-
play them all on your screen. For example, you can
load a color image on a 1-bit B/W display, modify
it, and write it back. The saved image will still
be full color, even though all you could see on
your screen was some B/W-dithered nightmare.
Greyscale
Like Full Color, but saves the image in a greyscale
format.
B/W Dithered
Like Full Color, but before saving the image xv
Rev: 2.10 Feb 26, 1992 34
xv(l) xv(l)
generates a 1-bit-per-pixel, black-and-white
dithered version of the image, and saves that,
instead.
Reduced Color
Saves the image as currently shown, with all color
modifications, cropping, rotation, flipping, resiz-
ing, and smoothing. The image will be saved as
shown on the screen, with as many or few colors as
xv was able to use on the display. The major pur-
pose of this is to allow special effects (color
reduction) to be saved, in conjunction with the
'-ncols' command line option. You will probably
never need to use this.
Format notes:
GIF While xv can read both the GIF87a and GIF89a for-
mats, it will only write GIF87a. This is in keep-
ing with the GIF89 specification, which states that
if you don't need any of the features added in
GIF89 (which xv doesn't), you should continue to
write GIF87, for greater compatibility with old
GIF87-only readers.
Since GIF only supports one format (up to 8 bits
per pixel, with a colormap), there will be no size
difference between a Full Color and a Greyscale
image. A B/W Dithered image, on the other hand,
will be considerably smaller.
PM Full Color images are saved in the 3-plane, 1-band,
PM_C format. Greyscale and B/W Dithered images are
both saved in the 1-plane, 1-band, PM_C format. As
such, there is no size advantage to saving in the
B/W Dithered format.
PBM (raw)
Full Color images are saved in PPM format.
Greyscale images are saved in PGM format. B/W
Dithered images are saved in PBM format. Each of
these formats are tailored to the data that they
save, so PPM images are larger than PGM images,
which are in turn larger than PBM images.
In the raw variation of the PBM formats, the header
information is written in plain ASCII text, and the
image data is written as binary data. This is the
more popular of the two dialects of PBM.
Rev: 2.10 Feb 26, 1992 35
xv(l) xv(l)
PBM (ascii)
Like PBM (raw), only the image data is written as
ASCII text. As such, images written in this format
will be several times larger than images written in
PBM (raw). This is a pretty good format for inter-
change between systems because it is easy to parse.
Also, since they are pure, printable ASCII text,
images saved in this format can be mailed, without
going through a uuencode-like program.
Note that xv-produced PBM files may break some PBM
readers that do not correctly parse comments. If
your PBM reader cannot parse comments, you can eas-
ily edit the PBM file and remove the comment lines.
A comment is everything from a "#" character to the
end of the line.
X11 Bitmap
Saves files in the format used by the bitmap pro-
gram, which is part of the standard X11 distribu-
tion. Since bitmap files are inherently 1-bit per
pixel, you can only select the B/W Dithered option
for this format.
Sun Rasterfile
Full/Reduced Color images are stored in a 24-bit
RGB format, Greyscale images are stored in an 8-bit
greyscale format, and B/W Dithered images are
stored in a 1-bit B/W format.
PostScript
Full/Reduced Color images are stored in a 24-bit
RGB format, Greyscale images are stored in an 8-bit
greyscale format, and B/W Dithered images are
stored in a 1-bit B/W format.
XV writes Encapsulated PostScript, so you can
incorporate xv-generated PostScript into many desk-
top-publishing programs. XV also prepends some
color-to-greyscale code, so even if your printer
doesn't support color, you can still print 'color'
PostScript images. These images will be three
times larger (in file size) than their greyscale
counterparts, so it's a good idea to save Greyscale
PostScript, unless you know you may be printing the
file on a color printer at some point.
Also, you should probably never need to generate
B/W Dithered PostScript, as every PostScript
printer I've ever heard of can print greyscale
images. The only valid cases I can think of are:
Rev: 2.10 Feb 26, 1992 36
xv(l) xv(l)
A) doing it for a special effect, and B) doing it
to generate a much smaller (roughly 1/8th the size)
PostScript file.
Note: When you try to save a PostScript file, the
xv postscript window will pop up to let you specify
how you want the image printed. (See "Section 8:
The PostScript Window", for details.)
JPEG XV writes files in the JFIF format created by the
Independent JPEG Group. Full/Reduced Color images
are written in a 24-bit RGB format, and Greyscale
images are written in an 8-bit greyscale format.
B/W Dithered images should not be used, as they
will probably wind up being larger than Greyscale
versions of the same images, due to the way JPEG
works. Note: You cannot write Reduced Color JPEG
files. If you attempt to, a Full Color JPEG file
will be saved.
When you save in the JPEG format, a dialog box will
pop up and ask you for a quality setting. '75%' is
the default value, and really, it's a fine value.
You shouldn't have to change it unless you're
specifically trying to trade off quality for com-
pression, or vice versa. The useful range of val-
ues is 5%-95%.
TIFF Full/Reduced Color images are written in a 24-bit
RGB format, Greyscale images are written in an
8-bit greyscale format, and B/W Dithered images are
written in a 1-bit B/W format.
When you save in the TIFF format, a dialog box will
pop up and ask you which type of image compression
it should use. None, LZW, and PackBits compression
types are available for Full/Reduced Color,
Greyscale, and B/W Dithered modes. In addition,
there are two B/W Dithered-only algorithms, CCITT
Group3 and CCITT Group4.
SECTION 8: THE POSTSCRIPT WINDOW
The xv postscript window lets you describe how your image
should look when printed. You can set the paper size and
the image size, position the image on the paper, and print
in 'portrait' or 'landscape' mode.
The majority of the xv postscript window is taken up by a
window that shows a white rectangle (the page) with a
black rectangle (the image) positioned on it. You can
position the image rectangle anywhere on the page. The
Rev: 2.10 Feb 26, 1992 37
xv(l) xv(l)
only constraint is that the center of the image (where the
two diagonal lines meet) must remain on the page. Only
the portion of the image that is on the page will actually
be printed.
The image can be (roughly) positioned on the page by
clicking in the image rectangle and dragging it around.
As you move the image, the "Top" and "Left" position dis-
plays will show the size of the top and left margins (the
distance between the top-left corner of the page and the
top-left corner of the image).
You'll note that you have limited placement resolution
with the mouse. If you want to fine-position the image,
you can use the arrow keys to move the image around. The
arrow keys will move the image in .001" increments. You
can hold them down, and they will auto-repeat. You can
also hold a <shift> key down while using the arrow keys.
This will move the image in .01" increments.
You can change the size of the printed image by adjusting
the "Width" or "Height" dials. Normally, the dials are
locked together, to keep the aspect ratio of the image
constant. You can unlock the dials by turning the off the
checkbox located below the dials. As you change the
dials, the size of the image (when printed) is displayed
below, in inches and in millimeters. The current resolu-
tion of the image is also displayed below. The "Resolu-
tion" numbers tell you how many image pixels will be
printed per inch.
Located below the 'page' rectangle are a set of radio but-
tons that let you specify the current paper size (8.5" x
11", 8.5" x 14", 11" x 17", A4, B5, 4"x5", and 35mm), and
orientation (Portrait and Landscape).
The Center button will center the image on the page. The
Maxpect button will make the image as large as possible
(maintaining half-inch margins on all sides) without
changing the aspect ratio.
There are a pair of small buttons located next to the
"Left" and "Top" displays. Clicking the "Left" one will
cycle between displaying the "Left" margin, the "Right"
margin, and the "Center X" position (the distance from the
left edge of the paper to the center of the image).
Clicking the "Top" display's button will cycle between
displaying the size of the "Top" margin, the size of the
"Bottom" margin, and the "Center Y" position (the distance
from the top edge of the paper to the center of the
image).
At the top of the xv postscript window are a pair of
Rev: 2.10 Feb 26, 1992 38
xv(l) xv(l)
checkboxes. The "preview" checkbox lets you specify
whether or not to include a b/w preview of the image in
the PostScript file. Certain desktop publishing programs
may make use of such a preview.
The 'compress' checkbox lets you specify whether or not to
generate compressed 8-bit PostScript. This is particu-
larly handy if you're generating color PostScript as color
PostScript files are normally three times larger than
their greyscale counterparts. Compression can shrink
these color PostsScript files by a factor of 4:1. It has
a lesser effect on greyscale images. It should be noted,
however, that compressed PostScript files may take 2-3
times longer to print than uncompressed PostScript files.
However, if you are connected to your laser printer via a
slow 9600 baud serial line, the decreased transmission
time due to compressed data may more than make up for the
increased execution time. You'll have to decide for your-
self.
Click the "Ok" button when you're finished with the xv
postscript window. If everything is successful, the xv
postscript and the xv save window will both close. If xv
was unable to write the PostScript file, the xv postscript
window will close, but the xv save window will remain
open, to give you a chance to enter a different filename.
SECTION 9: MODIFYING XV BEHAVIOR
XV supports literally dozens of command line options and
X11 resources. Fortunately, it is doubtful that you'll
ever need to use more than a small few. The rest are pro-
vided mainly for that 'one special case' application of
xv...
Section 9.1: Command Line Options Overview
If you start xv with the command 'xv -help', the current
list of options will be displayed:
xv [-] [-2xlimit] [-aspect w:h] [-bg color] [-black
color]
[-bw width] [-cegeometry geom] [-cemap] [-cgeometry
geom]
[-clear] [-cmap] [-cursor char#] [-DEBUG level]
[-display disp] [-dither] [-expand exp] [-fg color]
[-fixed] [-geometry geom] [-help] [-hi color]
[-hsv]
[-igeometry geom] [-imap] [-keeparound] [-lo color]
[-max]
[-maxpect] [-mono] [-ncols nc] [-nglobal] [-nin-
stall]
[-nopos] [-noqcheck] [-owncmap] [-perfect] [-quit]
[-rbg color]
Rev: 2.10 Feb 26, 1992 39
xv(l) xv(l)
[-rfg color] [-rgb] [-rmode mode] [-root] [-rw]
[-slow24]
[-smooth] [-visual type] [-wait seconds] [-white
color]
[-wloop] [-noresetroot] [-browse] [-nostat]
[-best24] [-quick24]
[-cecmap] [-crop] [-rv] [-nolimits] [-loadclear]
[filename ...]
Section 9.2: General Options
-help Print usage instructions, listing the current
available command-line options. Any unrecognized
option will do this as well.
-display disp
Specifies the display that xv should attempt to
connect to. If you don't specify a display, xv
will use the environment variable $DISPLAY.
-fg color (Resource name: foreground string)
Sets the foreground color used by the windows.
-bg color (Resource name: background string)
Sets the background color used by the windows.
-hi color (Resource name: highlight string)
Sets the highlight color used for the top-left
edges of the control buttons.
-lo color (Resource name: lowlight string)
Sets the lowlight color used for the bottom-right
edges of the control buttons, and also the back-
ground of some windows.
-bw bwidth (Resource name: borderWidth integer)
Sets the width of the border on the windows. Your
window manager may choose to ignore this, however.
Section 9.3: Image Sizing Options
-geometry geom (Resource name: geometry string)
Lets you specify the size and placement of the
'image' window. It's most useful when you only
specify a position, and let xv choose the size. If
you specify a size as well, xv will create a window
of that size, unless -fixed is specified. The geom
argument is in the form of a normal X geometry
Rev: 2.10 Feb 26, 1992 40
xv(l) xv(l)
string (e.g. "300x240" or "+10+10" or
"400x300+10+10").
-fixed (Resource name: fixed boolean)
Only used in conjunction with the -geometry option.
If you specify a window size with the -geometry
option, xv will normally stretch the picture to
exactly that size. This is not always desirable,
as it may seriously distort the aspect ratio of the
picture. Specifying the -fixed option corrects
this behavior by instructing xv to use the speci-
fied geometry size as a maximum window size. It
will, however, preserve the original aspect ratio
of the picture.
For example, if you give a rectangular geometry of
'320x240', and you try to display a square picture
with a size of '256x256', the window opened will
actually be '240x240', which is the largest square
that still fits in the '320x240' rectangle that was
specified.
-expand exp (Resource name: expand floating-point)
Lets you specify an initial expansion or compres-
sion factor for the picture. You can specify
floating-point values. Values larger than zero
multiply the picture's dimensions by the given fac-
tor. (i.e., an expand factor of '3' will make a
320x200 image display as 960x600).
Factors less than zero are treated as reciprocals.
(i.e., an expand factor of '-4' makes the picture
1/4th its normal size.). '0' is not a valid expan-
sion factor.
-aspect w:h (Resource name: aspect string)
Lets you set an initial aspect ratio, and also sets
the value used by the Aspect control. The aspect
ratio of nearly every X display (and, in fact, any
civilized graphics display) is 1:1. What this
means is that pixels appear to be 'square'. A 100
pixel wide by 100 pixel high box will appear on the
screen as a square. Unfortunately, this is not the
case with some screens and digitizers. The -aspect
option lets you stretch the picture so that the
picture appears correctly on your display. Unlike
the other size-related options, this one doesn't
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.
Rev: 2.10 Feb 26, 1992 41
xv(l) xv(l)
Aspect ratios greater than '1:1' (e.g., '4:3') make
the picture wider than normal. Aspect ratios less
than '1:1' (e.g. '2:3') make the picture taller
than normal. (Useful aspect ratio: A 512x480 image
that was supposed to fill a standard 4x3 video
screen (produced by many video digitizers) should
be displayed with an aspect ratio of '5:4')
Section 9.4: Color Allocation Options
-ncols nc (Resource name: ncols integer)
Sets the maximum number of colors that xv will use.
Normally, this is set to 'as many as it can get'.
However, you can set this to smaller values for
interesting effect. Most notably, if you set it to
'0', it will display the picture by dithering with
'black' and 'white'. (The actual colors used can
be set by the -black and -white options, below.)
-nglobal (Resource name: nglobal boolean)
Adjusts the way the program behaves when it is
unable to get all the colors it requested. Nor-
mally, it will search the display's default col-
ormap, and 'borrow' any colors it deems appropri-
ate. These borrowed colors are, however, not owned
by xv, and as such, can changed without xv's per-
mission, or knowledge. If this happens, the dis-
played picture will change, in a less-than-
desirable direction. If you specify the -nglobal
option, xv will not use 'global' colors. It will
only use colors that it successfully allocated,
which makes it immune to any color changes.
It should be noted that 'use global colors' is the
default because color changes aren't generally a
problem if you are only using xv to display a pic-
ture for a short time. Color changes only really
become a problem if you use xv to display a picture
that you will be keeping around for a while, while
you go and do some other work (such as using xv to
display a background). In such cases you will want
to specify -nglobal. Note: using the -ncols or
-root options automatically turn on -nglobal.
-rw (Resource name: rwColor boolean)
Tells xv to use read/write color cells. Normally,
xv allocates colors read-only, which allows it to
share colors with other programs. If you use
read/write color cells, no other program can use
the colors that xv is using, and vice-versa. The
only reason you'd do such a thing is that using
read/write color cells allows the Apply function in
Rev: 2.10 Feb 26, 1992 42
xv(l) xv(l)
the xv color editor window to operate much faster.
-perfect (Resource name: perfect boolean)
Makes xv try 'extra hard' to get all the colors it
wants. In particular, when -perfect is specified,
xv will allocate and install its own colormap if
(and only if) it was unable to allocate all the
desired colors. This option is not allowed in con-
junction with the -root option.
-owncmap (Resource name: ownCmap boolean)
Like '-perfect', only this option forces xv to
always allocate and install its own colormap,
thereby leaving the default colormap untouched.
-cecmap (Resource name: ceditColorMap boolean)
Specifies whether xv installs the image's colormap
in the xv color editor window, as well as in the
image's window. By default, the program does
install the colormap in the color editor window,
however this can occasionally make the color editor
window unreadable. (This option only apples when
the '-perfect' or '-owncmap' options create their
own colormaps.)
-ninstall (Resource name: ninstall boolean)
Prevents xv from 'installing' its own colormap,
when the -perfect or -owncmap options are in
effect. Instead of installing the colormap, it
will merely 'ask the window manager, nicely' to
take care of it. This is the correct way to
install a colormap (i.e., ask the WM to do it),
unfortunately, it doesn't actually seem to work in
many window managers, so the default behavior is
for xv to handle installation itself. However,
this has been seen to annoy one window manager
(dxwm), so this option is provided if your WM
doesn't like programs installing their own col-
ormaps.
Section 9.5: 24-bit Conversion Options
The following options only come into play if you are using
xv to display 24-bit RGB data (PPM files, color PM files,
JPEG files, the output of bggen, etc.). They have no
effect whatsoever on how GIF pictures or 8-bit greyscale
images are displayed.
Rev: 2.10 Feb 26, 1992 43
xv(l) xv(l)
-quick24 (Resource name: quick24 boolean)
Forces xv to use the 'quick' 24-bit to 8-bit con-
version algorithm. This algorithm dithers the pic-
ture using a fixed set of colors that span the
entire RGB colorspace. In versions of xv prior to
2.10, this was the default algorithm. It no longer
is.
-slow24 (Resource name: slow24 boolean)
Specifies that the 'slow' 24-bit to 8-bit conver-
sion algorithm is to be used by the program. This
algorithm uses a version of Heckbert's median cut
algorithm to pick the 'best' colors on a per-image
basis, and dithers with those. This is the current
default conversion algorithm.
Advantages: The -slow24 algorithm often produces
better looking pictures than the -quick24 algo-
rithm.
Disadvantages: The -slow24 algorithm is about half
the speed of the -quick24 algorithm. Also, since
the colors are chosen on a per-image basis, it
can't be used to display multiple images simultane-
ously, as each image will almost certainly want a
different set of 256 colors. The -quick24 algo-
rithm, however, uses the same exact colors for all
images, so it can display many images simultane-
ously, without running out of colors.
-best24 (Resource name: best24 boolean)
Forces xv to use the same algorithm used in the
program ppmquant, written by Jef Poskanzer. This
algorithm also uses a version of Heckbert's median
cut algorithm, but is capable of picking 'better'
colors than the -slow24 algorithm, and it doesn't
dither.
Advantages: Generally produces slightly better
images than the -slow24 algorithm. Also, the
images are undithered, so they look better when
expanded.
Disadvantages: Much slower than the -slow24 algo-
rithm. Like, 5 to 10 times slower. The images
produced aren't that much better than those pro-
duced by the -slow24 algorithm.
-noqcheck (Resource name: noqcheck boolean)
Turns off a 'quick check' that is normally made.
Normally, before running either of the 24-bit to
Rev: 2.10 Feb 26, 1992 44
xv(l) xv(l)
8-bit conversion algorithms, xv determines whether
the picture to be displayed has more than 256
unique colors in it. If the picture doesn't, it
will treat the picture as an 8-bit colormapped
image (i.e., GIF), and won't run either of the con-
version algorithms.
Advantages: The pictures will be displayed 'per-
fectly', whereas if they went through either of the
conversion algorithms, they'd be dithered.
Disadvantages: Often uses a lot of colors, which
limits the ability to view multiple images at once.
(See the -slow24 option above for further info
about color sharing.)
Section 9.6: Root Window Options
xv has the ability to display images on the root window of
an X display, rather than opening its own window (the
default behavior). When using the root window, the pro-
gram is somewhat limited, because the program cannot
receive input events (key press and mouse clicks) from the
root window. As a result, you cannot track pixel values,
or crop, nor can you use keyboard commands while the mouse
is in the root window.
-root (Resource name: <none>)
Directs xv to display images in the root window,
instead of opening its own window. Exactly how the
images will be displayed in the root window is
determined by the setting of the -rmode option.
-rmode mode (Resource name: rootMode integer)
Determines how images are to be displayed on the
root window, when -root has been specified. You
can find the current list of 'modes' by using a
mode value of '-1'. XV will complain, and show a
list of valid modes. The current list at of the
time of this writing is:
0: tiling
1: integer tiling
2: mirrored tiling
3: integer mirrored tiling
4: centered tiling
5: centered on a solid background
6: centered on a 'warp' background
7: centered on a 'brick' background
The default mode is '0'. See "Section 3.5: The
Display Modes Menu" for a description of the
Rev: 2.10 Feb 26, 1992 45
xv(l) xv(l)
different display modes.
-noresetroot (Resource name: resetroot)
Normally, when changing from root to window display
mode, the root is set to the standard X crosshatch
pattern. Using -noresetroot or setting resetroot
to false will force the root to remain. This is
useful when comparing between different tiled
images.
-rfg color (Resource name: rootForeground string)
Sets the 'foreground' color used in some of the
root display modes.
-rbg color (Resource name: rootBackground string)
Sets the 'background' color used in some of the
root display modes.
-max (Resource name: <none>)
Makes xv automatically stretch the image to the
full size of the screen. This is mostly useful
when you want xv to display a background. While
you could just as well specify the dimensions of
your display ('-geom 1152x900' for example), the
-max option is display-independent. If you sud-
denly decide to start working on a 1280x1024 dis-
play (ferinstance) the same command will still
work. Note: If you specify -max when you aren't
using -root, the behavior is slightly different.
The image will be made as large as possible while
still preserving the normal aspect ratio.
-maxpect (Resource name: <none>)
Makes the image as large as possible while preserv-
ing the aspect ratio.
-quit (Resource name: <none>)
Makes xv display the (first) specified file and
exit, without any user intervention. Since images
displayed on the root window remain there until
explicitly cleared, this is very useful for having
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 using -root.
-clear (Resource name: <none>)
Clears the root window of any extraneous xv images.
Rev: 2.10 Feb 26, 1992 46
xv(l) xv(l)
Note: it is not necessary to do an 'xv -clear'
before displaying another picture in the root win-
dow. xv will detect that there's an old image in
the root window and automatically clear it out (and
free the associated colors).
Section 9.7: Window Options
XV currently consists of three main windows, plus one win-
dow for the actual image. These three windows (the xv
controls window, the xv info window, and the xv color edi-
tor window) may be automatically mapped and positioned
when the program starts.
-cmap (Resource name: ctrlMap boolean)
Maps the xv controls window.
-cgeom geom (Resource name: ctrlGeometry string)
Sets the initial geometry of the xv controls win-
dow. Note: only the position information is used.
The window is of fixed size.
-imap (Resource name: infoMap boolean)
Maps the xv info window.
-igeom geom (Resource name: infoGeometry string)
Sets the initial geometry of the xv info window.
Note: only the position information is used. The
window is of fixed size.
-cemap (Resource name: ceditMap boolean)
Maps the xv color editor window.
-cegeom geom (Resource name: ceditGeometry string)
Sets the initial geometry of the xv color editor
window. Note: only the position information is
used. The window is of fixed size.
-nopos (Resource name: nopos boolean)
Turns off the 'default' positioning of the various
xv windows. Every time you open a window, you will
be asked to position it. (Assuming your window
manager asks you such things. mwm, for instance
doesn't seem to ask)
Rev: 2.10 Feb 26, 1992 47
xv(l) xv(l)
Section 9.8: Miscellaneous Options
-mono (Resource name: mono boolean)
Forces the image to be displayed as a greyscale.
This is most useful when you are using certain
greyscale X displays. While xv attempts to deter-
mine if it's running on a greyscale 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 b/w monitors. The computer, of
course, has no way of knowing what type of monitor
is attached.) On these displays, if you don't
specify -mono, what you will see is a greyscale
representation of one of the RGB outputs of the
system. (For example, you'll see the 'red' output
on our greyscale Sun 3/60s.) The -mono option cor-
rects this behavior.
-white color (Resource name: white string)
Specifies the 'white' color used when the picture
is b/w stippled. (When '-ncols 0' has been speci-
fied.)
-black color (Resource name: black string)
Specifies the 'black' color used when the picture
is b/w stippled. (When '-ncols 0' has been speci-
fied.)
Try something like: 'xv -ncols 0 -bl red -wh yellow
<filename>' for some interesting, late-'60s-style
psychodelia effects.
-wait secs (Resource name: <none>)
Turns on a 'slide-show' feature. Normally, if you
specify multiple input files, xv will display the
first one, and wait for you to give the Next com-
mand (or whatever). The -wait option makes xv wait
the specified number of seconds, and then go on to
the next picture, without any user intervention.
The program still accepts commands, so it's possi-
ble to 'abort' the current picture without waiting
the full specified time by using the Next command.
-wloop (Resource name: <none>)
Normally, when running a slide-show with the -wait
option, xv will terminate after displaying the last
image. If you also specify the -wloop option, the
program will loop back to the first image and con-
tinue the slide-show until the user issues the Quit
command.
Rev: 2.10 Feb 26, 1992 48
xv(l) xv(l)
-rgb (Resource name: hsvMode boolean)
Specifies that, by default, the colormap editing
dials in the xv color editor window should be in
RGB mode. This is the normal default behavior.
-hsv (Resource name: hsvMode boolean)
Specifies that, by default, the colormap editing
dials in the xv color editor window should be in
HSV mode.
-dither (Resouce name: autoDither boolean)
When specified, tells xv to automatically issue a
Dither command whenever an image is first dis-
played. Useful on displays with limited color
capabilities (4-bit and 6-bit displays.)
-smooth (Resource name: autoSmooth boolean)
When specified, tells xv to automatically issue a
Smooth command whenever an image is first dis-
played. This is useful when you are using one of
the image sizing options (such as '-expand' or
'-max').
-crop (Resource name: autoCrop boolean)
When specified, tells xv to automatically issue an
AutoCrop command whenever an image is first dis-
played.
-visual vistype (Resource name: visual string)
Normally, xv uses the default visual model provided
by your X server. You can override this by explic-
itly selecting a visual to use. Valid types are
StaticGray, StaticColor, TrueColor, GrayScale,
PseudoColor, and DirectColor. Not all of these
are necessarily provided on any given X display.
Run xdpyinfo on your display to find out what
visual types are supported.
-cursor curs (Resource name: cursor integer)
Specifies an alternate cursor to use in the image
window (instead of the normal 'cross' cursor).
curs values are obtained by finding the character
number of a cursor you like in the 'cursor' font.
(Run 'xfd -fn cursor' to display the cursor font.)
For example, a curs value of '56' corresponds to
the (singularly useless) 'Gumby' cursor.
Rev: 2.10 Feb 26, 1992 49
xv(l) xv(l)
-keeparound (Resource name: keepAround boolean)
The '-keeparound' option is now poorly named, as
I've changed the default behavior. Now, if you
Delete the last file in the xv controls list, noth-
ing unexpected will happen. If you specify the
'-keeparound' option, which toggles the
'-keeparound' flag off, the program will automati-
cally exit as a convenience. It should probably be
renamed '-goaway' or something...
-2xlimit (Resource name: 2xlimit boolean)
By default, xv prevents the image window from ever
getting larger than the screen. Unfortunately,
because of this, if you load an image that is
larger than your screen, the image will be shrunk
until it fits on your screen. Some folks find this
undesirable behavior. Specifying the -2xlimit
option doubles the size limitations. The image
window will be kept from getting larger than 2x the
width and height of your screen.
Just in case you're wondering why there's any size
limitations: it's fairly easy to accidentally ask
for a huge image to be generated. Simply crop a
section of the image, zoom so you can see the indi-
vidual pixels, and uncrop. If there were no size
limitations, the (expanded many times) image could
be huge, and might crash your X server. At the
very least, it would take a long period of time,
and freeze your X server during part of it. Gener-
ally undesirable behavior.
-nolimits (Resource name: nolimites boolean)
For the truly daring, this turns off all limita-
tions on the maximum size of an image window.
(Well, there's still an X-imposed maximum size of
64k by 64k, but that really shouldn't be a prob-
lem.) Warning: as mentioned above, it is fairly
easy to accidentally generate a huge image when you
do an UnCrop command, and you may well crash xv,
your X server, the host machine, or all three. Use
At Your Own Risk!!!
-rv (Resource name: reverse)
Makes xv display a 'negative' of the loaded image.
White becomes black, and black becomes white.
Color images will have 'interesting' effects, as
the RGB components are individually reversed. For
example, red (255,0,0) will become cyan
(0,255,255), yellow will become blue, and so on.
Rev: 2.10 Feb 26, 1992 50
xv(l) xv(l)
-DEBUG level (Resource name: <none>)
Turns on some debugging information. You shouldn't
need this. If everything worked perfectly, I
wouldn't need this either.
-browse (Resource name: browseMode boolean)
Prevents the xv load window from being closed when-
ever you successfully load a file. This makes
'browsing' a directory somewhat more pleasant.
-nostat (Resource name: nostat boolean)
Turns off the stat() call is is performed for each
file whenever you change directories in the xv load
and xv save windows. This is useful if you're on a
machine with lots of remote files mounted on it,
and you find the directory switching to be too
slow.
-loadclear (Resource name: clearOnLoad boolean)
If you were on a PseudoColor display, xv used to
automatically clear the image window (or the root
window, if you were in a root mode), whenever you
loaded a new image. This was to prevent the poten-
tially annoying/confusing 'rainbow' effect that
happens when colormap entries are freed and reallo-
cated with different colors. Ths has changed. By
default, xv no longer clears the image/root window.
This is for two reasons: I've decided that the
rainbow effect is semi-entertaining, in that it
gives you something to look at while the next image
is being loaded. Secondly, if you are viewing a
series of images that have the same colors in them,
it's possible for xv to animate them (by using the
'-wait' command line option), albeit no faster than
one frame every 1-2 seconds. For example, you can
go get the satellite radar images from
vmd.cso.uiuc.edu (in the directory 'wx'), run 'xv
-wait 0 -wloop SA*', and voila! Just like the
evening news!
- Specifying '-' all by itself tells xv to take its
input from stdin, rather than from a file. This
lets you put xv on the end of a Un*x pipe.
Section 9.9: Color Editor Resources
You can set default values for all of the HSV and RGB mod-
ification controls in the xv color editor window via X
resources. The easiest way to explain this is with an
example.
Rev: 2.10 Feb 26, 1992 51
xv(l) xv(l)
o Start xv and put it in the background by typing 'xv &'.
o Type the command 'cat >foo' in an active xterm window
o Bring the xv color editor window up.
o Issue the Cut Resources command.
o Click your Middle mouse button in the xterm window. A
set of resource lines describing the current state of
the xv color editor controls will be 'pasted' into the
window.
o You could type '<ctrl-D>' in the xterm to complete the
cat command, edit this file, and put it in your .Xde-
faults/.Xresources file.
The lines generated by Cut Resources will look like the
following:
xv.default.huemap1: 330 30 CW 330 30 CW
xv.default.huemap2: 30 90 CW 30 90 CW
xv.default.huemap3: 90 150 CW 90 150 CW
xv.default.huemap4: 150 210 CW 150 210 CW
xv.default.huemap5: 210 270 CW 210 270 CW
xv.default.huemap6: 270 330 CW 270 330 CW
xv.default.whtmap: 0 0 1
xv.default.satval: 0
xv.default.igraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254
xv.default.rgraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254
xv.default.ggraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254
xv.default.bgraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254
These lines completely describe one state of the xv color
editor controls. There are five different states that you
can specify via X resources. The 'default' state (as
shown) holds the settings used whenever the program is
first started, and whenever the Reset command is used.
You can also store settings in one of the four xv presets
(accessed via the '1'-'4' buttons in the xv color editor)
by changing the string 'default' in the above lines to
'preset1', 'preset2', 'preset3', or 'preset4' respec-
tively.
There are four types of resource described in these lines:
huemap, whtmap, satval, and graf.
Section 9.9.1: Huemap Resources
The huemap resources describe the state of the hue remap-
ping dials. There are six huemap resources per state of
the xv color editor. These huemap resources are numbered
'huemap1', 'huemap2', ... 'huemap6', and correspond to
the '1'-'6' radio buttons under the hue remapping dials.
Rev: 2.10 Feb 26, 1992 52
xv(l) xv(l)
Each huemap resources takes six parameters:
1. The 'starting' angle of the From range, in degrees
(integer).
2. The 'ending' angle of the From range, in degrees (inte-
ger).
3. The direction of the From range. Either 'cw' (clock-
wise) or 'ccw' (counter-clockwise).
4. The 'starting' angle of the To range, in degrees (inte-
ger).
5. The 'ending' angle of the To range, in degrees (inte-
ger).
6. The direction of the To range. Either 'cw' or 'ccw'.
Section 9.9.2: Whtmap Resources
The whtmap resource describes the state of the white
remapping control. There is one whtmap resource per state
of the xv color editor controls. The whtmap resource
takes three parameters:
1. The hue to remap 'white' to, in degrees (integer).
2. The saturation to give to the remapped 'white', in per-
cent (integer).
3. A boolean specifying whether the white remapping con-
trol is enabled. If '1', the control is enabled. If
'0', the control is disabled.
Section 9.9.3: Satval Resource
The satval resource describes the value of the Saturation
dial. There is one satval resource per state. The satval
resource takes a single integer value, in the range
+/-100, which specifies how much to add or subtract to
overall image color saturation.
Section 9.9.4: Graf Resources
The graf resources describe the state of the four 'graph'
windows in the xv color editor window (Intensity, Red,
Green, and Blue). The graf resources can be in one of two
formats, 'gamma' and 'spline/line'.
In 'gamma' format, the graf resource takes two parameters:
1. The letter 'G', specifying 'gamma' mode
Rev: 2.10 Feb 26, 1992 53
xv(l) xv(l)
2. A single floating point number specifying the gamma
value.
In 'spline/line' mode, the graf resource takes a variable
number of parameters:
1. The letter 'S' specifying 'spline' mode, or the letter
'L' specifying 'line' mode.
2. An integer number indicating the number of handles
(control points) that this graph window will have.
(Must be in the range 2-16, inclusive.)
3. For each handle, there will be a ':', and the x and y
positions of the handle, separated by a comma. The x
and y positions can be in the range 0-255 inclusive.
Section 9.9.5: Other Resources
Also, there are the boolean resources 'autoApply', 'dis-
playMods', and 'autoReset', which control the initial set-
tings of the three checkboxes in the xv color editor win-
dow.
There are also boolean resources 'saveNormal', 'pspre-
view', and 'pscompress' which control the initial settings
of the checkboxes in the xv save and xv postscript win-
dows.
LIMITATIONS
xv will NOT work on displays that aren't 1-, 2-, 4-, 6-,
8-, 16- 24-, or 32-bits deep. Luckily, that should still
cover nearly every display out there. It may not work on
certain 6- or 24-bit displays.
It also only displays the first image in GIF files that
have multiple images in them.
As for PM pictures, this program only displays 1-plane
PM_I pictures, or 1-, 3-, or 4-plane PM_C pictures.
PM FORMAT
The PM format is a file format that we use at the GRASP
Lab for our image processing work. If you aren't at Penn,
you are unlikely to ever run into a PM-format file, so
don't worry about it. Please ignore all references to PM.
The 4-, 6-, 16-, 24-, and 32-bit code has not been exten-
sively tested. (A 4-bit MicroVax GPX system, a 6-bit HP
9000/320, a 16-bit Sony 3710, and a 24-bit HP 9000/350,
respectively. The 32-bit code hasn't actually been tested
Rev: 2.10 Feb 26, 1992 54
xv(l) xv(l)
at all.) You won't be able to do '-ncols 0' on a 6-, 16-,
24-, or 32-bit display, not that you should want to.
AUTHORS
John Bradley - bradley@cis.upenn.edu
GIF reading code based on gif2ras.c, by Patrick J.
Naughton (naughton@wind.sun.com)
GIF writing code essentially unchanged from code written
by Michael Maudlin (mlm@cs.cmu.edu).
SUN Rasterfile i/o code written by Dave Heath
(heath@cs.jhu.edu)
JPEG interface code written by Markus Baur
(s_baur@iravcl.ira.uka.de)
JPEG i/o code provided by the Independent JPEG Group.
TIFF i/o code and interface code written by Sam Leffler
(sam@sgi.com)
Portions of 'ppmquant' snarfed for the '-best24' algo-
rithm. ppmquant (and the rest of the pbmplus package) was
written by Jef Poskanzer. (jef@well.sf.ca.us)
fsQuick code written and supplied by David B. Rosen
(rosen@cns.bu.edu). This code is a very fast implementa-
tion of Floyd-Steinberg dithering for 1-bit b/w displays.
Rev: 2.10 Feb 26, 1992 55