The Control Window


The xv controls window is the central point of control for the program, which just goes to show how appropriately it was named. It contains controls to resize the current image, flip and rotate it, load and save different files, and bring up the other xv windows. It can be brought up by clicking the Right mouse button in the image window, or by pressing the ? key inside any open xv window. Doing either of these things while the xv controls window is visible will hide it.

All of the following commands may be executed by either clicking the appropriate command button, or typing the keyboard equivalent (where given) into any open xv window.

Resizing Commands

The resizing commands have all been moved to the Image Size menu. Note that none of the 'resizing' commands modify the image in any way. They only affect how the image is displayed. The image remains at its original size. This allows you to arbitrarily stretch and compact the image without compounding error caused by earlier resizing. In each case, the displayed image is recomputed from the original internal image.


Note: The keyboard equivalents for each command are listed on the right side of the menu. These commands may be entered in the xv image window, the xv controls window, the xv info window, and the xv color editor window. They may not be entered in the xv visual schnauzer windows, the xv load window, or the xv save window. The same goes for all other commands listed in the xv controls window.

Attempts to return the image to its normal size, where one image pixel maps to one screen pixel. For example, if the image (or the current cropped portion of the image) has a size of 320x200, this command will attempt to make the image window 320 screen pixels wide by 200 screen pixels high.

This command may fail in two cases. If you're running a window manager (such as mwm) that enforces a minimum window size, and the 'normal' size is too small, the image may get distorted. See the note in "Cropping" for more information.

Also, if the image is larger than the size of your screen, it will be shrunk (preserving the aspect ratio) until it fits on the screen. For example, if you try to display a 1400x900 image on a 1280x1024 screen, the Normal command will display a 1280x823 image. (1400/900 = 1280/823)

This command will make the displayed image the same size as the screen. If you are running a window manager that puts up a title bar, you'll find that the title bar is now off the top of the screen. To get the title bar back, simply shrink the image to anything smaller than the size of the screen. The window will be moved so that the title bar is once again visible.
Makes the image as large as possible, while preserving the aspect ratio. This avoids the generally unwanted image distortion that Max Size is capable of generating. For example, if you have a 320x200 image, and an 1280x1024 screen, doing the Maxpect command will result in an image that is 1280x800. Max Size , on the other hand, would've generated an image of size 1280x1024, which would be appear 'stretched' vertically.
Doubles the current size of the image, with the constraint that neither axis is allowed to be larger than the screen. For example, given a 320x200 image and a 1280x1024 screen, the image can be doubled once (to 640x400), a second time (to 1280x800), but a third time would make the image 1280x1024. You'll note that on the third time, the width didn't change at all, since it was already at its maximum value. Also note that the height wasn't allowed to double (from 800 to 1600), but was truncated at its maximum value (1024).
Halves the current size of the image, with the constraint that neither axis is allowed to have a size less than 1 pixel. Also, you may run into 'minimum size' problems with your window manager. See the note in "Cropping" for more information.

Note that the window size is maintained as a pair of integers. As a result you may see some integer round-off problems. For example, if you halve a 265x185 image, you'll get a 132x92 image, which is just fine. However, if you Double Size this image, you'll get a 264x184 image, not the 265x185 image that you started with.

Increases the current size of the image by 10%, subject to the constraint that the image cannot be made larger than the screen size (in either axis). For example, issuing this command on a 320x200 image will result in a 352x220 image.
Decreases the current size of the image by 10%. Neither axis of the image is allowed to shrink below 1 pixel. Also, you run the risk of running into 'minimum window size' problems with your window manager.

It should be noted that the 10% Larger and 10% Smaller commands have no concept of an 'original size'. They simply increase or decrease the current image size by 10%. As a result, they do not undo each other. For example, take a 320x200 image. Do a 10% Larger and the image will be 352x220. If you issue the 10% Smaller command now, the image will be made (352 - 35.2)x(220 - 22), or 316x198.

Lets you specify the exact size, or exact expansion, to display the image. Pops open a dialog box where you can type a string of the form " width x height", " expansion%", or " horiz-expansion% x vert-expansion%". The spaces between numbers aren't necessary, but the 'x' and '%' characters are.
Applies the 'default aspect ratio' to the image. This is done automatically when the image is first loaded. Normally, the default aspect ratio is '1:1', but certain GIF files may have an aspect ratio encoded in them. You can also set the default aspect ratio via a command-line argument or an X resource. See "Image Sizing Options" for more info. The idea behind this command is that you'd stretch the image manually (via your window manager) to roughly the size you'd like, and then use the Aspect command to fix up the proportions.

Normally Aspect expands one axis of the image to correct the aspect ratio. If this would result in an image that is larger than the screen, the Aspect command will instead shrink one of the axes to correct the aspect ratio.

Attempts to resize the image so that the ratio of width to height is equal to 4 to 3. (e.g., 320x240, 400x300, etc.) This is useful because many images were meant to fill the screen on whatever system they were generated, and nearly all video tubes have an aspect ratio of 4:3. This command will stretch the image so that things will probably look right on your X display (nearly all of which, thankfully, have square pixels). This command is particularly useful for images which have really bizarre sizes (such as the 600x200 images presumably meant for CGA, and the 640x350 16-color EGA images).
Resizes the image to the nearest integral expansion or compression ratio. For example, if an image is currently being displayed at "162.43% x 231%", the IntExpnd command will show the image at a "200% x 200%" expansion ratio. Likewise, if an image is being shown at a "37% x 70%" expansion ratio, IntExpnd will resize it to "33% x 50%", the nearest integer compression ratios.
An alternate way of issuing the 10% Larger command.
An alternate way of issuing the 10% Smaller command.

