XV3: Unix Image Manipulation: A Basic Helpsheet

I. Files:

XV is a Unix XWindows program for displaying and manipulating graphic images. It will read images in the following formats:

GIF, JPEG, TIFF, PBM, PGM, PPM, X11 bitmap, Utah Raster Toolkit RLE, PDS/VICAR, Sun Rasterfile, BMP, PCX, IRIS RBG, and PM.

You can load an image into XV by issuing the command xv [filename] at the Unix prompt or from within XV by using the Control Window discussed below. XV will also save files in the following formats:

GIF, PM, PBM (raw), PBM (ascii), X11 Bitmap, Sun Rasterfile, BMP, PostScript, IRIS, JPEG and TIFF.

II. Mouse:

As with most XWindows applications, XV uses a three-button mouse as its main interface. When the cursor is located within the XV window, clicking the left mouse button will display numeric pixel information in the following format:

n,n = n,n,n (n n n HSV)
The first two numbers are the x and y coordinates within the image of the selected pixel. The second three number are the RGB values of the pixel, where each number can have an integer number from 0-255 (see Color Editor below). The third set of numbers reveal the HSV values of the selected pixel.

You may have limited use for this feature.

The middle mouse button allows you to crop a rectangular portion of the image by clicking and dragging (see below).

The right mouse button alternately calls up and dismisses the XV Controls Window.

III. Controls Window:

As its name suggests, this window contains the control points for the application's main manipulation tools. The menu buttons are laid out in two sections: a group of 17 in the upper two-thirds of the window that control the file handling; and a three by seven block of buttons at the bottom controlling the image manipulation. Beginning at the top and working down:

Display: XV can display the chosen file in one of two ways: as an independent window, and as an image on the root window. In almost all cases you will be using the former for image work, as it presents the graphic in a window and allows you to use the XV tools. The root window display in essence gives you a "background" images, placing the graphic behind all the windows and icons, and removing its sensitivity to the mouse.

The Display Menu also contains a number of color allocation options. When calling up an image, the default setting, Normal Colors, will allocate as many available colors as possible, mapping the remaining colors into the closest colors that it did get. In addition, the Read/Write Colors option prevents XV from sharing colors with other applications, which will speed up the rate at which changes through the XV Color Editor (below) are applied. For most uses this approximation method will suffice. If, however, a more accurate representation of colors is needed, you can try:

Perfect Colors: When this option is chosen, XV will proceed with color allocation as in Normal Colors. If it fails to allocate all colors exactly, though, it will free existing allocations and begin again, this time creating its own private colormap. This option will usually provide a more accurate allocation.

Use Own Colormap: This option begins by creating its own private colormap and allocating from there. It runs slightly faster than Perfect Colors.

Use Std. Colormap: When working with multiple images, you can very quickly run out of colors by overloading the color buffer. Use Std. Colormap forces all images to use the same set of standard colors, using dither to make the approximate match. Because of this color sharing, the individual images may not look as nice; however, you won't run out of colors.

24/8 Bit: XV now supports both 8- and 24-bit color (what Paintbrush calls Color Photo and Millions of Colors). This menu shows what mode you are currently in, and with Lock current mode, allows you to force all subsequent images into the chosen format. If you have locked on 8-bit and load a 24- bit image, the three bottom options designate how XV will convert the file. Quick is the fastest but produces the worst images; Slow (the default process) uses a simple algorithm to pick 256 colors and then dithers to these colors; and Best uses a more complex algorithm to select the 256 colors. In general Slow takes twice the time as Quick, and Best takes ten-times as long as Slow.

Algorithms: XV contains a set of rudimentary image-processing tools which it places under this menu option: the Blur choices will "convolute" the image to varying degrees, depending on whether you choose 3x3, 5x5 or 7x7; Edge Detection will reduce an image to a rough outline; Emboss creates a gray "3-D relief" image; and Oil Painting smears the image in interesting ways, producing a sort of "Modernist" effect.

Visual Schnauzer: This menu option opens a window containing icons for each file in a directory and gives you the ability to create thumbnail images for each of the graphics files. This can prove a useful aid in locating files within large directories. In the Visual Schnauzer window:
1. Misc. Commands presents a menu of options allowing you to delete or Rename a file, create a New directory, reScan the current directory to reflect changes, open a new Schnauzer window (up to four total), create thumbnail icons for the entire directory (Update icons) or for selected files (Generate icons(s)), view the text of a file, Quit XV or Close the window.
2. At the bottom of the Schnauzer window, the most often-used options from the Misc. Commands window are listed.
The thumbnail images created by XV for the Schnauzer are about 2k apiece and located in a hidden subdirectory named .xvpics. Once XV creates the thumbnail image the program retains the image for as long as the file remains in the directory, obviating the necessity to update with each new use.

