xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
NAME
xv - displays and manipulates images on X11 displays
SYNTAX
xv [options] [filename [filename...]]
DESCRIPTION
xv is an X11 program that displays images in the GIF, PBM,
PGM, PPM, X11 bitmap, and PM formats on 1-, 4-, 6-, 8-, and
24-bit X displays.
OVERVIEW
xv displays one image at a time in an output window. You
can arbitrarily stretch or compress the window, and the pic-
ture will be rescaled to fit. You can rotate the picture in
90-degree steps. You can repeatedly 'crop' a picture
(define a rectangular 'region-of-interest' and 'throw away'
the rest). You can magnify any portion of the picture by
any amount, up to the maximum size of your screen.
xv allows you click on the picture to determine pixel RGB
values and x,y coordinates. You can perform arbitrary
'gamma correction' on the picture both in RGB space and HSV
space. You can specify the maximum number of colors that xv
should use, for some interesting visual effects. You can
have the program produce a stippled version of the picture
using black and white, or any other pair of colors.
xv can write images in a variety of formats, with many of
the modifications you may have made to the picture saved as
well. You can use xv to do format conversion. xv will also
automatically uncompress compress-ed files, as well as read
files from stdin.
It slices, it dices, and it'll balance your checkbook if you
aren't careful.
USING THE PROGRAM
Start the program up by typing 'xv <filename>' After a short
delay, a window will appear with the desired image displayed
in it. If you change the size of the window, (however your
particular window manager lets you do this), the picture
will rescale to fit the window.
Clicking (and dragging) the Left mouse button inside the
image window will display pixel information. The first two
numbers are the x and y offset, in pixels, from the top-left
corner of the image. The first group of three numbers are
the red, green, and blue values of that pixel from the ori-
ginal data (after any 24-bit to 8-bit conversions...). The
second group of three numbers are the red, green, and blue
values of that pixel AFTER any gamma correction (and the
Amiga Unix Last change: 1
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
'-rv' option). If you actually want to measure some pixels,
it will probably help to crop to a small region, and expand
that region quite a bit, to the point where you can see
individual pixels.
If you type 'h', '?' or click the Right mouse button inside
this window, the CONTROL BOX window will appear. This box
will contain a list of file names (just one in this example)
and many buttons.
Note: unless specified otherwise, 'click' means 'click with
the Left mouse button'.
THE CONTROL BOX
Most of the buttons in the control box let you adjust the
size of the currently shown picture. You can either click
the button, or type a keyboard equivalent inside ANY xv win-
dow (except the SAVE BOX (see below)). It should be noted
that the 'resizing' controls do not MODIFY the picture in
any way. They simply change the way the picture is
displayed, by duplicating or dropping pixels from the origi-
nal picture to produce an image of the desired size. As you
expand images, they will get 'chunkier'.
The 'Max Size' button (or 'm' key) causes the picture to be
redrawn so that it completely fills the screen. Be warned
that this might take a while, depending on the speed of your
machine. It also may cover all the other windows on the
screen, including the control window. If this happens, you
can bring the control window back to the top by clicking the
Right mouse button in the picture window one or two times.
The 'Normal' button (or 'n' key) returns the picture to it's
normal size. Normal size is defined as a 1 to 1 mapping
between pixels in the image and pixels on the screen.
(i.e., if you have a 320x200 image, the 'Normal' command
will set the 'on-screen' size to 320x200).
The only exception to this behavior is when the image is
larger than your screen. In this case, the picture is
'halved' until it fits. (For example, if you were trying to
display a 1000x600 image on an 800x600 screen, the 'Normal'
command would set the 'on-screen' size to 500x300.)
The 'Dbl Size' button (or '>' key) doubles the width and
height of the picture, under the constrant that the picture
may not be larger than the screen. (ie, if you have a
900x100 image, and a 1000x800 screen, doubling would result
in a picture size of 1000x200 (the doubling of the '900' was
clipped))
Amiga Unix Last change: 2
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
The 'Half Size' button (or '<' key) halves the width and
height of the picture.
The '+10%' button (or '.' key) adds 10% to the width and
height of the picture. (Under the same constrant as 'Dbl
Size'.)
The '-10%' button (or ',' key) subtracts 10% from the width
and height of the picture.
NOTE: The '+10%' and '-10%' buttons are NOT complementary.
If, for example, you have a 100x100 picture, '+10%' will
make it into a 110x110 picture. If you then do '-10%', you
will have a 99x99 picture. (10% of 110 = 11 ; 110 - 11 =
99) The '+10%' and '-10%' buttons have no concept of an
'original size' to use as an increment/decrement basis.
They only expand or shrink the current picture by 10% of its
current size.
The '4x3' button (or '4' key) attempts to resize the picture
so that the ratio of width to height is equal to 4 to 3.
(eg, 320x240, 400x300, etc.) This is quite useful because
most images were meant to fill the screen of whatever they
were generated on, and nearly all video screens have an
aspect ratio of 4:3. By issuing this command, the picture
will be stretched so the proportions of things will (possi-
bly) look right on your X display. (Most of which, thank
god, have square pixels.) This is particularly obvious on
pictures that have really bizarre sizes (such as the 600x200
pictures presumably meant for CGA).
The 'Aspect' button (or 'a' key) applies the 'default aspect
ratio' to the picture. (This is done automatically when the
image is first loaded.) Normally, the default aspect ratio
is '1:1', but certain GIF files may have an aspect ratio
encoded in them. You can also set the default aspect ratio
via a command-line argument or an X Resource. The idea here
is that you'd stretch the picture manually (via your window
manager) to roughly the size you'd like, then you'd click on
'Aspect' to fix-up the proportions.
The 'Rotate' button (or 'r' key) rotates the picture 90
degrees clockwise. It should be noted that when you rotate
the picture, you are rotating the ENTIRE image, even if
you're only viewing a small section of it (via cropping).
The 'Gamma' button (or 'g' key) opens up the GAMMA BOX.
(See 'GAMMA BOX', below.)
The 'Info' button (or 'i' key) opens up the INFO BOX. (See
'INFO BOX', below.)
Amiga Unix Last change: 3
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
The 'Save' button (or 's' key) opens up the SAVE BOX. (See
'SAVE BOX', below.)
CROPPING
In addition to being able to resize/rotate the image, you
can do the same to any rectangular region of the image. By
pressing the Middle mouse button in the picture window, and
dragging it, you'll be able to draw a rectangle. When this
rectangle is visible, the 'Crop' button in the CONTROL BOX
lights up, enabling the 'Crop' command.
You can 'fine-tune' the cropping rectangle by using the
arrow keys on your workstation. The arrow keys (unmodified)
will move the cropping rectangle in the requested direction,
preserving its current size. You can change the size of the
cropping rectangle by holding the 'Shift' key down and using
the arrow keys. 'Shift-Left' makes the rectangle narrower,
'Shift-Up' makes it shorter, 'Shift-Right' makes it wider,
and 'Shift-Down' makes it taller. For precise cropping,
you'll probably want the INFO BOX visible, which will tell
you the position and size of the cropping rectangle, in
image coordinates.
If you press the 'Crop' button (or the 'c' key), the parts
of the picture outside the rectangle will disappear, and the
window will shrink to the size of the rectangle. Also, the
'Crop' button will 'dim', and the 'UnCrop' button will light
up.
You can manipulate this portion of the image exactly as if
it were the entire image. You can even draw another 'crop-
ping rectangle' on it and do the 'Crop' command again.
Pressing the 'UnCrop' button (or the 'u' key) (when lit)
will return to manipulating the entire image. It will try
to keep the current 'expansion', but if that would result in
a picture larger than the screen, it will use the 'normal'
size (defined in the description of the 'Normal' button).
MULTIPLE FILES
If, when you started xv, you specified more than one file
name, you'll be able to use the file-selection controls in
the CONTROL BOX.
The CONTROL BOX will have a list of the filenames that you
specified on the command line. The names will be shown
without any common prefixes. For example, if you started xv
with the command 'xv /pic/gif/*', the filenames will be
shown without the leading '/pic/gif/'. The current filename
will be shown in reverse video.
Amiga Unix Last change: 4
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
If there's more than a screenful of file names the scrollbar
will be enabled.
You can scroll through the list a line at a time by using
the up and down arrow buttons in the scroll bar. If you
hold the button down, it will auto-repeat. If you click
inside the gray region of the scrollbar, but not on the
slider, the list will be scrolled up or down (depending on
whether you clicked above or below the slider) a page at a
time. If you click on the slider, you can drag it to
another position and let go of it.
You can also scroll through the list by clicking on the list
itself, (which will move the reverse video 'bar') and drag-
ging up or down.
In short, it behaves like a Macintosh.
You can display any picture file by double-clicking on its
filename. The current picture will go away, and the new
picture will be displayed, if possible. If xv was unable to
load the selected picture, the previous picture will be re-
displayed.
If there are multiple files, and you aren't at the end of
the list, the 'Next' button will be enabled. Clicking
'Next' (or pressing the RETURN or SPACEBAR keys) will close
the current picture and bring up the next one. This is the
normal way to view multiple images.
If there are multiple files, and you aren't at the beginning
of the list, the 'Previous' button will be enabled. Click-
ing 'Prev' (or pressing the BACKSPACE or DELETE keys) will
close the current picture and bring up the previous one.
It should be pointed out that all of these commands work
whether or not the CONTROL BOX is visible (though if it's
not visible, you'll obviously have to use the keyboard
equivalents.)
QUITTING THE PROGRAM
Pressing the 'Quit' button (or the 'q' key) will exit the
program.
THE INFO BOX
The INFO BOX displays several bits of information. In addi-
tion to credits and a revision date, the INFO BOX displays
information about the currently displayed picture. It shows
the current file name, the format of the current file, its
size, and its resolution. This information is available
early in the loading process, and is displayed as soon is it
is known. The rest of the lines are filled in after the
Amiga Unix Last change: 5
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
picture has been loaded.
The 'Cropping' line displays the coordinates of the current
cropping rectangle. Normally, this line says 'none', but if
you draw a cropping rectangle on the picture (see CROPPING,
above) it will display the size and position of the rectan-
gle in Image Coordinates. The first two numbers are the
width and height of the rectangle, respectively. The second
pair of numbers specifies where the upper-left corner of the
rectangle is, as an offset from the upper-left corner of the
entire image.
The 'Expansion' line shows the effects of any stretching
that you may have done to the picture. The first pair of
numbers represent the stretching as a ratio of two scaling
factors. Normally, they will be '1x1', which indicates that
one data pixel maps to one screen pixel, in both x and y
axes. For example, the values '2x3' would indicate that the
image or sub-image has been made twice as wide as normal,
and three times as high as normal. The second pair of
numbers, (the ones in parenthesis) simply display the
current screen size of the image.
The 'Colors' lines displays how successful the color alloca-
tion schemes have been. Normally, xv uses a three-pass
color allocation algorithm. In the first pass, the program
requests every color that the picture requires to be
displayed properly. The results of this attempt are printed
on the first 'Colors' line. If everything worked out per-
fectly, this line will say "Got all x desired colors.", and
may append "(y unique)". In this string, x is the number of
colors that the picture required. If the 'unique' string is
appended, that means that some of the colors were duplicates
of one another, and the picture only REALLY needed (and was
only allocated) y colors.
If xv wasn't able to get all the colors it wanted, it will
run the second-pass color allocation code. In this pass,
the program will ask the display what colors it has avail-
able in its colormap, dtermine which of those colors are
'close' to the desired colors, and try to allocate those
colors. The program will print "Got x 'close' colors." if
it performed the second pass allocation. This is so that
the user will know that image displayed is not as well as it
could possibly be.
Finally, if even that didn't work, xv will normally attempt
to 'borrow' colors from the colormap without actually allo-
cating them. These colors are not owned by the program, and
they can change without xv's knowledge. If this third pass
is executed, the program will print "'Borrowed' x colors."
Amiga Unix Last change: 6
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
It should be noted that the '-noglob', '-perfect', and '-rw'
options modify the way color allocation is handled in xv,
and will therefore modify what will be displayed in the INFO
BOX. For example, if you specify '-noglob', xv will never
'borrow' colors, so you'll never see a third-pass line.
Finally, the INFO BOX will display warning messages that
occur while loading the image. In particular the message
'File appears truncated, winging it' comes to mind, from the
GIF image loading code.
THE GAMMA BOX
The GAMMA BOX is used to control image brightness, contrast,
and to get some fairly bizarre effects. The majority of
this box is taken up by a window that displays the current
gamma correction curve. This curve defines a mapping
between the input values (0-255) along the x axis, and the
output values (0-255) along the y axis. How these values
are interpreted depends on the setting of the 'HSV/RGB Mode'
button. (see below)
The gamma curve is defined by four 'control points', two of
which are locked at the left and right edges of the window.
These two points may only move up and down. The other two
points may be moved freely around the window, subject only
to the constraint that they cannot be moved past one another
on the x axis. The 'left' point must stay to the left of
the 'right' point.
The gamma curve can be adjusted in a variety of ways. You
can change the curve directly by clicking on one of the con-
trol points and dragging it. Also, you can indirectly
adjust the curve by using the 'Brighter', 'Dimmer',
'Sharper', and 'Duller' buttons.
The 'Apply' button takes the current gamma curve, and
applies it to the ORIGINAL picture data, according to the
setting of the 'HSV/RGB Mode' button, and displays the
results. It's important to note that the gamma curve is
always applied to the original data. It is not applied to
the currently-displayed data. Thus, if you draw a gamma
curve that makes pictures darker, and click 'Apply' several
times, it will only (noticably) do anything the first time.
It will NOT keep making the picture darker. Also, it should
be noted that the apply button is very often unnecessary.
If you are running on a 1-bit b/w display, or you specified
'-ncols 0' on the command line, the gamma curve will be
automatically applied every time you DIRECTLY modify the
curve (by dragging a control point). If you specified the
'-rw' option on the command line, the gamma curve will be
automatically applied every time it is changed (by any
means). (Keyboard equivalent: 'p')
Amiga Unix Last change: 7
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
The 'No Gamma' button shows the original picture with no
gamma correction, but does not affect the current gamma
curve. It just ignores it. You can use this command to do
A/B comparisions between the original picture and your
'improved' version.
The 'Linear' button sets the gamma curve to a straight line
from 0,0 to 255,255. This has the effect of displaying the
picture without any apparent gamma correction, much like the
'No Gamma' command, however, this command also resets the
curve. This command serves as an "Aaah! I've screwed it up
horribly!" fix.
The 'Default' button sets the gamma curve to its default
setting. Normally, this is a straight line, exactly the
same as the 'Linear' command. However, by specifying the
'-GAMMA' option on the command line, or by defining the
'xv.gamma' resource, it is possible to the the default gamma
correction to something else entirely.
The 'Spline' button is actually a two-state switch that
displays its current setting. It controls how the four con-
trol points are connected. By default, they are connected
by a spline curve. Unfortunately, some gamma curves are
hard to get (or impossible) in this mode. Clicking the
'Spline' button will toggle it to 'Lines'. The control
points will now be connected by straight lines. Clicking
the button again will set it back to 'Spline'.
The 'Close' button hides the GAMMA BOX. Use the 'Gamma'
command (see CONTROL BOX, above) to make it visible again.
The 'Brighter' button makes the picture brighter. Unless
you're running in '-rw' mode, you'll have to press 'Apply'
to see the effect.
The 'Dimmer' button makes the picture dimmer.
The 'Sharper' button increases the contrast of the picture.
The 'Duller' button decreases the contrast of the picture.
The 'HSV/RGB Mode' button is a two-state switch that
displays its current setting. It affects HOW the gamma
curve is used. By default, it is in 'HSV Mode'. In this
mode, the colors of the picture are converted from the RGB
model (red, green, and blue) into the HSV model (hue,
saturation, and value). The gamma curve is applied to the
'value' (brightness) of the HSV colors. The (modified) HSV
colors are converted back to RGB colors so that they may be
displayed. In this mode, colors are made brighter or dim-
mer, according to the curve, but their Hue and Saturation is
Amiga Unix Last change: 8
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
not changed. This is generally the more desirable way to
apply gamma correction to color pictures.
When the 'HSV/RGB Mode' button is in 'RGB Mode', the gamma
curve is applied to each of the RGB components (red, green,
and blue) separately. This can have some interesting
effects, particularly when you use a drastic gamma correc-
tion curve. For example, assume a gamma curve that is a
straight line from 0,255 to 255,0 (top-left to bottom-right,
instead of the 'normal' bottom-left to top-right). In HSV
Mode, this curve will merely take 'dark' colors and make
them 'light', and vice-versa. (i.e., dark blue <-> light
blue). The RGB Mode, on the other hand will COMPLEMENT the
colors. (blue <-> yellow, red <-> cyan, and green <->
violet). Both modes will do (black <-> white), however.
The RGB Mode is mainly for amusement value.
It should be noted that when viewing greyscale pictures, it
makes no difference whether you are in HSV or RGB mode.
Both modes will behave exactly the same. Also, note that
when the '-rw' option is specified, gamma correction is per-
formed AFTER the reversal.
xv allows you to have four gamma 'presets'. By default,
they have four vaguely useful curves. You can 'load' them
by clicking on the '1', '2', '3', or '4' buttons, respec-
tively. You can 'write' them by clicking 'Set', and click-
ing one of the numbered buttons. The current gamma correc-
tion curve will be 'stored' in the preset number you
clicked, and will remain there until overwritten, or until
you exit the program.
Notes: The Spline/Lines and HSV/RGB settings are NOT stored
in the presets. A weakness, admittedly. You can specify
your own 'default settings' for the presets by setting the X
resources 'xv.gamma1', 'xv.gamma2', etc.
The 'Undo' button undoes the last change to the gamma curve.
Currently, the undo buffer is eight slots long, so you can
undo up to the last eight changes. There is no way to 'undo
an undo', however. As with presets, the Spline/Lines and
HSV/RGB settings are not saved, nor are they considered
'changes'.
At the top of the GAMMA BOX are six numbers that define the
current gamma correction curve. The numbers are, in order,
the y-coordinate of the first control point, the x- and y-
coordinates of the second and third control points, and the
y-coordinate of the fourth control point. These numbers
appear in the same order that they would be specifed to the
'-GAMMA' command line option, or the 'xv.gamma',
'xv.gamma[1-4]' X resources.
Amiga Unix Last change: 9
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
THE SAVE BOX
When you issue the 'Save' command (by clicking the 'Save'
button in the CONTROL BOX (above), or typing 's' in any of
the xv windows, the SAVE BOX will appear, giving you an
opportunity to write the current file to disk. The file
will consist of the currently-visible portion of the pic-
ture. Normally, this would be the entire picture, but if
you 'crop' first, and then save, it will only save the
cropped-to region. If the picture has been rotated, the
rotation will also be saved in the file. If a gamma correc-
tion curve has been applied to a picture, the picture will
be saved with the gamma correction.
Major Bummer: As noted elsewhere, xv stores images inter-
nally as 8-bit colormapped images. If you load a 24-bit
color image, it is converted to an 8-bit image IMMEDIATELY,
and the 24-bit version is thrown away. As such, you do not
REALLY want to use xv to modify (crop, rotate, etc.) 24-bit
images, as much of the information will be lost in the
translation.
Saved images are not affected by the display that they were
saved on. For example, if you displayed a full-color image
on a 1-bit b/w display, it would be dithered in black and
white. If you save the image, by default, it will be saved
as a full-color image. All the data will still be there.
When you open up the SAVE BOX, it will display the contents
of the current directory in a scrollable list. Next to each
file name will be an icon representing its file type. Sub-
directories will be shown as 'file folders', for instance.
You can go 'down' the directory tree by 'Open'-ing a sub-
directory, either by clicking on its name and clicking the
'Open' button, or by double clicking on the name. (Note:
You can only 'Open' directories and symbolic links. Other
files are displayed merely as a navigational aid.)
You can go 'up' the directory tree by clicking on the button
at the very top of the SAVE BOX. A pop-up menu will appear,
with the current directory name at the top, and its parent
directories listed below it. Drag the mouse to any direc-
tory in this list and let go. You will switch to that
directory.
Once you are in the correct directory, you can save the file
by typing a simple file name (no /'s) and clicking 'Save' or
pressing return. Ctrl-U or Ctrl-K will clear the line. By
default, the file will be saved as a full-color GIF file, in
'Normal Size'. You can choose the format by clicking on the
buttons at the bottom of the window. Note that some combi-
nations are not possible (for example, X11 Bitmaps can only
be saved as 'B/W Dithered'). Also, the 'PBM (raw)' and 'PBM
Amiga Unix Last change: 10
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
(ascii)' formats actually cover all PBM/PGM/PPM formats.
The particular format is chosen according to the setting of
the 'Colors' control.
The 'Cancel' button gets rid of the SAVE BOX. You'll have
to issue the 'Save' command to make it visible again.
The 'Quit' button exits xv. It is provided as a conveni-
ence, as you'll often want to quit immediately after saving
a file.
Note: Since the SAVE BOX is expecting you to type a file
name, you cannot execute keyboard commands (see 'Shortcuts',
below) while the keyboard focus is in this window (gen-
erally, whenever the mouse is in this window).
COMMAND LINE OPTIONS
There are a Vast Multitude of options. Note: only the first
few unique characters of an option name are required. For
example, '-d' is a legal abbreviation for '-display', but
you'd have to give '-nc' as an abbreviation for '-ncols',
because there's another option that starts with the letter
'n'.
That said...
GENERAL OPTIONS
-help Print usage instructions, listing the current
available command-line options. Any unrecog-
nized option will do this as well.
-display 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 Sets the foreground color used by the windows.
(Resource name: foreground. Type: string)
-bg Sets the background color used by the windows.
(Resource name: background. Type: string)
-bw Sets the width of the border on the windows.
Your window manager may choose to ignore this,
however. (Resource name: borderWidth. Type:
integer)
WINDOW SIZING OPTIONS
-geometry 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
Amiga Unix Last change: 11
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
specified. (Resource name: geometry. Type:
string)
-fixed 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. When
you do this, xv will now use the geometry size
as a MAXIMUM window size. It will, however,
preserve the original aspect ratio of the pic-
ture. For example, if you give a rectangular
geometry of '320x240', and you try to display a
square picture of '256x256', the window opened
will actually be '240x240', which is the largest
square that still fits in the '320x240' rectan-
gle that was specified. (resource name: fixed)
-expand Lets you specify an initial expansion or
compression factor for the picture. It expects
an integer value. Values larger than 1 multiply
the picture's dimensions by the given factor.
(ie, an expand factor of '3' will make a 320x200
image display as 960x600). Factors less than
zero are treated as reciprocals. (ie, an expand
factor of '-4' makes the picture 1/4th its nor-
mal size.) '0' is not a valid expansion factor.
(resource name: expand)
-aspect 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 many 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 pic-
ture is. It operates on a pixel-by-pixel basis,
stretching each image pixel slightly, in either
width or height, depending on the ratio. Aspect
ratios greater than '1' make the picture wider
than normal. Aspect ratios less than 1 make the
picture taller than normal. (Useful aspect
ratio: A 512x480 image that was supposed to
fill a standard 4x3 video screen should be
Amiga Unix Last change: 12
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
displayed with an aspect ratio of 5:4)
(Resource name: aspect. Type: string)
COLOR ALLOCATION OPTIONS
-ncols Sets the maximum number of colors that xv will
use. Normally, this is set to 'as many as it
can get'. (ie, 2^(depth of screen)) However,
you can set this to smaller values for interest-
ing 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.) (Resource name: ncols. Type: integer)
-nglobal 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
colormap, and 'borrow' any colors it deems
appropriate. These borrowed colors are, how-
ever, NOT owned by xv, and as such, can changed
without xv's permission, or knowledge. If this
happens, the displayed 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 suc-
cessfully allocated, which makes it immune to
any color changes. (Resource name: nglobal.
Type boolean)
It should be noted that 'use global colors' is
the default because color changes aren't gen-
erally a problem if you are only using xv to
display a picture 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 back-
ground). In such cases you will want to specify
'-nglobal'. Note: using the '-ncols' or '-root'
options automatically turn on '-nglobal'.
-rw Tells xv to use read/write color cells. Nor-
mally, xv allocates colors read-only, which
allows it to share colors with other programs.
If you use read/write color cells, no other pro-
gram 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 the Gamma window
to operate many times faster. (Resource name:
rwColor. Type: boolean)
Amiga Unix Last change: 13
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
-perfect 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 allo-
cate all the desired colors. This option is not
allowed in conjunction with the '-root' option.
(Resource name: perfect. Type boolean)
-ninst Prevents xv from 'installing' its own colormap,
when the '-perfect' option is 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 (ie, ask the WM to do it), unfor-
tunately, 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
colormaps. Note that this is ONLY relevant if
A) '-perfect' has been specified and B) xv ran
out of colors and generated its own colormap.
(Resource name: ninstall. Type: boolean)
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,
and the output of bggen). They have no effect whatsoever on
how GIF pictures or 8-bit greyscale images are displayed.
-slow24 Specifies that the 'alternate' 24-bit to 8-bit
conversion algorithm is to be used by the pro-
gram. The default algorithm dithers the picture
using a fixed set of colors that roughly approx-
imate all displayable colors. The '-slow24'
algorithm picks the 'best' colors on a per-image
basis, and dithers with those. Advantages: The
'-slow24' algorithm often produces better look-
ing pictures. Disadvantages: The '-slow24'
algorithm is about half the speed of the default
algorithm. Since the colors are chosen on a
per-image basis, it can't be used to display
multiple images, as each image will almost cer-
tainly want a different set of 256 colors. The
default algorithm, however, uses the same exact
colors for all images, so it can display many
images simultaneously, without running out of
colors. Also, the '-slow24' algorithm occasion-
ally produces worse-looking pictures than the
default algorithm, particularly on displays with
very few colors. The default algorithm produces
Amiga Unix Last change: 14
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
nice, dependably 'okay' pictures. (Resource
name: slow24. Type: boolean)
-noqcheck Turns off a 'quick check' that is normally made.
Normally, before running either of the 24-bit to
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 (ie, GIF), and won't run
either of the conversion algorithms. Advan-
tages: 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.) (Resource
name: noqcheck. Type: boolean)
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 program
is somewhat limited, because the program cannot receive
input events (key press and mouse clicks) from the root win-
dow. 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 Directs xv to display images in the root window,
instead of opening its own window. Images will
be displayed in the upper left corner of the
screen, and will be repeated as many times as
necessary to fill the entire screen. (Resource
name: <none>)
-tile Makes xv shrink images so that they fit on the
screen an integer number of times (in both
directions). The default behavior will gen-
erally chop off the bottom and right sides of
the images along the bottom and right sides of
the screen. Disadvantage: will slightly change
the aspect ratios of the images. (Resource
name: tile. Type: boolean)
-max 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 (ie, '-geom 1152x900' for example),
the -max option is display-independent. If you
Amiga Unix Last change: 15
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
suddenly decide to start working on a 1280x1024
display (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. (Resource name: <none>)
-quit 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'. (Resource name: <none>)
-clear Clears the root window of any extraneous xv
images. While there are other ways of clearing
the root window of an X display, such as
'xsetroot', you must use the '-clear' option to
free up the other resources allocated by xv, in
particular, the colormap entries. Note: it is
not necessary to do an 'xv -clear' before
displaying another picture in the root window.
xv will detect that there's an old xv image in
the root window and automatically clear it out
(and free the associated colors). (Resource
name: <none>)
WINDOW OPTIONS
xv currently consists of four main windows, plus one window
for the actual image. Of those four, three of them (the
CONTROL BOX, the INFO BOX, and the GAMMA BOX) may be
automatically mapped and positioned when the program starts.
-cmap Maps the CONTROL BOX. (Resource name: ctrlMap.
Type: boolean)
-cgeom Sets the initial geometry of the CONTROL BOX.
Note: only the position information is used.
The CONTROL BOX is of fixed size. (Resource
name: ctrlGeometry. Type: string)
-imap Maps the INFO BOX. (Resource name: infoMap.
Type: boolean)
-igeom Sets the initial geometry of the INFO BOX.
Note: only the position information is used.
The INFO BOX is of fixed size. (Resource name:
infoGeometry. Type: string)
Amiga Unix Last change: 16
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
-gmap Maps the GAMMA BOX. (Resource name: gammaMap.
Type: boolean)
-ggeom Sets the initial geometry of the GAMMA BOX.
Note: only the position information is used.
The GAMMA BOX is of fixed size. (Resource name:
gammaGeometry. Type: string)
MISCELLANEOUS OPTIONS
-rv Reverses the colors of the image, so that white
becomes black and black becomes white. This has
'interesting' effects on color images, however.
(For instance, red (255,0,0) becomes cyan
(0,255,255)) (Resource name: reverseVideo.
Type: boolean)
-mono Forces the image to be displayed as a grayscale.
This is most useful when you are using certain
grayscale X displays. While xv attempts to
determine if it's running on a grayscale
display, many X displays lie, and claim to be
able to do color. (This is often because they
have color graphics boards hooked up to b/w mon-
itors. 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 grayscale representation
of one of the RGB outputs of the system. (For
example, you'll see the 'red' output on our
grayscale Sun 3/60s.) The '-mono' option
corrects this behavior. (Resource name: mono.
Type: boolean)
-white Specifies the 'white' color used when the pic-
ture is b/w stippled. (When '-ncols 0' has been
specified.) (Resource name: white. Type:
string)
-black Specifies the 'black' color used when the pic-
ture is b/w stippled. (When '-ncols 0' has been
specified.) Try something like 'xv -ncols 0 -bl
red -wh yellow <filename>' for some interesting,
late-'60s-style psychodelia effects. (Resource
name: black. Type: string)
-GAMMA Sets up the default gamma-correction curve. It
can be used for contrast and/or brighness con-
trol. The curve defines a transformation
between input pixel intensity values (from the
picture) and output pixel intensity values
(which get displayed). The curve is specified
Amiga Unix Last change: 17
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
by four points in the range 0,0 <-> 255,255.
The points must be in strict left-to-right
order. The first point is fixed at x=0. The
last point is fixed at x=255. The parameters to
the '-GAMMA' option are, in order, the y-value
of the first point, the x and y values of the
second point, the x and y values of the third
point, and the y value of the last point.
(These are the same numbers that appear above
the gamma correction curve in the GAMMA BOX (see
below)). (Resource name: gamma. Type: six
integers)
You can also specify default values for the 4
gamma 'presets' in the GAMMA BOX. The format is
the same as above, and the resource names are
'gamma1', 'gamma2', 'gamma3', and 'gamma4'.
-autogamma Tells xv to apply the 'default' gamma correction
(set by the '-GAMMA' option or the 'gamma'
resource) to the image automatically, before the
image is ever displayed. (Resource name: auto-
Gamma)
-fish Turns on some animated fish that are displayed
whenever xv is loading or resizing an image.
Note: This option may cause 'X Protocal Errors'
on slower X displays. Use at your own risk.
(Resource name: fish. Type: boolean)
-wait 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' command (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 possible to
'abort' the current picture without waiting the
full specified time by using the 'Next' command.
(Resource name: <none>)
SHORTCUTS
Commands and their keyboard equivalents:
Next Picture: <SPACE>, <RETURN>
Previous Picture: <BS>, <DEL>
Quit XV: 'q'
Open/Close Control Box: 'h', '?', Right Mouse Button
Open/Close Info Box: 'i'
Open/Close Gamma Box: 'g'
Open Save Box: 's'
Aspect: 'a'
Amiga Unix Last change: 18
xv(l) MISC. REFERENCE MANUAL PAGES xv(l)
Rotate: 'r'
4x3: '4'
Crop: 'c'
Uncrop: 'u'
Normal: 'n'
Max Size: 'm'
Shrink 10%: ','
Grow 10%: '.'
Half Size: '<'
Double Size: '>'
Apply Gamma: 'p'
LIMITATIONS
xv will NOT work on displays that aren't 1-, 4-, 6-, 8-, or
24-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-, and 24-bit code has not been extensively tested.
(A 4-bit MicroVax GPX system, a 6-bit HP 9000/320, and a
24-bit HP 9000/350, respectively.) You won't be able to do
'-ncols 0' on a 6- or 24-bit display.
AUTHOR
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).
Amiga Unix Last change: 19