Rotate/Flip Commands
Rotates the entire image (not the selection) 90 clockwise.
Keyboard equivalent: t

Rotates the entire image (not the selection) 90 counter-clockwise.
Keyboard Equivalent: T
Flips the image (or the selected area of the image) horizontally (around the vertical center-line of the image).
Keyboard Equivalent: h
Flips the image (or the selected area of the image) vertically (around the horizontal center-line of the image).
Keyboard Equivalent: v

The Display Menu

This menu controls how the image is displayed on your screen. None of these commands actually modifies the image itself, only how it is presented.

Dithering Commands

Returns the displayed image to its 'raw' state (where each pixel in the displayed image is as close as possible to the corresponding pixel in the internal image). In short, it turns off any dithering or smoothing. This command is normally disabled, and is only enabled after you have issued a Dithered or Smooth command..

Regenerates the displayed image by dithering with the available colors in an attempt to approximate the original image. This has a useful effect only if the color allocation code failed to get all the colors it wanted. If it did get all the desired colors, the Dither command will just generate the same display image as the Raw command. On the other hand, if you didn't get all the desired colors, the Dither command will try to approximate the missing colors by dithering with the colors that were obtained, which can help eliminate visible banding, and such. Note: If you are running xv on a 1-bit display the Dither command will be disabled, as the image will always be dithered for display.
Smoothes out distortion caused by integer round-off when an image is expanded or shrunk. This is generally a desirable effect, however it can be fairly time-consuming on large images, so by default it is not done automatically. See "Modifying xv Behavior" for more details. Note that Smooth only has a useful effect if the image has been resized. If the image is being displayed at its normal 1:1 expansion ratio, then the Smooth command will not have a useful effect.

Note: if you are currently in '24-bit mode' (see "The 24/8 Bit Menu" for more info), the Dithered command is disabled, Raw displays the image (dithered on an 8-bit display), and Smooth displays a smoothed version of the image (dithered on an 8-bit display).

Color Allocation Commands
When turned on, forces xv to use read/write color cells (ignored and disabled in Use Std. Colormap mode, below).. Normally, xv allocates read-only color cells, which allows it to share colors with other programs. If you use read/write color cells, no other program can use the colormap entries that xv is using, and vice-versa. The major advantage is that using read/write color cells allows the Apply function in the xv color editor window to operate much faster, and allows the Auto-Apply while dragging feature to be used at all. Also note that this command is only enabled if you are running xv on a PseudoColor display. See "Color Allocation in xv" for more information on display modes.
xv's normal color allocation mode. For any given picture, xv figures out what colors should be allocated, and tries to allocate them (read-only, or read/write, as determined by the Read/Write Colors setting). If any color allocation fails, xv will try a few other tricks, and generally just map the remaining colors (the ones it didn't get) into the closest colors that it did get.
When Perfect Colors is turned on, xv proceeds as in the Normal Colors case. If any color allocation request fails, all colors are freed, and xv creates itself a private colormap, and tries all over again. It is assumed that having a private colormap will provide more colors than allocating out of the already partially-used system default colormap.
Like Perfect Colors , but it doesn't even try to allocate out of the system colormap. Instead, it starts off by creating its own colormap, and allocating from there. Slightly faster than Perfect Colors mode. Also useful, as certain X servers (AIX 3.1 running on an RS6000, for instance) never report an allocation error for read-only color cells. They just return the closest color found in the system colormap. Generally nice behavior, but it prevents Perfect Colors mode from ever allocating a colormap...
An entirely different color allocation mode. Instead of picking the (generally unique) colors that each image requires, this mode forces all images to be displayed (dithered) using the same set of (standard) colors. The downside is that the images don't look as nice as they do in the other modes. The upside is that you can display many images simultaneously (by running more than one copy of xv) without instantly running out of colors. The setting of Read/Write Colors is ignored while in this mode. Also, this mode is the only one available when you are displaying images in 24-bit mode.

Root Display Modes

While xv normally displays an image in its own window, it is also possible for it to display images on the root window (a.k.a. 'the desktop'). You would normally use this feature from the command- line, as part of some sort of X startup script, to put up a background pattern or image of your choice. See "Root Window Options" for further information on the relevant command-line options.

You can also specify root display options interactively, while the program is running, by using the Root menu, as shown.

One note regarding root display: it is not possible for xv to receive button presses or keyboard presses in the root window. As such, there are several functions that cannot be used while in a 'root' mode, such as pixel tracking, image editing, pan and zoom operations, etc. If you want to do such things, you'll have to temporarily return to 'window' mode, and return to 'root' mode when you're finished. Also, when you are in a 'root' mode, you will not be able to get rid of the xv controls window. At best you can iconify it (using your window manager). There's a good reason for this. If you could get rid of the window, there would be no way to ever get it back (since it won't see keypresses or mouse clicks in the root window).

One other note: If you are running xv on certain 24-bit displays, where the 'default' visual type is an 8-bit PseudoColor, but xv in its cleverness has decided to use a 24-bit TrueColor mode, you will not be able to switch the display to a root mode. This is because xv requires the visual used in the 'window' mode to be the same as the visual used for the 'root' modes. In the case of these types of displays, it is not possible to put a 24-bit TrueColor image on the root window. You can get this to work by using the ' -visual default ' command-line option, which will force xv to use the 'default' visual for both the 'window' and 'root' modes.

