ZGV(1)
NAME
zgv - view GIF/JPEG/PPM/BMP/TGA/PCX/PNG/mrf files on
VGA/SVGA displays
SYNOPSIS
zgv [ -bcghijklpstTz ] [ -a alt_cmd ] [ -J jpg_decmp_type
] [ -M mousetype ] [ -m modespec ] [ -r seconds ] [
dirname | filename | filename1 ... filenameN ]
DESCRIPTION
Zgv is an svgalib-based picture viewer capable of display-
ing GIF files, JPEG/JFIF files (using the Independent JPEG
Group's JPEG library), PNG files (using libpng and zlib),
PBM/PGM/PPM files as used by pbmplus and netpbm, Microsoft
Windows and OS/2 BMP files, Targa (TGA) files, PCX files,
and mrf files.
Zgv displays which picture files are in the current direc-
tory, and also lists subdirectories and a parent directory
if there are any present. On selecting one of these, zgv
will either display it if it is an image, or change direc-
tory if not. By default, small "thumbnail" versions of
the pictures are also shown on the file selector. However,
to create these, you should press `u' (see VISUAL SELECTOR
and KEYS below).
OPTIONS
-a use alternate command when viewing. This lets you
use zgv as a front-end to something else. The
alt_cmd string should be the command to run, which
will be run in a subshell with the first instance
of `%s' replaced with the full filename of the file
selected. Note that this option does not affect
viewing of tagged files.
-b blockcursor toggle, gives outline cursor not the
`3d effect' cursor.
-c centre toggle, whether to centre pictures on the
screen (defaults to on, so using -c will turn it
off).
-g betterpgm toggle, whether to use 8-bit or high-
colour modes for PGM files (8-bit is used if this
option isn't given).
-h display a list of options and a terse description
of what the options do.
-i ignore errors and display what picture has been
able to be read anyway, if possible. The flag has
no effect if zgv isn't started on a file or files
as given on the command line. (Even then it only
has an effect for GIF and PNG files, which in zgv
give errors rather than warnings perhaps a little
too freely.) You can view a file you are download-
ing as it downloads with something like `zgv -ir 1
filename'. This should work for all file types.
It's particularly effective with interlaced PNG
files - with those you should be able to see a
blocky but full-size image when only 15% of the
file has been downloaded. The quality gets progres-
sively better as the file downloads (though due to
the implementation of the PNG decompression, the
image is likely to appear in `chunks'). The same
applies to interlaced GIFs, to a lesser degree.
With other image types, the effect is more as you
might expect - the as-yet-unloaded area of the
image, usually the bottom, is blank.
-J sets JPEG speed/quality tradeoff - `1' = floating-
point - (very) slow but accurate, `2' = slow inte-
ger - faster but not as accurate, `3' = fast inte-
ger - fastest but less accurate still. The default
tradeoff is `2'.
-j jpeg24bit toggle - defaults to on, so using -j will
turn it off. (This affects all 24-bit files, not
just JPEGs!)
-k vkludge toggle, smoothes slightly in 320x400 and
360x480 modes, and also when `zooming' a big pic-
ture down to screen size.
-l loop `forever' in slideshows (actually until you
press Esc). If this option is not specified, zgv
will stop the slideshow at the end of the file
list.
-M tell zgv to use mouse support. The mousetype argu-
ment should be one of `ms' (Microsoft), `msc'
(Mouse Systems Corp.), `mm' (MM Series), `logi'
(Logitech), `bm' (BusMouse), `sun' (MSC 3-bytes),
or `ps2' (PS/2) - this sets which type of mouse you
have. The file /dev/mouse must be (possibly a link
to) the device your mouse is connected to, for
example /dev/ttyS0.
-m startup mode; the modespec should be in quotes but
otherwise in the same format as the .zgvrc entry
startmode e.g. "640 480 8" (see CONFIGURATION
below).
-p toggles progress report when loading single file.
If set, this stops zgv displaying the progress
report bar while loading files when invoked with
something similar to "zgv wibble.gif". The one-
file_progress config file option has the same
effect.
-r if seconds is >0, then any picture displayed is re-
read and redisplayed (without clearing the screen
first) every seconds seconds. If it is equal to -1,
then the picture is re-read as often as possible.
If zero, the picture is only read once - the
default. Unless this option has suddenly inspired
you to write an interesting little shell script,
you're unlikely ever to have a use for it. :-)
-s causes zgv to output the x and y offsets, width and
height of the section of the image being displayed
when you press Esc. Can be useful for things like
"pnmcut `zgv -s input.ppm` input.ppm > output.ppm".
-t thicktext toggle, makes the text a little bit
clearer, kind of (has no effect unless -b is speci-
fied too).
-T echo tagged files on exit. This can be useful in
constructions something like "mv `zgv -T` /tmp",
which moves to /tmp only the files you select.
-z zoom toggle, i.e. whether to scale pictures to the
screen size.
filename
makes zgv auto-load the file, and exit when you
exit from viewing the picture. This also makes it
possible to view single files without the usual
extensions such as `.gif', etc.
dirname
causes the program to start with dirname as the
current directory for the file selector. (What
really happens is that whenever a filename or
dirname is specified on the command line, the named
file is tested to see if it is a directory, and the
appropriate action is taken.)
filename1 ... filenameN
causes zgv to do a slideshow of the specified
files. This is useful for things like `zgv ~/graph-
ics/*.jpg'. You may want to specify -l so that zgv
will loop around these pictures until Esc is
pressed.
All options are processed after any $HOME/.zgvrc or
/etc/zgv.conf file.
KEYS
The keys when using the file selection screen are as fol-
lows:
Esc exit zgv.
x same as above.
k move the selection pointer up.
j move the selection pointer down.
h move the selection pointer left.
l move the selection pointer right.
Home or Ctrl-A
move to the start of the directory listing.
End or Ctrl-E
move to the end of the directory listing.
PgUp or Ctrl-U
move back (almost) a page in the directory listing.
PgDn or Ctrl-V
move forward (almost) a page in the directory list-
ing.
Enter views the image, or changes to the directory (while
waiting for an image to be loaded, you can press
Esc to abort - on JPEGs and other 24-bit files in
8-bit mode, you may have to wait a while for this
to be acknowledged).
: (colon)
display the full filename of the currently-selected
file. Can be useful if zgv has abbreviated it due
to lack of room.
v switch between the visual selector (default, file-
names + pictures) and the text selector (filenames
only).
c in 640x480x16 mode, switch between colour and
monochrome thumbnails.
f or z toggle proper full-screen file selector, i.e. with-
out the logo. Why two keys for it? Well, `f' stands
for `full-screen', while `z' is by analogy with its
function when displaying a picture (see below).
Ctrl-R or Ctrl-L
rescan the current directory, and redisplay the
screen.
D or Delete
deletes the image file, if you have permission to
do so. You are prompted to confirm the deletion,
unless nodelprompt is set (see CONFIGURATION). If
there is a thumbnail for the image, that will be
deleted too.
t tags an image.
T tags all images in the current directory.
n untags an image.
N untags all images in the current directory.
Space toggle whether an image is tagged or not.
Tab does a `slide show' of all tagged files, waiting a
few seconds between displaying each image. (In
practice, the wait time will vary as the next image
is loaded while the previous image is still
onscreen.) Pressing Esc will abort the `slide
show'.
? shows a help page summarising (some of) these keys.
The cursor keys or the keys `q', `a', `o', `p' can also be
used to move the pointer. Note that PgUp/Ctrl-U and
PgDn/Ctrl-V actually move the pointer back/forward
(nearly) a page rather than moving the files listed
back/forward, which will probably seem a little odd.
When using the visual selector, there is the addition of
`u', which updates the picture index. (And also `d' which
updates the index for subdirs.) New thumbnail files are
created if either no thumbnail exists for a given file, or
the file was modified more recently than the existing
thumbnail file. Note that errors reading a picture file
are not reported when generating thumbnail files - the
file is simply left without a thumbnail.
The keys used by zgv when viewing an image are as follows:
Esc returns to file selection screen.
x same as above.
k scrolls up the image.
j scrolls down the image.
h scrolls left along the image.
l scrolls right along the image.
K scrolls up (larger step).
J scrolls down (larger step).
H scrolls left (larger step).
L scrolls right (larger step).
Home or Ctrl-A
moves to the top-left of the image.
End or Ctrl-E
moves to the bottom-right of the image.
PgUp or Ctrl-U
moves (almost) a screen's height up in the image.
PgDn or Ctrl-V
moves (almost) a screen's height down in the image.
- moves (almost) a screen's width left in the image.
= moves (almost) a screen's width right in the image.
4 changes to 640x480 16-colour mode, which (somewhat
poorly) tries to emulate a 640x480x256 mode. Don't
bother with this mode if you have a real
640x480x256 mode; it's purely intended for those
with only a standard VGA (i.e. not SVGA) card, so
they have access to some kind of tolerably hi-res
mode. No other 16-colour modes are supported, or
ever will be. See the section below headed THE
VIEWER'S 640x480 16-COLOUR MODE for details.
5 changes to 320x200x256 mode.
6 changes to 320x240x256 mode.
7 changes to 320x400x256 mode. (This acts like a
`virtual' 640x400 mode by `squashing' the image
horizontally.)
8 changes to 360x480x256 mode. (This acts like a
`virtual' 720x480.)
C in 640x480 16-colour mode, switch between greyscale
and dithered colour.
v toggles vkludge mode, which smoothes when in zoom
mode or a `virtual' mode.
The following modes are available only on SVGA cards sup-
ported by svgalib, and then only if your card has such a
mode. However, you should try these first, as they're
preferable if available.
Tab tab is used as a prefix for the highest-res modes.
So for example, pressing tab then F5 changes to
1600x1200x256 mode (if supported).
F1 use 640x480x256 (1152x864x256 if after tab).
F2 use 800x600x256 (1152x864x15bit if after tab).
F3 use 1024x768x256 (1152x864x16bit if after tab).
F4 use 1280x1024x256 (1152x864x24bit if after tab).
F5 use 320x200x15bit (1600x1200x256 if after tab).
F6 use 320x200x16bit (1600x1200x15bit if after tab).
F7 use 320x200x24bit (1600x1200x16bit if after tab).
F8 use 640x480x15bit (1600x1200x24bit if after tab).
F9 use 640x480x16bit.
F10 use 640x480x24bit.
SF1 (i.e. shift + F1) use 800x600x15bit.
SF2 use 800x600x16bit.
SF3 use 800x600x24bit.
SF4 use 1024x768x15bit.
SF5 use 1024x768x16bit.
SF6 use 1024x768x24bit.
SF7 use 1280x1024x15bit.
SF8 use 1280x1024x16bit.
SF9 use 1280x1024x24bit.
c toggles whether image is centred on screen or not
(normally, it is).
z toggles `zoom' mode which scales the image to fit
the screen.
s scales up the image (see SCALING below for
details).
S scales down the image.
d scales up the image by doubling the size of pixels.
D the opposite - halves the pixel size.
i toggles interpolation in scaling mode - this is
slow!
1 (one)
toggles between next pixel and next-but-one pixel
to interpolate towards in interpolation + scaling
mode.
n return to `normal' mode - no scaling/interpolation,
and no zoom.
r rotates the image by 90 degrees clockwise.
R rotates the image by 90 degrees anti-clockwise.
m mirrors (horizontally reflects) the image.
f `flips' (vertically reflects) the image.
, decreases contrast.
. increases contrast.
< decreases brightness.
> increases brightness.
* reset contrast and brightness to normal.
Ctrl-P view previous file in directory.
Ctrl-N view next file in directory.
Backspace
view previous file in directory, without showing
progress report while loading; during a slideshow,
skips to next file without waiting.
Enter view next file in directory, without showing
progress report while loading; during a slideshow,
skips to next file without waiting.
Space toggle whether this image is tagged or not, then
view next file in directory; during a slideshow,
skips to next file without waiting.
? shows a help page summarising (some of) these keys.
The cursor keys act like `H', `J', `K', `L' in that they
move around the image in larger steps. The keys `q', `a',
`o', `p' can be used in exactly the same way the `h', `j',
`k', `l' keys can (i.e. with or without shift). Note that
F11 is equivalent to SF1, and F12 is equivalent to SF2.
If you are viewing an 8-bit file, like a GIF (or a 24-bit
file in 8-bit mode) then you must use 256 colour (eight
bit) modes - 15, 16 and 24-bit modes are not allowed. The
reverse is true when viewing a 24-bit file in 24-bit mode.
You can use the ^C key at any time to instantly stop the
program. This is rather a last-ditch exit, however, and
should only be used if some operation is unbearably slow
and you want to kill the whole thing off.
USING A MOUSE
You must either specify the -M option when starting zgv
for mouse support to be enabled (see OPTIONS for details),
or, probably more convenient if you intend to use the
mouse often, put mouse type in the config file (see CON-
FIGURATION for details).
Moving the mouse acts as the cursor keys would, in both
the file selector and when viewing a picture.
In the file selector, the left button views a picture
(like Enter) and the right button tags/untags a picture
(like Space).
When viewing a picture, the left button goes to the next
picture (like Enter) and the right button goes to the pre-
vious picture (like Backspace).
If redisplay of the picture takes a long time, zgv can lag
behind mouse input somewhat. This shouldn't be much of a
problem unless you use scaling with interpolation, and if
you use that you're beyond help anyway. :-)
VISUAL SELECTOR
The visual selector works in a similar manner to the
`Visual Schnauzer' provided in xv. In fact, it operates
by using the same format "thumbnail" files in the same
subdirectory, .xvpics. This means that indexes of thumb-
nail files created by zgv can be used by xv, and vice
versa. But if you don't use xv, or use it but not its
visual schnauzer, then you will of course need to `update'
the picture index from zgv. As in xv, this is a fairly
time-consuming process the first time around, but saves
zgv from having to repeat the calculations every time it
wants to show you roughly what the file looks like. After
the first `update', further updates only need to index
those pictures which have changed or are new.
In general, you need to re-index the current directory (by
pressing `u') whenever any filenames (other than directo-
ries) appear with not a picture below them, but a `docu-
ment' symbol - a rectangle with one corner `folded over'.
Directories are always shown with a `folder' symbol
(unless you use subdir indexing - more on this below).
While the index is being generated, the message "Updating
index of ..." replaces the usual "Directory of ...". The
Esc key can be used to abort the update process; zgv may
take a while to respond, however, as it finishes creating
the current thumbnail image first.
If you switch virtual consoles while zgv is updating the
thumbnails, it will keep updating them `in the back-
ground'. When you switch back, if the update is still in
progress, it may look as though zgv is doing nothing (or
the screen may look a bit confusing) for some time. The
reason is that the screen is not updated unless zgv is
running on the currently displayed console (this is unfor-
tunately necessary). The screen is redrawn when the thumb-
nail currently being dealt with has been finished.
As well as the thumbnails for normal files, you can also
create thumbnails for subdirectories by pressing `d'.
These are made up of the first four files in the directory
squeezed into a single thumbnail, in the hope that these
will be representative of the directory as a whole. The
subdir thumbnails are all created each time, unlike the
incremental way the ordinary thumbnails are cre-
ated/updated. (This is necessary since one or more of the
four files may have been deleted, moved etc. since the
last time you created a thumbnail based on them, and such
a change would be difficult to detect reliably.)
Unlike the ordinary thumbnails, which are almost undoubt-
edly useful and something you'd want, it's by no means
certain that subdir thumbnails are a Good Thing. It can
make it a lot less clear which entries are directories, if
nothing else. But give it a try and see what you think. If
you don't like it, just delete all the files in .xvpics
which have no `extension' and everything'll be as before.
The visual selector normally operates in 640x480x256 mode;
if this mode is not available, 640x480x16 mode will be
used instead, but using this mode means that display will
be slower. It also means that you must choose between
either low-quality eight-colour thumbnail pictures, or
higher quality eleven-greyscale monochrome thumbnails.
Zgv defaults to using monochrome. If you'd prefer to have
colour, put the line `fs16col on' in your ~/.zgvrc file.
You can switch between monochrome and colour while running
zgv by pressing `c'.
You can switch between the visual selector and the file-
names-only selector by pressing `v' while on the file
selection screen. The filenames-only selector has two main
advantages - it shows many more files onscreen at once,
and it doesn't need lots of disk space for thumbnail
files, which range from around 1K to 5K each.
The thumbnail images are dithered to a 3:3:2 palette - 3
bits red, 3 bits green, and 2 bits blue. This results in
only four greyscales, but for the average colour image,
it's a reasonable spread (the eye is more sensitive to
green - and red - than to blue). Since this uses up all
256 colours available, providing the file selector with
the colours used for drawing the cursor, the text, etc. is
awkward. The manner in which this is dealt with by default
is to select the colours in the 3:3:2 palette `closest' to
the colours required, and then to change them to the file
selector colours. In my experience, this results in a min-
imal disturbance to the thumbnail images. However, the
option perfectindex in either configuration file can be
used to stop zgv changing the colours. This will probably
result in the file selector looking a little (or a lot)
strange, but the thumbnail images should be restored to
normality. Anything you cannot cope with then is therefore
your own problem. :-)
When the visual selector is operating in 640x480x16 mode,
these 3:3:2 images are mapped to 11 greyscales. In this
mode, zgv always acts as though perfectindex was speci-
fied, as five palette entries are reserved for the colours
used by the selector.
If the directory .xvpics can't be created or written to -
such as when using an MS-DOS partition or floppy, or a CD-
ROM - zgv will use a different strategy for storing the
thumbnails. It creates the directory ~/.xvpics/_sam-
ple_path_name and stores the file there if possible. The
_sample_path_name is the original path (in this case /sam-
ple/path/name) with the slashes converted to underscores.
The fact that zgv is storing the thumbnails somewhere else
won't make any noticeable difference when using zgv.
(Except that the delete feature will not delete any thumb-
nails in or under ~/.xvpics/_*.)
Because of the way JPEGs are encoded (and the flexibility
of the IJG's JPEG software) they can be indexed quicker
than you might expect. The default method is a reasonable
mixture of speed and accuracy, but see the description of
jpegindexstyle in the CONFIGURATION section below for how
to change this.
SCROLLING, ZOOM MODE, AND VIDEO MODES
When you're viewing a picture, there are lots of curious
things you can do - some useful, some... less useful. This
section covers most of the useful ones.
If a picture is bigger than the screen, there are two dif-
ferent ways to view the rest of the picture. First you can
scroll around the image - using the cursor keys or `h',
`j', `k', `l' or `q', `a', `o', `p' - which means you can
only see part of it at once; or you can fit the image to
the screen, which loses resolution and tends to make the
image look either gritty or smudged (depending on whether
the `vkludge' option is being used - more about that
later).
Scrolling is probably the more useful of the two, and is
the default method used. The cursor keys move around the
image in 100-pixel steps, as do `H', `J', `K', `L' and
`Q', `A', `O', `P' (i.e. hold shift). Using `h', `j', `k',
`l' or `q', `a', `o', `p' unshifted moves around the image
in 10-pixel steps. The Home key moves to the top-left of
the image, and the End key moves to the bottom-right.
PgUp and PgDn move up and down in pages, oddly enough.
`-' and `=' move left and right in pages, which really is
odd.
The method which fits the image to the screen, or `zoom'
mode as it is confusingly called, is toggled on or off by
pressing `z'. The scrolling keys will no longer have any
effect, because there's nowhere to scroll to (you can see
it all). You can toggle the `vkludge' mode on or off by
pressing `v'.
In zoom mode, having vkludge on causes zgv to average out
an appropriate area from the unzoomed image for each new
onscreen pixel, so what you see looks better, but takes
longer to draw. (The word `appropriate' is being used in a
rather dubious and optimistic sense here.)
When using either 320x400 or 360x480 mode, having vkludge
on means that zgv does a similar kind of averaging between
the two pixels which are being mapped to one onscreen
pixel. (Zgv does this 2-to-1 mapping normally with these
modes so that the modes are pseudo-640x400 and 720x480
modes, which should be more useful. Vkludge makes it look
better, but takes longer. To disable this mapping alto-
gether when in the mode, press `0' (zero).)
When not in zoom mode and not in a `virtual' mode, vkludge
has no effect.
8-BIT AND 24-BIT MODES
Zgv allows for the varying types of video modes available
from modern SVGA cards by using two different internal
modes. This controls only how the image is stored in mem-
ory, but can affect how it appears on the screen.
GIF files contain up to 256 colours from a palette of 16.7
million, although in practice most GIF files follow the
VGA hardware's capabilities of 256 colours from a palette
of 262,144. Zgv always displays GIF files in 8-bit (256
colour) video modes.
JPEG files are either greyscale or 24-bit. Greyscale JPEGs
are always shown in 8-bit video modes. (See point 2 under
IMPLEMENTATION for a discussion of greyscale handling in
256 colour modes.) 24-bit JPEGs, which can have any
colour from a fixed 16.7 million colour spread can be
shown in 24-bit video modes, in 15 and 16-bit video modes
(the latter two being 32,768 and 65,536-colour modes
respectively), and dithered to 256 colours in an 8-bit
mode. Zgv (by default) uses a 15, 16 or 24-bit colour mode
to display JPEGs if possible.
PBM files are shown in 8-bit. PGM files are shown in 8-bit
unless `betterpgm' is set, in which case they are con-
verted to 24-bit internally and displayed in 15, 16 and
24-bit modes. PPM files are shown in the same way as
24-bit JPEGs.
Note that if a file is loaded as 8-bit internally (GIF,
PBM, usually PGM, sometimes JPEG and PPM) then it can only
be displayed in 8-bit video modes. If one is loaded as
24-bit internally (usually JPEG and PPM, sometimes PGM),
then it can only be displayed in 15, 16 or 24-bit video
modes. This is necessary because of the conversion over-
head in the 24 to 8-bit direction.
BMP, TGA, PCX and PNG files are treated in the same way as
PBM, PGM or PPM files depending on the colour depth.
(Apart from `betterpgm' being ignored, that is - that set-
ting only affects PGM files.) Mrf files are treated like
PBMs.
Since 15 and 16-bit video modes do not have quite the same
representation (and depth) that a file loaded as 24-bit
does, there are some drawbacks to using them. The image is
converted to the 2-byte-per-pixel format as it is drawn.
See point 3 in the IMPLEMENTATION section for the ratio-
nale behind this. Also, the modes actually have less
colour depth than 256 colour modes.
In explanation of that last point; although 15 and 16-bit
video modes show many colours onscreen at once, there are
fewer colours to choose from.
A good way to illustrate this point is by considering the
number of greyscales each mode can display. In a 256
colour video mode, only 64 greys can be shown, since
2^(log2(262144)/3)=64. But with a 15-bit video mode, even
less can be shown - 2^(log2(32768)/3)=32. Because of the
way that 16-bit video modes work, which is by providing
the green channel with twice as much colour depth (i.e. an
extra bit), they can also only show 32 greys. Put another
way, 2^int(log2(65536)/3)=32. (Of course, 24-bit mode will
show all 256.)
THE VIEWER'S 640x480 16-COLOUR MODE
When viewing pictures, zgv only truly supports 8-bit and
15/16/24-bit video modes. However, since there may still
be some people out there stuck with only a standard VGA
card (or perhaps an unsupported SVGA one), zgv includes a
special-case kind of support for the 640x480 16-colour
mode.
Before going any further, I should say that no-one with
access to a true 640x480x256 mode should bother with the
640x480x16 mode. Even the 320x400x256 and 360x480x256
modes (which should work on standard VGA) are probably
preferable, though there may be circumstances where these
are unavailable or don't work (laptops spring to mind as a
possibility).
Anyway, the way the 640x480x16 mode works is quite simple.
It acts in exactly the same way as the true 640x480x256
mode, except that the screen contents are modified just
before they're displayed. The 256-colour image is either
displayed as a greyscale (16 levels dithered to give the
appearance of 64) or dithered (in colour). Like the
16-colour file selector, the greyscale option is the
default. If you'd prefer colour, either put the line
`viewer16col on' in your ~/.zgvrc file, or press shift-c
(`C') while in the viewer (this toggles between the two
options).
The dithering used (in both cases) is unlike that used in
the rest of zgv - it's an ordered dither (using a fixed
pattern) rather than being error-diffused. Essentially,
this means it's a lot quicker but doesn't look as good.
SCALING
In addition to the `zoom' facility which resizes an image
to fit the screen, zgv can scale up the pixels in an image
to make it appear larger. The `s' key scales up (`zooms
in', if you like, but remember that this is not what zoom
mode does!), and the `S' key (that's shift + s) scales
down (`zooms out'). Note that this `zooming out' goes no
further than the normal 1:1 pixel ratio - if you want to
fit a large image to the screen, use zoom mode instead by
pressing `z'.
The way the scaling works is as follows: Normally the pix-
els in the image are displayed as one pixel in the image =
one pixel onscreen. All that happens when the scaling
keys are used is that this 1:1 ratio gets changed - for
example, if you press `s' then the ratio becomes 1:2, and
one pixel in the image shows as 2x2 pixels onscreen so
that it's double the size of the original. If you then
press it again, the ratio becomes 1:3 (note that pressing
`s' adds one to the second number, rather than doubling it
as is common), and one pixel in the image translates to
3x3 pixels onscreen. You can carry this on up to 1:512 if
you wish, where zgv stops so that pixels may be conserved
for future generations. :-)
If you want to change the ratio by doubling instead of
adding one, you can use `d' and its counterpart key `D'.
This causes ratios like 1:1, 1:2, 1:4, 1:8, 1:16, etc.
When an image is scaled up, you should be aware that the
movement keys such as the cursor keys operate on the
scaled-up image, rather than the image which has been
scaled up; even to the extent of moving fractions of an
unscaled pixel if appropriate. As such, zgv operates
exactly as if you had actually loaded the scaled-up
image... except that everything happens rather slower.
You may find, while scaling back down again, that the
screen clears (before the image is redrawn) when the image
starts returning to normal size. This is perfectly normal,
as zgv is clearing the screen to make sure no junk remains
from what was previously there. Since this is only neces-
sary when the image as shown is smaller than the screen,
zgv only does it then.
Unfortunately, there are a couple of problems with the
scaling functions. Firstly, they cannot be used in 320x400
and 360x480 modes (they'll have no effect). If you want to
use scaling in that mode, one workaround - admittedly
rather clumsy - is to switch to 320x240 or 320x200 mode
(press `6' for the former or `5' for the latter), treat
that as the 1:2 scaling up, and carry on from there.
Secondly, if you are `zoomed in' and flip or mirror the
picture, then you will (effectively) end up looking at a
completely different part of the picture. This is the case
normally, but isn't usually quite as noticeable.
Note that by default zgv will reset the scaling to 1:1
whenever a new picture is viewed. To stop this, and have
the scaling persist `between pictures', insert `revert
off' in your configuration file (see CONFIGURATION below).
SCALING WITH INTERPOLATION
This is more a sign of my thinking, "hey that'd be a cool
feature to add" than anything else. In scaling mode, there
is an additional feature which `smoothes out' the screen
pixels which lie in-between image pixels. This is horribly
slow, much more so than scaling mode alone; in addition,
it only works in a 15, 16 or 24-bit screen mode, which
means it will only work for 24-bit files and only if you
have a card which supports one or more high-colour modes.
The `i' key toggles the interpolation on and off. If you
do intend to use it, you should probably use normal scal-
ing mode and the panning controls to move to some part of
the image, and then turn interpolation on.
At the ratio 1:2 (and, at a stretch, 1:3) it's often good
with JPEGs to use the `1' key to toggle next-pixel-bar-one
interpolation, which ends up not really interpolating
properly; however, it does smooth out some of the blotchi-
ness there is in scaled-up JPEGs. If you use the toggle on
a highly scaled image, you should be able to see how inac-
curate the interpolation becomes.
CONSOLES
If not run from a console tty, zgv will attempt to run on
the first available console - if there are none free, it
will exit with an error message. When it has to switch
consoles like this, exiting zgv will cause an automatic
return to whichever console was current when the program
was started. This means you can run zgv reasonably trans-
parently from X, Emacs, etc.
Since zgv fork()s when doing this, it's rather like using
`open -s zgv', except that stdout isn't redirected. In
particular, `zgv -h' and other things which give output on
stdout will give confusing results, as the original zgv
process will have exited before the new zgv process exits.
Redirect stdout if you want things to make a bit more
sense - for example, `zgv -h | less' will give the
expected results. For more `normal' uses where zgv
doesn't give any output, there's no problem.
However, there's a problem running zgv from X, when it's
invoked from, say, a twm or fvwm menu. (It works ok from
an xterm.) The problem is that the window manager runs the
program with its stderr attached to the tty that the X
server was started from. Since zgv tests stderr to see if
it's a console, which in this case it probably will be,
everything gets very confused.
As luck would have it, there's an easy workaround; when
invoking zgv from the menu, just redirect the stderr to a
non-console, such as /dev/null. For example, here's an
extract from my system.fvwmrc:
Popup "graphics"
Exec "Gimp " exec gimp &
Exec "XV " exec xv &
Exec "Zgv " exec zgv 2>/dev/null &
Exec "XPaint " exec xpaint &
Exec "Bitmap " exec bitmap &
EndPopup
It seems a bit odd running zgv from X, but it can be use-
ful if you have a 15/16/24-bit card and normally run X in
monochrome or 8-bit colour.
Running zgv from an xterm with a filename as an argument
is generally how you'd do this, though - e.g. "zgv wib-
ble.jpg". Zgv then runs on a free VT and switches back
when you exit, so it's fairly hassle-free. If you want to
switch back to X before exiting zgv, it's just a matter of
switching VTs, as usual. X will be running on what was the
first free VT when it started; often this is number 7.
Apparently, there can be problems starting zgv from an X
session if xdm was used to login. As far as I know, xdm
tries to change the ownership of /dev/console to the per-
son it is logging in. This isn't such a great idea - you
should get it to `chown' the console that the X session is
running on, which is likely to be console 7. (This has
almost certainly been fixed since I wrote this. I don't
use xdm and I'm not interested in it, so I don't know.)
CONFIGURATION
Some of the ways in which zgv works, and the settings it
uses, can be altered using either the file $HOME/.zgvrc or
/etc/zgv.conf. The latter is intended as a system zgv
defaults file. You should use the former (which overrides
/etc/zgv.conf) if more than one person is going to use zgv
on the console.
The config file is arranged so that each line is blank, or
a comment, or consists of one assignment. (If you're
starting to feel ill, look at the sample.zgvrc file sup-
plied with zgv, and work it out from there.) Comment
lines begin with the hash (`#') character. Blank lines are
ignored. Assignment lines give a new value to an
attribute of zgv's operation - the attribute names are
listed below. Comments can also be put on assignment
lines; anything after a `#' is ignored.
Attributes are defined by a line like this;
<attrib_name> <value1> [value2 ... ]
`Boolean' values are either "on" or "off" ("yes"/"no" are
also allowed), integers are small integral numbers (where
small is defined as "between -2^31 and 2^31-1 inclusive" -
gotta love Unix :-) ), and `float's are floating-point
(i.e. real) numbers.
The attributes which can be set are:
visual whether to use the visual selector or not - boolean
perfectindex
if set then don't change any colours when using the
visual selector (see the VISUAL SELECTOR section
above) - boolean
zoom sets zoom mode - boolean
centre or center
whether to centre the pictures or not - boolean
blockcursor
use a more visible `block' cursor - boolean
thicktext
make the file screen text a bit thicker (this only
takes effect if blockcursor is on as well) -
boolean
nodelprompt
inhibits the "Really delete <filename>?" prompt
when deleting a file from the file selector if set
- boolean
cleartext
specifies whether or not to clear the text screen
upon startup and on exit - boolean
onefile_progress
has the same effect as the -p option (see OPTIONS
above) - boolean. Defaults to `on'.
hicolmodes
zgv has a short test routine which tries to deter-
mine whether your video card has high-colour modes
(15, 16 or 24-bit), so it knows whether it's possi-
ble to use them or not. If your card has a 640x480
high-colour mode but no 320x200 high-colour mode,
this test will fail - this is a bug, not a feature.
:-( This (boolean) option is provided so that if
you have one of these cards, you can at least force
zgv to work with it by inserting "hicolmodes on" in
one of the rc files.
force16fs
if set, forces the program to use 16-colour mode
for the file selector. You should do this if,
although your video card is capable of 640x480 in
256 colours, the screen is somehow garbled or unus-
able.
fs16col
if set, zgv uses low-quality colour thumbnail pic-
tures when the file selector is using 640x480x16
mode (i.e. on vanilla VGA cards). If turned off
(default), zgv uses monochrome thumbnails in
16-colour mode.
fullsel
if set, it uses the full screen for the file
selector, removing the stupid logo. :-) By default,
off.
forgetoldpos
if set, zgv uses the old (pre-v3.0) behaviour of
not returning the cursor to its previous position
when revisiting a directory. By default, off. It's
difficult to see why you'd want to enable this
option, but I put it in in case anyone really hates
the newer behaviour for some reason. :-)
linetext
use the original line-based text in the file selec-
tor etc. Defaults to off. You may want to enable
this if you're using the file selector in 16-colour
mode, as the bitmap fonts are perceptibly slower
than the line-based font in that mode.
viewer16col
if set, zgv gives a dithered colour image in
640x480x16 mode (when in the viewer). If turned off
(default), zgv gives a greyscale image when in that
mode.
revert is on by default, and if set zgv resets the scaling
ratio to 1:1 each time a new picture is viewed. It
also turns off scaling interpolation, if that is
set.
jpeg24bit
sets whether to try and use a 15, 16 or 24-bit dis-
play mode for JPEGs and other 24-bit files. On =
try, off = don't try. If `jpeg24bit on' is used on
a card where only 256 colour modes are available,
zgv will act as though `jpeg24bit off' was used.
jpegindexstyle
sets how to read JPEGs when generating thumbnails.
Choices are: `1', the quickest (but this sometimes
generates rather fuzzy/blocky thumbnails); `2', the
default; `3', the old slow method used in zgv ver-
sion 2.7 and earlier.
vkludge
sets vkludge mode - boolean; this smoothes the two
image-pixel wide pixels in 320x400 and 360x480
modes, and also - when in zoom mode - smoothes
images larger than the screen size to reduce the
unsightly `ripples' that the resizing down to fit
the screen usually causes. By default, off.
mouse enables mouse support and specifies the type of
mouse you're using. The mouse type should be spec-
ified after mouse, as with the -M command-line
option, as described in OPTIONS.
showxvpicdir
is off by default, but if set, shows any `.xvpics'
directories so that index files can be viewed even
if the files they referred to no longer exist.
(However, it's usually easier to simply start zgv
in the `.xvpics' dir.)
black sets RGB value of `black' on file selection screen
- takes three integers in the range 0-63 for RGB
value
dark sets RGB value of `dark grey' - see above
medium sets RGB value of `medium grey' - see above
light sets RGB value of `light grey' - see above
tagged sets RGB value of `tagged file' colour - see above
tagtimeout
sets time between pictures in `slide show' in sec-
onds (integer). The default value is 4 seconds.
contrast
sets contrast value. Zgv implements contrast by
multiplying the colour value by this number, and so
the value is a float.
brightness
sets brightness, which zgv implements by adding
this number to the colour value. (Brightness, con-
trast, etc. have no effect in 24-bit mode, as they
would be wildly slow and very memory hungry.
Believe me, using the monitor controls is much less
painful.)
gamma sets whether to fake more greyscale and colour
depth in 8-bit video modes. By default, on. (See
point 2 in the next section for more on this, and
see the BUGS section for why I called it gamma when
it's nothing of the sort.)
allmodesbad
(no parameter) stops zgv from allowing any modes.
This is usually followed by some `goodmode' assign-
ments. If it isn't, then zgv simply assumes that
the 320x200x256 mode can be used.
allmodesgood
(no parameter) the default - all modes can be used,
if your video card has them.
badmode
marks a mode as `bad', so it can't be used. Takes
three integers, and is used like this: "badmode
width height bpp" where bpp = number of bits per
pixel, 8 in 256 colour modes, 15 in 32768 colour
modes, etc.
goodmode
similar to "badmode", but marks the mode as `good'
i.e. usable.
startmode
defines the video mode zgv should start off using
when viewing pictures. This is normally set to the
equivalent of "startmode 640 480 8" if possible,
"startmode 360 480 8" if not, and "startmode 320
200 8" as a last resort. Takes three integers in
the same way as "badmode" and "goodmode". Zgv will
automatically switch to the 15, 16 or 24-bit mode
nearest to the resolution of the 8-bit mode cur-
rently being used if `jpeg24bit on' is being used,
and vice versa (sort of).
IMPLEMENTATION
This section covers some aspects of the implementation of
zgv which the author thinks may be of interest in some
situations. Feel free to skip this section, as I'll
indulge in any long-winded, boring discussion I want. ;-)
1. Whenever zgv reads a file, it needs to allocate memory
to read or decompress the file into. The size of the mem-
ory required varies from file to file, so it must be allo-
cated at the time it is needed (i.e. dynamically). This
is all very well so far, but there is a bit of a problem.
Say you start zgv, then view a 1 megabyte file. (This
isn't too unlikely - 1024x768 is getting close.) The size
of zgv's total memory allocation, i.e. the total memory
used by the zgv process, is increased by 1 Mb via malloc()
to store the image. Although this allocated memory is
free()'d when you quit viewing the image the memory is not
returned to Linux. It is recycled by future allocations
in the zgv process, however, which is some consolation.
Note that this behaviour is the case for all programs that
use dynamic allocation via malloc() - it's just that zgv
has to use such potentially large blocks of memory, even
if only for a short time, that this is more noticeable
than is usual.
So what are the problems with this? Since Linux has vir-
tual memory, there aren't many; any unused data will be
swapped out to disk when it gets in the way. My advice is
to make sure you've got at least eight, and preferably
twelve or more, megs of total memory - i.e. real RAM plus
swap space.
2. When using 8-bit video modes, zgv uses some trickery to
try and increase the apparent colour depth a little. The
VGA's 256 colour hardware only has 18-bit palette resolu-
tion (where 24-bit would be `perfect'), which means, among
other things, that only 64 greyscales can be shown.
The trick zgv uses is to increase one or two of the
red/green/blue channels by one, giving a coloured `pseudo-
grey'. Since the eye is more sensitive to brightness than
colour, this is reasonably convincing under normal condi-
tions.
A slightly more unusual use of this technique in zgv,
though, is that it carries on using it for colour 8-bit
images. I'm not certain how valid this is; the `sub-depth'
value is calculated as a greyscale, and the channels
altered are the same, with no consideration given to how
this might affect the colour balance.
However, the difference this feature makes is very slight.
The image will probably be very, very slightly brighter
than it would be otherwise, and possibly a little `warmer'
because of the minor use of colour and the eye's green/red
bias (I think).
If you want to disable this pseudo-grey feature, put
`gamma off' in your config file. You can use `g' while
viewing an 8-bit image to toggle it, to see what differ-
ence it makes.
3. In zgv, images are stored internally as either 8-bit or
24-bit images. These can trivially be drawn in 8-bit and
24-bit video modes, of course. But in 15/16-bit modes, the
24-bit image has to be converted to the 15/16-bit format
to be drawn.
A couple of people have asked me why this should be the
case. Why couldn't I have the image stored in the
15/16-bit format if it's to be viewed in that mode? My
answer is that it's an artificial restriction, and it
wouldn't buy much. The difference between 8-bit and 24-bit
formats isn't so much the number of bits; it's more that
one is palette-based while the other isn't. This means
that while conversion from 24-bit to 8-bit is slow enough
for a separate 8-bit mode to be sensible, conversion from
24-bit to 15/16-bit can be done sufficiently quickly that
the picture in 15/16-bit modes draws at about the same
speed as it does in the equivalent 24-bit mode. I think
this is acceptable.
FILES
$HOME/.zgvrc - this is where zgv first looks for a config
file. If it can't read the file, or it doesn't exist, it
tries...
/etc/zgv.conf - which is intended to be the system's
default zgv config file. If this can't be read, the built-
in defaults are used. (Actually, this isn't quite true -
it also checks for /etc/system.zgvrc before giving up, but
/etc/zgv.conf should really be used instead.)
.xvpics - this is the subdirectory under which all picture
file thumbnails are stored (usually).
/dev/mouse - this is the mouse device used if the -M
option is given on invocation.
BUGS
This huge list makes zgv look chock-full of bugs. It's not
as bad as this implies... honest... :-)
24-bit PCX files are not supported yet. Sorry. If you can,
use PNG instead, it compresses much, much better and is
still lossless. Failing that, try TGA, which can use sim-
ilar compression to PCX.
Corrupt JPEG or PNG data warnings are not reported by zgv.
If a GIF file is corrupted in such a way that the decom-
pressed image has a larger number of pixels in it, the
extra pixels will be ignored and no error or warning will
be generated.
In the 640x480x16 mode in the viewer, when scaling a pic-
ture where the scaled picture remains narrower than the
screen's width, the background to the left and right of
the picture is filled in with the picture's background
colour (though you'll only be able to see this if the pic-
ture's background colour isn't black). This is harmless
but looks strange.
When toggling the `full-screen' option for the file selec-
tor, the first file listed onscreen remains the same,
which can sometimes look odd (but is otherwise harmless).
The name of the `gamma' config file option is a complete
misnomer. It got the name from fractint's `gamma' palette
maps which use a similar technique. I couldn't think of a
better name for it, so it stuck.
The help pages only list a few of the keys.
32-bit video modes are not supported.
The "Directory of..." text appears smaller when using
bitmap fonts - about the same size as the filename text,
usually. However, this is arguably a misbug, because at
the `correct' size the text was more than one pixel thick,
which made it (IMHO) too distracting.
If you look up `joe code' in a dictionary, it says "see
zgv". :-)
RESTRICTIONS
Zgv does not support any of the extensions in the GIF89a
specification, but does read the files - it just skips the
extension blocks. Multiple image GIFs are not supported.
The combination JPEG/GIF format which can optionally be
produced by Handmade Software's GIF2JPG is not supported.
ACKNOWLEDGEMENTS
Thanks to Tommy Frandsen, Harm Hanemaayer and many others
for VGAlib and svgalib.
This program is based in part on the work of the Indepen-
dent JPEG Group.
"The Graphics Interchange Format(c) is the Copyright prop-
erty of CompuServe Incorporated. GIF(sm) is a Service Mark
property of CompuServe Incorporated."
Thanks also to the many zgv users who've contributed sug-
gestions, ideas for features, and even... dare I say...
compliments. :-) Zgv would simply not be as good without
their input.
AUTHOR
Russell Marks.
Mouse support and a few other features by Edwin Fong
hffong@cs.cuhk.hk.
The mouse driving code is taken from selection, which was
written by Andrew Haylett ajh@primag.co.uk.
BMP support by Carsten Engelmann (cengelm@yacc.cen-
tral.de).
Fast JPEG thumbnails by Costa Sapuntzakis (csa-
puntz@mit.edu).
SEE ALSO
xv(1) twm(1) fvwm(1x) xterm(1) XFree86(1) xdm(1)
cjpeg(1) djpeg(1) pbm(5) pgm(5) ppm(5) mrf(5)