vgamut(1)

PROGRAM
vgamut - Compress 3-band (24-bit) images to N-plane pseudo color

SYNTAX

vgamut

-i  input image filename

-o  output image filename

[-n]
    specifies the number of colors to compress to

[-p]
    grey levels are truncated to this number of bits

[-r]
    fraction of color splits based on color subspace 2-norm

[-V]
    Gives the version for vgamut

[-U]
    Gives the usage for vgamut

[-P]
    Prompts for command line options

[-A [file1]]
    Creates the answer file called vgamut.ans or file1

[-a [file1]]
    Uses vgamut.ans or file1 as the answer file

DESCRIPTION
vgamut takes a 3 band multi-spectral image, where each band would normally represent one component of a 24-bit RGB image, and generates a pseudo color image with a specified number of colors that can be displayed using editimage or putimage. The object is to make the displayable image look like the true 24-bit RGB image even though the number of colors is greatly restricted.

The color compression is performed by isolating clusters of "neighboring" colors in a three dimensional histogram, with each axis being one of the color components. The clusters are obtained using a modified version of Heckberts median cut. The true colors are then matched to the closest cluster, and the input RGB triplet is then re-mapped to an n-color pseudo color image.

To keep the histogram from becoming exceedingly large (max of around 2^24 bytes), one may need to quantize the grey levels of the input bands to less than 8 bits. 6 bits (64 levels) gives results that are reasonable in a short amount of time. The number of bits that are kept is called the color precision, which can be specified at execution time. The general tradeoff is that smaller precision is faster and takes less memory, but it looks worse too. High precision takes longer and great gobs of memory, but looks good, provided that a reasonable number (say 128) colors is specified. The execution time is very dependent on the image statistics. In general, a small number of colors is faster than a large number of colors. In either case, if the image has good spatial color coherence, execution time is greatly reduced.

The allocation fraction (-r) controls how large areas of nearly the same color are handled. An allocation fraction of 0.0 will cause the large areas to be broken into as many colors as possible with the largest areas of a particular color range being broken first. An allocation fraction of 1.0 will attempt to preserve the detail in the image be preserving the color range of all parts of the image at the expense of smooth coloring of the larger areas. An allocation fraction of around 0.2 to 0.5 gives very good results on most images.

As a special note, be sure that the input image has a map that has one-to-one correspondence to the pixel values (i.e. the pixel value is the grey level). If this is not the case, use vmapdata(1) to convert to a linear map.

If the input image contains less than the number of colors requested then the output image will contain only the number of colors present in the input image. A diagnostic messsage will printed to STDERR when this occurs, provided that the KHOROS_VERBOSE environment variable is set.

No dithering is done by vgamut. Dithering in color space can often cause the image to look very noisy due to the color sensitivity of the eye. The result images from vgamut may display some banding effects, but these are often more tolerable visually than the noise that would result from a color dithering process.

If the KHOROS_VERBOSE environment variable is set then an additional diagnostic message, the number of colors actually found in the image, will be printed. The color count is subject to the color precision specified by the -p option.

REQUIRED ARGUMENTS

-i  type: infile
    desc: input image filename

-o  type: outfile
    desc: output image filename

OPTIONAL ARGUMENTS

-n  type: integer
    desc: specifies the number of colors to compress to
    default: 128
    bounds: 1 < [-n] < 256

-p  type: integer
    desc: grey levels are truncated to this number of bits
    default: 6
    bounds: 1 < [-p] < 8

-r  type: float
    desc: fraction of color splits based on color subspace 2-norm
    default: 0.5
    bounds: 0.000000 < [-r] < 1.000000

EXAMPLES
vgamut -i lenna.rgb.xv -o lenna.250.xv -n 250 -p 8

generates a viewable color image of "lenna.rgb.xv" with 250 colors and full color precision.

SEE ALSO
intro(1), verror(3), vgparms(3), vutils(3), lvgamut(3) vmapdata(1)

RESTRICTIONS
vgamut works only on BYTE images with three bands of data.

COPYRIGHT
Copyright 1991, University of New Mexico. All rights reserved.