Also note: This is only necessary to get this menu to work on such displays. If you use the ' -root ' or ' -rmode ' command-line options, xv will automatically use patented "DoTheRightThing" technology...

Displays the image in a window. If you were previously in a 'root' mode, the root window will also be cleared.
The image is displayed in the root window. One image is displayed aligned with the top-left corner of the screen. The image is then duplicated towards the bottom and right edges of the screen, as many times as necessary to fill the screen.
Similar to Root: Tiled , except that the image is first shrunk so that its width and height are integer divisors of the screen's width and height. This keeps the images along the bottom and right edges of the screen from being 'chopped-off'.

Note: using any of the 'resizing' commands (such as Normal , Double Size , etc.) will lose the 'integer'- ness of the image, and you'll have to re-select this mode to 'integer-ify' the image again.

Tiles the original image with versions that have been horizontally flipped, vertically flipped, and both horizontally and vertically flipped. This gets rid of the sharp dividing lines where tiled images meet. The effect is quite interesting.
Like Root: Mirrored , but also does the integer-ization described under the Root: Integer Tiled entry.
Like Root: Tiled , but it positions the images so that one of them is centered on the screen, and the rest are tiled off in all directions. Visually pleasing without the image size distortion associated with Root: Integer Tiled .
Displays a single image centered in the root window, surrounded by black, or your choice of any other solid color. (See "Modifying xv Behavior " for more information.)
Displays a single image centered in the root window, surrounded by a black and white 'warp' pattern, which produces some mildly visually pleasing Moir effects. The colors can also be chosen by the user. (See "Modifying xv Behavior" for details.)
Displays a single image centered in the root window, surrounded by a black and white 'brick' pattern. Again, the colors can be set by the user.
Tiles images on the root window such that the images are symmetric around the horizontal and vertical center lines of the screen.
Like the Root: symmetrical tiled mode, but the images are also mirrored.

Note: The three 'centered' modes ( Root: Centered , Root: Centered, Warp , and Root: Centered, Brick , but not Root: Center Tiled ) require the creation of a Pixmap the size of the screen. This can be a fairly large request for resources, and will fail on a color X terminal with insufficient memory. They can also require the transmission of considerably more data than the other 'root' modes. If you're on a brain- damaged X terminal hanging off a slow network, you should probably go somewhere else. Barring that, you should certainly avoid the 'centered' modes.

Also note: If you quit xv while displaying an image on the root window, the image will remain in the root window, and the colors used by the image will remain allocated. This is generally regarded as correct behavior. If you decide you want to get rid of the root image to free up resources, or simply because you're sick of seeing it, the quickest route is to run ' xv -clear ', which will clear the root window, release any allocated colors, and exit. Alternately, xsetroot or any other X program that puts things in the root window should be able to do the trick as well.

The 24/8 Bit Menu

xv has a whopping grand total of two internal image formats: 8-bit colormapped, and 24-bit RGB. Every image you load is converted to one of these two formats, as part of the image loading procedure, before you ever get to see the image.

There are a few crucial differences between these two modes. In 8-bit mode, you have a colormap, and thus color-editing changes (see "The Color Editor" ) can happen much more quickly. On the downside, most of the image editing functions only actually operate on 24-bit images. (Such as the Algorithms menu, described later in this section.) If you use these functions, xv will convert the 8-bit image into a 24-bit image, operate on the 24-bit data, and convert the result back to an 8-bit image. As a result, artifacts can be introduced from the image conversions. As such, if you're going to be doing a lot of this sort of thing, switch to 24-bit mode first.

But I digress...

This menu lets you see which mode xv is currently operating in, and lets you change modes. You can also force xv to remain in the current mode, and select how the program will convert 24-bit images into 8-bit images.

Forces the program into 8-bit mode when selected. If you are currently working on a 24-bit image, it will be converted into an 8-bit image using the selected conversion algorithm (see below), and the 24-bit data will be thrown away.
Forces the program into 24-bit mode when selected. If you currently working on an 8-bit image, it will be converted into a 24-bit image and the 8-bit image will be thrown away. Note that if you are working on a 24-bit image, switch to 8-bit mode , and switch back to 24-bit mode , your 24-bit data will have been lost in the conversions. A dialog box will pop up to alert you of this potential problem.
Normally, xv will switch between 8 and 24-bit modes based on the image type (if you load a 24-bit image, it'll switch to 24-bit mode , otherwise it will use 8- bit mode ). Turning this option on will force xv to remain in the current mode. One reason that you might wish to this would be to lock xv into 8-bit mode so that 24-bit images are shown dithered with the 'Slow' algorithm (see below), which produces better looking images on 8-bit displays. (Just don't try to save the image afterwards!)
Converts 24-bit images to 8-bit images by dithering with a fixed 6x6x6 RGB colormap. It is the quickest of the three algorithms, but also generally produces the worst images. It can also be selected via the '-quick24' command-line option or X resource.
The default algorithm. Takes about twice as long as the Fast algorithm. Uses the median-cut algorithm to pick a set of 256 colors, and then dithers with these colors. It can be selected via the '-slow24' command-line option or X resource.
By far and away the slowest of the algorithms. Can take up to ten times as long as the Slow algorithm. Uses a cleverer version of the median-cut algorithm to pick a better set of 256 colors than the slow algorithm. Does not dither. This might look best if you're going to be expanding the image by very much, as the dithering in the other two algorithms becomes very noticeable. You can also select this option via the '-best24' command-line option or X resource.

Note that none of the three 24->8 algorithm choices immediately does anything. They merely select which algorithm will be used the next time xv feels a need to convert a 24-bit image into an 8-bit image.

