Zgv displays which picture files are in the current directory, 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 directory 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).
All options are processed after any $HOME/.zgvrc or /etc/zgv.conf file.
The cursor keys can 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 `U' 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. `r' updates picture index for image files in the current directory and recursively, in all subdirectories. `R' does the same for directory pictures.
The keys used by zgv when viewing an image are as follows:
The following modes are available only on SVGA cards supported by svgalib, and then only if your card has such a mode. However, you should try these first, as they're preferable if available.
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.
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 previous 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. :-)
In general, you need to re-index the current directory (by pressing `u') whenever any filenames (other than directories) appear with not a picture below them, but a `document' 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 background'. 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 unfortunately necessary). The screen is redrawn when the thumbnail 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 created/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 undoubtedly 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 filenames-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 minimal 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 specified, 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/_sample_path_name and stores the file there if possible. The _sample_path_name is the original path (in this case /sample/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 thumbnails 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.
If a picture is bigger than the screen, there are two different 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 altogether when in the mode, press `0' (zero).)
When not in zoom mode and not in a `virtual' mode, vkludge has no effect.
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 converted 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 overhead 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 setting 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 rationale 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.)
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.
The way the scaling works is as follows: Normally the pixels 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 necessary 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).
The `i' key toggles the interpolation on and off. If you do intend to use it, you should probably use normal scaling 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 blotchiness there is in scaled-up JPEGs. If you use the toggle on a highly scaled image, you should be able to see how inaccurate the interpolation becomes.
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 x
v &
Exec "Zgv " exec zgv 2&
gt;/dev/null &
Exec "XPaint " exec xpaint &
Exec "Bitmap " exec bitmap &
EndPopup
It seems a bit odd running zgv from X, but it can be useful 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 wibble.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 person 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.)
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 supplied 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:
1. Whenever zgv reads a file, it needs to allocate memory to read or decompress the file into. The size of the memory required varies from file to file, so it must be allocated 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 virtual 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 resolution (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 conditions.
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 difference 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.
/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.
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 similar 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 decompressed 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 picture 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 picture's background colour isn't black). This is harmless but looks strange.
When toggling the `full-screen' option for the file selector, 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.
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". :-)
This program is based in part on the work of the Independent JPEG Group.
"The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated."
Thanks also to the many zgv users who've contributed suggestions, ideas for features, and even... dare I say... compliments. :-) Zgv would simply not be as good without their input.
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.central.de).
Fast JPEG thumbnails by Costa Sapuntzakis (csapuntz@mit.edu).