
vgamut(1)                    Khoros                     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 sub-
                    space 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 clus-
     ter, 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 preci-
     sion takes longer and great gobs of memory, but looks good,
     provided that a reasonable number (say 128) colors is speci-
     fied.  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 alloca-
     tion 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 sub-
     ject 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 sub-
            space 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) vmap-
     data(1)

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

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

Khoros                    Release: 1.0                          1