Image Algorithms

xv now has the ability to run a number of standard image-processing algorithms on the current image, or any rectangular portion of the current image. If there is a current selection rectangle (See "Selection Rectangle" ), the algorithm will only affect the selected area. Otherwise, the algorithms operate on the entire image.

Algorithms are chosen via the Algorithms menu, and are executed immediately. Algorithms are cumulative, in that if you run an algorithm on an image, and then run a second algorithm, the second algorithm operates on the modified image produced by the first algorithm. And so on.

See "Adding Algorithms to xv" for information on how you can add additional algorithms to this menu.

Also, it should be noted that the algorithms operate on 24-bit images. If you are currently operating on an 8-bit image, and you run an algorithm, the image will be converted up to 24-bits, the algorithm will be run, and the result will be converted back to 8-bits using the currently selected 24->8 algorithm. As such, if you're going to be doing a lot of algorithm-ing, you may find it faster to temporarily switch to 24-bit mode . Likewise, if you intend to run multiple algorithms on the same image (say, a Blur followed by an Emboss ), you should definitely switch to 24-bit mode , to maintain full 24-bit precision on the intermediate images (i.e., to prevent noise from being added to the image by any intermediate 24->8 conversions).

The (normally dimmed-out) Undo All selection undoes any and all algorithms that have been run on the current image. It restores the image to the state it was in when the first algorithm was executed, and it also puts xv back into the 8/24-bit mode it was in.
Keyboard Equivalent: <Meta> u
Runs a convolution over each plane (red, green, blue) of the image, using a n*n convolution mask consisting of all 1's. It has the effect of, for each pixel in the image, replacing it with the average value of all the pixels in the n*n rectangle centered around the pixel in question. When you select this command, a dialog box is opened up to request the value for ' n'. Values must be greater than or equal to '3', and they must also be odd (e.g. 3,7,5,9,11). Larger values blur the image to a greater extent.

Warning! This algorithm, due to its n^2 nature, can get very slow as n is increased. Values above '15' aren't particularly recommended.

Note: This command is a reasonable way to turn dithered black-and-white images back into some semblance of the greyscale that they probably originally started as.
Keyboard Equivalent: <Meta> b

Runs an edge-sharpening algorithm on the image, which attempts to maximize contrast between adjacent pixels. Prompts for a 'strength' value of 0% through 99%.
Keyboard Equivalent: <Meta> s
Runs a convolution using a pair of convolutions, one which detects horizontal edges, and one which detects vertical edges. The convolution is done separately for each plane (red, green, blue) of the image. It is only done for pixels that have the 3x3 mask fully contained within the image, to avoid pesky edge conditions. One note: since it runs an edge detection separately for each plane of the image, the results are colorful. You'll get red edges when there are edges in the red plane, yellow edges when there are edges in the red and green planes, and so on. If you'd like a traditional grey edge detection (based on the overall intensity of each pixel), you should use the Saturation dial in the xv color editor (See "The Saturation Control" ) to completely desaturate all the colors in the image (turning it grey) first. Then, the results will also be grey.
Keyboard Equivalent: <Meta> e
Runs an algorithm that produces nifty 'embossed' images by using a variation of the edge detection algorithm. It produces greyscale (8-bit) images where most of the image is shown as a medium gray. 'Leading' edges (edges found on the top and left sides) are shown as a lighter gray, and 'trailing' edges (bottom and right edges) are shown as a darker gray. The image wind up looking like pseudo-3-d, sort of like the Motif toolkit. You can then use the White dial in the xv color editor (See "The White Remapping Control" ) to colorize the image as you see fit
Keyboard Equivalent: <Meta> m
Does an 'oil transfer', as described in the book "Beyond Photography", by Holzman. It is a sort of localized smearing. The basic algorithm is to take a rectangle (7x7 in this case) centered around the current pixel, compute a histogram of these (49) pixels, and replace the current pixel with the 'most popular' pixel as determined by the histogram.
Keyboard Equivalent: <Meta> o
Blends a rectangular selection out of existence by replacing the selected area with a radial gradient fill. Each pixel on the edge of the selection retains its original color, the pixel in the center is replaced by the average of all the edge pixels, and all remaining pixels are replaced by the weighted average of the center pixel and the edge pixel (along the line that runs through the center pixel and the pixel being computed).

This is much easier to see than it is to explain.
Keyboard Equivalent: <Meta> B

Does arbitrary (smooth) rotation of the entire image (or the selected region). You will be prompted to enter a rotation amount, in degrees. Positive values rotate the image counter-clockwise, negative values rotate the image clockwise. The Copy Rotate function makes a copy of the selection, rotates it, and pastes it back on top of the original.
Keyboard Equivalent: <Meta> t
Also does arbitrary smooth rotation, as with the Copy Rotate command, but this version clears the original image (using the 'current color', see "Displaying Pixel Values" ) before pasting the rotated version.
Keyboard Equivalent: <Meta> T
Runs a 'pixelization' algorithm, suitable for obscuring sensitive and/or naughty parts of an image. Pops open a dialog box which prompts for either a single value ' m', or a pair of values ' mx n'. Divides the image (or the selected region) up into m-by- m squares (if a single value was entered) or m-by- n rectangles (if a pair of values were entered). Each area is filled with the average color of all pixels contained within the area.
Keyboard Equivalent: <Meta> p
Runs a 'random spread' algorithm on the selected area of the image (or the entire image). Pops up a dialog box which prompts for either a single value ' m', or a pair of values ' mx n'. In the case of the single value, each pixel in the image is swapped with some other random pixel located within a distance of m pixels from the first pixel. If two values are entered, each pixel is swapped with another pixel located within m, n of the original pixel. This can produce an interesting 'de-rez' effect. Whether it's useful or not is for you to decide.
Keyboard Equivalent: <Meta> S
Runs a despeckling algorithm, also known as a median filter among image-processing circles. This algorithm is good at removing minor noise from an image, such as you'll normally find on scanned-in faxes and the like. It may also prove useful for de-dithering images, turning black-and-white dithered images into greyscale images, and dithered color images into undithered color images. Note that the Blur algorithm can also be used in the same way, and may do a better job of un-dithering. However, the DeSpeckle algorithm generally leaves edges alone, unlike the Blur algorithm, which blurs everything uniformly.