Directly below the Visual Schnauzer button is a group of 12 buttons controlling miscellaneous file management options: Next and Prev control the highlight bar in the file listing window to the left; Load, Save and Delete allow you to control the files themselves; Info displays size and colormap info in the selected file; TextView and Comments display text information contained in the selected file; and Quit closes XV. In addition, there are two quite useful and important applications in this window area, ColEdit (discussed in a separate section below) and:
1. Grab. The Grab option takes an arbitrary portion of the screen and copies it to the XV window. When you click the Grab button the machine will beep once. This tells you that Grab has been initiated. You then have three options:
  1. Clicking the left mouse button on a window will grab the entire window, including frame, and place it within the active XV window.
  2. Clicking the middle mouse button and dragging it will create a temporary rectangle. Anything on the screen within the rectangle when you release the button will be grabbed and placed in the active XV window.
  3. Clicking the right mouse button cancels the Grab command.
  There is a new switch available at the command line that will tell XV to delay starting the grab feature a specified number of seconds. When you first open xv, if you add "-grabdelay n", XV will wait n seconds between the time you click on the Grab button and the time it begins the Grab option. This will allow you time to remove any windows that might be obscuring your image.
The bottom row of 21 buttons contains buttons controlling the basic text manipulation commands, including image cropping, sizing, rotation and smoothing. Bear in mind that these features alter the way the image is displayed on the screen and does not change the original image. Only by saving do you make the changes permanent.
1. Crop Commands. To select one rectangular portion of an image and zoom in on it, use the middle mouse button to block off the desired section. Once the portion is blocked, clicking on Crop will place only the blocked section in the XV window. UnCrop will return the image to the uncropped state within the window. AutoCrop will locate any same-color border space at the edge of an image and remove it.
2. Resizing Commands. When you call up an image in XV, the application attempts to establish a one-to-one correspondence between the image and screen pixel maps, i.e., one image pixel will be mapped to one screen pixel. If the image is larger than the screen, XV will scale it down maintaining the aspect ration. If, while changing the shape of an image the size and/or aspect get skewed, the Normal command will restore the image to its original size and pixel correspondence.
  
  Xv can only display an image as large as the monitor screen. Max Size will make the image as large as the screen, irrespective of aspect ratio; Maxpect will make the image as large as possible while maintaining the original aspect ratio. Dbl Size and Half Size will alter the image accordingly. The buttons with diagonal arrows within rectangles will increase or decrease the size of the image by 10%. SetSize opens a dialogue box offering three modes to specify size: "n x n", which dictates the size in screen pixels; "n%", which dictates percentage of overall expansion or contraction; and "n% x n%", which dictates the percentage of horizontal and vertical expansion or contraction. Finally, the three buttons IntExpnd, Aspect and 4x3 offer default or "rounding" resizing.
3. Rotate & Flip Commands. The buttons featuring left and right circular arrows will rotate the image 90 degrees left or right. The button featuring a vertical line and two opposing horizontal arrows will flip the image along the vertical axis, while the button featuring a horizontal line and two opposing vertical arrows will flip the image along the horizontal axis.
4. Smoothing Commands. If the displayed image is plagued with inaccurate colors, the Dith command will dither available colors in an attempt to approximate the original colormap. The Smooth command compensates for "integer round-off" that occurs when an image is expanded or shrunk. Raw cancels both commands and returns the image to it original state.

IV. Color Editor:

Probably the most useful feature of XV, the Color Editor allows you to manipulate an image's colormap pixel by pixel, modify its overall hue, saturation and value, and change its red-green-blue balance. The controls are located in three sections of the Color Editor window, labelled Colormap Editing, HSV Modification, and RGB Modification. Since the applications offered by the first section tend to react in unpredictable ways with the second and third, XV's creator John Bradley suggests that you use Colormap Editing independent of either of the other two. In addition, there is a fourth section located in the lower left corner of the window containing controls that affect the entire Color Editor.