This algorithm runs through the selected area of the image, and for each pixel in the image, looks at the m-by- m square centered around the pixel. It replaces the pixel with the median value of the pixels found in the square. As with the Blur algorithm, you will be prompted for a value of ' m'. The value must not be less than '3', and it must be odd. Larger values have a greater effect, though '3' should be sufficient for most purposes.
Keyboard Equivalent: <Meta> k

Cropping Commands
Crops the image to the current selection rectangle. This command is only available when a cropping rectangle has been drawn on the image. See "Cropping" for further information.
Keyboard Equivalent: c
Returns the image to its normal, uncropped state. This command is only available after the image has been cropped. See "Cropping" for further information.
Keyboard Equivalent: u
Crops off any constant-color borders that exist in the image. It will crop to the smallest rectangle that encloses the 'interesting' section of the image. It may not always appear to work because of minor invisible color changes in the image. As such, it works best on computer-generated images, and not as well on scanned images. In an attempt to get around this problem, if you AutoCrop while in 24-bit Mode , it will crop off portions that change by a little bit, not just portions that are exactly the same. Not that it works all that well.
Keyboard Equivalent: C

Also, you can 'fine-crop' an image, by holding the <Ctrl> key and pressing the arrow keys on your keyboard. Each press of the keys will remove one row (or column) of pixels from the appropriate edge. For example, pressing <Ctrl><Up> will crop off the bottom row of the image. Likewise, <Ctrl><Down> will crop off the top row, <Ctrl><Left> will crop off the right edge, and <Ctrl><Right> will crop off the left edge. It may sound backwards, but it does the Right Thing.

This 'fine-cropping' will work regardless of whether or not there is a selection rectangle currently drawn. If you accidentally crop too much off the image, you can use the UnCrop command described above to get the original image back.

Note that cropping never actually changes the image, only what portions are displayed. The original image can always be restored using the UnCrop command. Also, note that the 'cropping' commands and the 'zoom' commands (See "Zooming " ) are related, in that both affect the 'visible portion' of the image. The cropping commands maintain the same expansion factors by making the window larger or smaller, while the zooming commands maintain the same window size, and stretch the relevant portion of the image to fit. As such, the UnCrop command will also undo an zooming that you may have done.

Image Cut and Paste Commands

A new feature added to Version 3.10 is the ability to cut and paste arbitrary rectangular portions of images. You can cut (and copy) and paste within a single image, between two different images, or even between two running copies of xv. You can even cut or copy a portion of an image, exit xv, go out for dinner, come back, restart xv , and paste the previously-copied portion into the current image.

Copied image data is normally stored within the X Server's memory (in the ' XV_CLIPBOARD ' property), and remains there until some other data is copied, or until the X Server is reset (i.e., when you log off). This allows you to transfer image data between different copies of xv, and the xv's can even be running on different machines.

If there is not enough server memory available to hold the copied image data (this can happen if you copy a large amount of data, and you're using an X Terminal, as opposed to a workstation), xv will detect this, and fall back to using a file (' .xvclip ') in your home directory. Needless to say, this precludes transferring data between xv 's running on different machines, but it's better than nothing.

Copy . First, you must select a region to copy, via the selection rectangle mechanism (See "Selection Rectangle" ). Then, use this command to copy the selected data to the 'clipboard'.
Keyboard Equivalent: <Meta> c
Cut . Operates just like the Copy command, except that it also clears the selection to the 'current color', which is set using the pixel measurement tool. See "Displaying Pixel Values" for further information.
Keyboard Equivalent: <Meta> x
Paste . If there is no selection rectangle currently drawn, the first time you issue the Paste command, it will create a selection rectangle the size and shape of the image data that will be pasted. You may move and resize this rectangle as you see fit (See "Selection Rectangle" ). Then, when you have the selection appropriately adjusted, hit Paste a second time to actually paste the clipboard contents onto the image.

On the other hand, if you have a selection rectangle drawn when you hit Paste the first time, the image will be pasted into the selected area immediately.
Keyboard Equivalent: <Meta> v

Clear . Clears the selected region to the 'current color', which is set using the pixel measurement tool. See "Displaying Pixel Values" .
Keyboard Equivalent: <Meta> d

The Pad Command

The Pad command is the opposite of the Crop command. Sort of. It lets you add a border of a specified size to the edges of the image. It also lets you resize images to some desired size without manually expanding or cropping the image. But it goes further than that. There are a whole slew of interesting effects available, as described below:

Pad . Brings up the dialog box shown below.
Keyboard Equivalent: P

Pad Methods

There are three primary Pad methods, as shown to the left. These methods are accessible via the 'Pad Method' menu, which says 'Solid Fill' in the dialog box shown above. In all cases, the Pad command operates in the same basic way: A new image of the desired size is created, it is filled as specified, and the original image is pasted onto this new image, centered. If the new image is smaller than the original image, the original image will be cropped. Otherwise, the area outside the original image will have the new background.

Note: The new, padded image will have the same 8/24-bit mode as the original. As such, you probably want to switch to 24-bit Mode before issuing the Pad command, particularly if you intend to modify the image further. (See "The 24/8 Bit Menu" .)

The 'Pad Method' menu gives you three different ways of filling the background:

The background is filled with a solid color. The color may be specified by name, (as specified in the X11 ' rgb.txt ' file), by RGB values in the range 0- 255, separated by commas (e.g. '0,255,128'), or by RGB values in hexadecimal

(e.g. '0x00ff80'). In each case, the string you enter is parsed, and the background is filled solid with the specified color.

The external program bggen is executed to generate the background. This program is normally distributed with xv, and xv assumes that the executable is located somewhere in your search path (such as ' /usr/local/bin/bggen '). bggen can generate background gradients, at a specified angle. The gradient can be the entire size of the background, or it can repeat multiple times. See "External Programs" for a complete description of the bggen command.
An image file in any of the xv-supported formats may be loaded and used as the background. In this case, the background size (and therefore the size of the padded image) is equal to the size of the loaded background image. If you want a different size, you can load the background image (as a regular image), resize it as you see fit, save it, and use the newly saved version as the background for the original image.

Image Size Dials

These dials let you specify the size of the new, padded image in the "Solid" and "Run 'bggen'" modes. In the "Load Image" mode, the dials are disabled, as the new image size is dictated by the size of the loaded image.

If the image size dials are enabled, the small button above them resets them to the size of the currently-loaded image. Note that padding with the 'new' size equal to the current size won't actually do anything, unless you change the "Opaque" dial, described below.

Opaque-ness

This dial sets the 'opaque-itude' of the foreground (the original image). Normally, this is set to '100%', which simply means that everywhere the original image and the background overlap, the original image is what you'll see. If you set the dial to '0%', then wherever the original image and the background overlap, the background is what you'll see. In any case, at points where the foreground image does not overlap the background, you'll see the background, unmodified. (Practical upshot: at '0%' you will only see the background.)

Of course, most of the interesting effects happen when the dial is set to intermediate values, where the foreground image will appear semi-transparent.

There are four modes the 'Opaque' dial can operate in. They are selected by clicking the button located above the 'Opaque' dial.

RGB

The two images are blended together in the most obvious way. Each RGB color component in the new image is computed by taking a weighted average of the RGB components from the appropriate pixels in the foreground and background images. Like so:

R new = ( opaque% * R fg ) + ( (100 - opaque% ) * R bg ) (same for G and B)

INT

On overlapping pixels, only the Intensity components (the 'V' in the HSV colorspace, see "RGB & HSV Colorspaces" ) of the pixels are blended, using the same weighted average calculation shown above. If you set the 'Opaque' value to '0%', brightness of overlapping pixels will be completely determined by the 'background' pixel. It's possible to get some interesting 'masking' effects and whatnot by playing around with black&white backgrounds.

SAT

Similar to INT , except that it is the Saturation component (the 'S' in the HSV colorspace, see "RGB & HSV Colorspaces" ) of the two pixels that will be blended together, again using the weighted average calculation. The effects possible with this one are considerably more subtle, and not necessarily interesting. It is mainly included for completeness.

HUE

In this case, the colors of the two overlapping pixels are blended. You can get some interesting effects by setting 'Opaque' to '0%', and loading a colorful rainbow background. In this case, at all overlapping pixels, it will be as if the foreground image were a greyscale transparency, as the brightness and saturation will be controlled by the foreground, and the color will be controlled by the background.

Technical Note: The HUE case does not simply do a weighted average of the two hue components. Instead, it plots the two points on the edge of a standard color wheel, draws a straight line between them, and picks a point along this line based on the 'Opaque' value (i.e., the larger the value, the closer it is to the 'foreground' endpoint of the line). As a result, the HUE setting can affect both the hue and saturation components of the computed pixel. While this makes this 'Opaque' mode somewhat unlike the others, once again it is a fine example of xv's trademark "Do The Right Thing" technology.

Text Annotation

Starting in xv version 3.10, it is now possible to do text annotation, or what we in the business call "putting words on the picture". There is one thing to note, before you go diving in: xv's text annotation ability is Really Lame. I mean, Big Time Lame. It's awkward to use (to say the least), and not very powerful. Frankly, it's an embarrassment. But maybe it'll be useful to someone.

Now that your expectations are suitably low, here's how it works:

Text Annotation . First, if you have a selection rectangle drawn, get rid of it. Click this button to bring up a dialog box, where you can enter a single-line string. After you enter the string and press <Return > (or the Ok button in the dialog box), you will be presented with an appropriately-sized selection rectangle. You may reposition and resize this rectangle as you see fit. When you have the rectangle just so, use the Paste command to put the text on the image. The text will be pasted in the current color (See "Displaying Pixel Values" ). The text will be stretched to fit the selection rectangle.
Keyboard Equivalent: A

Note: if you want to change the color of the pasted text, pick a new color (via the 'eyedropper' described in "Displaying Pixel Values" ), and issue the Text Annotation command again. (It is not sufficient to simply Paste again.) Note that if you have a selection rectangle drawn, the Text Annotation command will not change the position or shape of the rectangle to reflect the new text, which lets you easily re- Paste over your last attempt.

The Grab Command

The Grab command in xv version 3.10 has been extensively improved. It is now possible to do delayed grabs , which can give you time to shuffle some windows around before the grab takes place. You can also do delayed auto-grabs , which gives you a way to grab pull-down menus and other actions that take place while a mouse-button is being held down.

Grab command. Clicking this button brings up the xv grab dialog box shown (and described) below.
Keyboard Equivalent: <Ctrl> g

A normal grab operation (issued by hitting the Grab button in the xv grab dialog box) operates as follows:

You can grab the entire contents of a window (including its frame) by clicking the Left mouse button in a window. If you click the Left button somewhere on the root window, the entire screen will be loaded into xv. Note: if you Left- click somewhere inside a window whose contents are drawn in a different visual than the frame (as happens on many 24-bit graphics systems, where the default visual is an 8-bit PseudoColor, but the window contents may be drawn in 24-bit TrueColor), the window frame will not be included in the grabbed image. (It is not possible to grab data from two different visuals simultaneously.)

You can grab an arbitrary region of the screen by clicking the Middle mouse button and dragging a rectangle in exactly the same way you draw a cropping rectangle. When you release the mouse button, the contents of this rectangle will be read from the screen and loaded into xv. Note: the image will be grabbed with respect to the visual of the outermost window that completely encloses the grabbed rectangle. (Practical upshot: on 24-bit systems, if you try to grab the contents of a 24-bit window, plus some of the (8-bit) root window, window frames, etc., you will not get what you probably wanted. Sorry.)

Or, alternately, you can simply abort the Grab command by clicking the Right mouse button anywhere on the screen.

A delayed grab is very similar to a normal grab, except that xv will wait for the specfied number of seconds, and then beep once to signify the start of the grab. You can then press the Left, Middle, or Right mouse buttons, as described above. To do a delayed grab, simply enter a non-zero number in the 'Delay' field, and press the Grab button in the xv grab dialog box.

A delayed auto-grab is another matter entirely. When you issue this command (by entering a non-zero number in the 'Delay' field, and pressing the AutoGrab button), xv will sleep for the specified number of seconds, and then automatically grab the full contents of whatever top-level window the mouse is positioned inside of. This makes it possible to grab things like pull-down menus that cannot be captured using the normal grab method. For example, to grab a pull-down menu in another program, set the 'Delay' field to something small (say, '5' seconds), hit the AutoGrab button, go to your other program, and open up the pull-down menu. Continue holding the menu open until xv beeps once (signifying the start of the grab), and then beeps twice (signifying the end of the grab). The entire top-level window containing your menu will be copied into xv. If you get more than you want, you can easily crop off the rest, using the cropping commands. (See "Cropping" )

Note: You may not be able to Grab all of the xv windows, at least not windows owned by the xv doing the grabbing. If you run into this minor inconvenience, simply start a second copy of xv and use it to grab the windows from the first xv (or vice-versa).

You can use the Grab command for a wide variety of purposes. For example, you can use it to print the contents of any window (or the whole screen) by grabbing the appropriate image, and then saving it as a PostScript file.

You can use the Grab command, in conjunction with xv's Zoom and UnZoom commands, as a reasonable, albeit overpowered and none-too-quick, replacement for the xmag program.

You can also use the Grab command to pick 'just the right colors' for any application. Simply start the application in question, Grab the window into xv, and use the xv color editor to twiddle the colors around to your heart's content.

Note: the Grab command does not work on Macintoshes running MacX in a 'rootless' mode, which isn't too surprising, if you think about it...

Working With Multiple Files

xv provides a set of controls that let you conveniently operate on a list of images. To use the following commands, you'll have to start up xv with a list of filenames. For example, you could type ' xv *.gif ' (assuming, of course, that you have a bunch of files that end with the suffix '.gif' in the current directory).

The filenames are listed in a scrollable window, as shown below. The current selection is shown in reverse video. If there are more names than will fit in the window, the scrollbar will be enabled.

Operating a List Window

The scrollbar operates as follows:

The File Commands

You can directly view any image in the list by double-clicking on its filename. If xv is unable to load the file (for any of a variety of reasons), it'll display an appropriate error message.

Attempts to load the next file in the list. If it is unable to load the next file, it will continue down the list until it successfully loads a file. If it gets to the bottom of the list without successfully loading a file, it will put up the default image.
Keyboard Equivalent: <Space>

Attempts to load the previous file in the list. If it is unable to load the previous file, it will continue up the list until it successfully loads a file. If it gets to the top of the list without successfully loading a file, it will put up the default image.
Keyboard Equivalent: <backspace>

This command lets you delete the currently selected file from the list (and optionally delete the associated disk file). Note that the currently selected file is the one with the highlight bar on it. While this is generally the same as the currently displayed image, it doesn't have to be.
Keyboard Equivalent: <Ctrl> d

The Delete command will pop up a window asking you what you want to delete. Your choices are:

Opens the xv load window, which lets you load images that weren't specified on the original command-line. See "The Load Window" for more details. Note: this function has been mostly taken over by the visual schnauzer (See "The Visual Schnauzer" ) but remains for largely historical reasons. (It is considerably faster than the schnauzer, however...)
Keyboard Equivalent: <Ctrl> l

Opens the xv save window, which lets you save the current image (or current selected area) in a variety of image formats. See "The Save Window" for more details.
Keyboard Equivalent: <Ctrl> s

Prints the current image to a PostScript 2 device.. This command takes a somewhat Unix-centric approach to printing, but it may work on other operating systems. When you issue this command, it opens a dialog box which prompts you for the 'print' command to use. Normally, this is just ' lpr ', but if you'd like to send the output to another printer, you could use something like ' lpr -Pelsewhere '. (And right after you do that, you should change the name of that printer!) You change the default command the appears in this window by using the ' xv.print ' X resource. See "Other Resources" .

Anyway, enter some command that will have the desired effect. xv will open up the xv postscript window, where you can fine-tune the size, position, and rotation of your image. See "The PostScript Window" for more information. When you press the Ok button, xv will generate the appropriate PostScript, and feed it as ' stdin ' to the command you entered earlier.
Keyboard Equivalent: <Ctrl> p

Image Reloading

It is occasionally desirable to reload an image file because the contents of the file have changed. For example, you could be downloading a file, and you might want to keep reloading the file to check on the progress of the download. Or perhaps you have a program that generates images, and you'd like to view these images without any manual intervention.

xv provides a way to reload an image via an external signal. If you send the xv process a SIGQUIT signal (' kill -QUIT <pid> ', or ' kill -3 <pid> ' on most systems), the program will reload the currently selected file. (The one that is currently highlighted in the xv controls window filename list.) This behavior is exactly the same as hitting <Return> in the xv controls window. If xv is currently in a state where hitting <Return> in the controls window won't load an image (i.e., some pop-up dialog box is grabbing all such events), then sending this signal won't work either.

An idea: You could write a 'clock' program that, once a minute, generates a really spiffy looking picture of the current time (with color gradations, 3-d extruded numbers, whatever), then sends xv the signal to reload the generated image. If anyone ever does this, I'd like to hear about it.

Note: This will not work if the current file was read from <stdin> .

xv also has a 'polling mode', enabled by the ' -poll ' option. When it is turned on, xv will attempt to recognize when the currently displayed file changes on disk. (What with UNIX being a multi-tasking OS, it's perfectly possible to have another process modify a file while xv is displaying it.) When the current file changes, xv will reload it.

You can use this feature to get xv to monitor all sorts of things. For example, if you have one of those programs that automatically goes out and ftps the latest version of the US weather map, (and you do, in the unsupt directory), then you can have xv automatically reload the map whenever a new one is downloaded.

It probably goes without saying that 'PostScript' is a registered trademark of Adobe Systems, Inc.

You could even use xv as a sort of frame buffer, to allow otherwise non-X programs to display graphics. Just have your program draw on its own internal 'frame buffer' (just an appropriately sized hunk of memory), and periodically write it out to a file in some xv-supported format. The PBM/PGM/PPM formats are trivial to write. See the documentation in the doc subdirectory of the xv distribution. Anyhow, periodically write the image to a file, and have xv display the file with the ' -poll ' option turned on. Voila! An instant output-only frame buffer for X workstations, albeit a fairly slow one.

The Windows Menu

As an obvious result of xv's patented "Keep-Adding-Code-Until-It- Breaks" Technology, there are considerably more commands, features, cool gizmos, and dubious design decisions than will comfortably fit in the xv controls window.

Luckily, this is nothing that bolting-on a couple more top-level windows won't fix, which is the method that has been used.

This is where the Windows menu comes into play, though in practice you'll probably just use the keyboard equivalents to open the other windows. I know I do.

Opens up a xv visual schnauzer window (you can have up to four of them). The visual schnauzer lets you manipulate your image file collection in a nifty Point'n'Click, Drag'n'Drop, What You See Is What You Get, Graphical User Interface. Despite all that, it's actually a useful thing. See "The Visual Schnauzer" for more info.
Keyboard Equivalent: <Ctrl> v

Opens and closes the xv color editor window. The color editor provides you with an interesting collection of color manipulation doodads, including a colormap editor, hue remapping controls, arbitrary R, G, B, and I gamma correction curves, and so on. See "The Color Editor " for more info.
Keyboard Equivalent: e

Opens and closes the xv info window. This window gives you detailed information about the current image, the current selection, the success/failure of the color allocation code, and such. See "The Info Window" for more info.
Keyboard Equivalent: I

Opens the xv image comments window. This lets you view any comments that may be encoded in the current image. It does not let you add or edit any comments, as that's a project for a later release. Note that, currently, the vast majority of images do not have comments in them. My fault, no doubt. See "The Comment Window" for more details.
Keyboard Equivalent: <Ctrl> c

Opens the xv text viewer window. Displays the contents of the currently selected file (i.e., the file selected in the filename list in the xv controls window), as ASCII text, or as a hexadecimal dump. This happens automatically when xv tries to load a file in a format it doesn't recognize. See "The TextView Window" for more info.
Keyboard Equivalent: <Ctrl> t

Opens the xv text viewer window, and displays version information, copyright notice, licensing information, the author's email addresses, and such. Basically, it's the text of the first two (or so) pages of this manual.
Keyboard Equivalent: <Ctrl> a

Opens the xv text viewer window, and displays a summary of all the keyboard equivalents and mouse button permutations.

Other Commands

Does exactly the same thing as the About XV command described in "The Windows Menu" : displays version number, licensing info, etc.

'Reloads' and displays the xv logo image, which not only contains the version number and revision date of this copy, it also has some nifty 3-D fish.

The logo image also displays who, if anyone, this particular copy of xv is licensed to. If it still says "UNREGISTERED COPY", you should probably do something about that.
Keyboard Equivalent: <none whatsoever>

Quits xv. Quite possibly the most useful command of them all.
Keyboard Equivalents: q and <Ctrl> q

This document was extracted from the PostScript documentation and formatted by Roy Johnson. Much of the process was automated, and may therefore have introduced errors. Corrections are appreciated.