Colormap Editing. In 2-bit and 8-bit images, a complete colormap appears at the top of this section (it's disabled for 24-bit images). Each cell corresponds to a color in the window image, and you can highlight a cell either by clicking on the color in the image or on the cell in the color map. The three dials beneath the map allow you to change the red, green and blue values of each cell.

You can "sort" a range of cells into a smooth gradient by clicking the left mouse at the beginning of the range and the middle button at the end. You can also create groups of cells linked together for manipulation purposes. To create a group, hold down the key and click the left mouse button on a cell. This marks that cell as the group's "anchor." Still holding down the key, click the right mouse button on each cell you wish to include in the group (clicking again will de-select a cell). Each member of the group will take on the same color value as the anchor. Furthermore, you can change the color value of all members of a group using the three color dials.

Six buttons beneath the colormap control various effects: Grey converts the image to greyscale; RevVid inverts the colors (most useful in black & white); ColUndo reverses the last change that altered a color cell's value, including the grouping and ungrouping of cells and dial alterations; Revert returns the colormap to its original state and releases all groupings; RGB/HSV toggles the editing dials between applying change in terms of red-green-blue and applying change in terms of hue-saturation-value; and Random, which generates a random colormap...fun but of little use.

HSV Modification. While you can easily change the color value of a pixel, at some point you may wish to alter instead the hue, saturation or intensity of a range of colors. XV provides controls for remapping hue in terms of red-yellow- green-cyan-blue-magenta, as well as the saturation and intensity or a range. These controls tend toward the complex, and you should consult the manual if you suspect you'd like to use these tools.

Bear in mind that the eight colors modifiable through the HSV tools themselves are constituted of the three primary colors: red, green and blue. The makeup of the colors looks like this:
```
                          Red   Grn  Blue
           White           Y     Y    Y
           Black           N     N    N
           Red             Y     N    N
           Green           N     Y    N
           Blue            N     N    Y
           Yellow          Y     Y    N
           Cyan            N     Y    Y
           Magenta         Y     N    Y
```
RGB Modification. The three graphs provide access to global levels of red, green and blue in an image. In general, bowing the line towards the upper left increases a color while bowing down left decreases it. In addition, a vertical line will provide high contrast will a horizontal line will provide low contrast. Arranged along the left edge of each graph are tools that allow you to add or subtract the number of control squares on the line, and preset modification shapes.

Color Editor Controls. While the three control groups discussed above deal with either single colors or with hues, this final group controls the entire Color Editor window. The most useful of these controls (Brite, Dim, Sharp & Dull) allow you to quickly change the brightness and contrast of the image.
1. Apply. This displays the current image with the current color settings
2. NoMod. This displays the current image without any color modifications.
3. Undo. XV maintains a series of "history files" containing the 32 previous states of the current image. Undo cycles back through these earlier states. Note that by moving back to a previous state and changing that state you eliminate all states subsequent to it.
4. Redo. This button moves you forward through the same set of "history files."
5. Reset. This resets the HSV and RGB controls, but not the Colormap Editing tool.
6. 1, 2, 3, 4, and Set. The numbered buttons contain preset HSV and RBG values, while the Set button allows you to load settings into each button.
7. CutRes. Should you wish to save your current color and hue settings, CutRes copies them into your X server's buffer. From there you can paste them into .Xdefaults or .Xresources, whichever system file you use.
8. Close. Closes the Color Editor window.
9. Brite, Dim, Sharp and Dull. These buttons globally change the brightness (Brite and Dim) and contrast (Sharp and Dull) of the current image.
10. Norm. This button expands the contrast range of the current image by moving the darkest pixel to the least intense setting and the brightest pixel to the most intense setting. By forcing the image into the largest dynamic range it increases the scope and precision of any manipulations.
11. HistEq. According to XV's creator, "the only modification [HistEq] makes to the image is to generate a bizarre corrective Intensity curve." Go figure.
12. Display with HSV/RGB mods. Indicates whether the image in the active window is being displayed in unmodified or modified state. The Apply and NoMod buttons change the setting of this box.
13. Auto-apply HSV/RGB mods. This determines whether the image display is updated after each modification to the HSV or RGB controls.
14. Auto-apply while dragging. This determines whether the image display is updated after each modification to the Color Editor dials and graphs.
15. Auto-reset on new image. If you have a series of similar images and you think the color manipulations from one will apply to all, by turning this off you can tell XV to keep the setting when loading a new image. If not (most of the time), leave this option turned on.