DATASERV (kappserv) functions


LIBRARY ROUTINE

kcolor_gamut_object - perform color quantization of 1..4 plane images

LIBRARY CALL

int kcolor_gamut_object (
   kobject src,
   int ncolors,
   int bits,
   double fraction,
   kobject dest )

INPUT

OUTPUT

RETURN VALUE

TRUE (1) on success, FALSE (0) on failure

DESCRIPTION

kcolor_gamut_object uses a variation of Paul Heckbert's median cut algorithm to perform color quantization of one, two, three, or four plane images producing a single-plane image with color map.

The quantization is performed by isolating clusters of "neighboring" color vectors in a four dimensional histogram, with each axis being one of the color components. The clusters are obtained using a modified version of Heckbert's median cut. The true colors are then matched to the closest cluster, and the input vector 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 decent, provided that a reasonable number (say 128 or more) 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 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 by 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.

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. The color map will contain the number of entries requested (meaning all colors in the image) with any extra entries zero padded.

Multiple plane images are processed by quantizing each plane independently, generating a corresponding plane of colors in the map. Thus an input object with (w,h,d,t,e)=(512,480,10,10,4) will result in an output object with a value segment with dimensions (512,480,10,10,1) and a map segment with dimensions (4,10,10,10,1).

ADDITIONAL INFORMATION

none

EXAMPLES

none

SIDE EFFECTS

none

RESTRICTIONS

none

MODIFICATION

27-Dec-94 Scott Wilson: Major revisions. 1. Added support for more than 256 output colors 2. Cleaned up much error handling and memory resource recovery code. 3. Added support for 1..4 bands of color data, which means that you can handle RGB alpha. 4. Use better hasher now, added hash table instrumentation and statistics. 5. Force a map size of ncolors regardless of the number actually present. 1-Jan-95 Scott Wilson: 1. Added support for multi-plane processing.

FILES

$DATASERV/objects/library/kappserv/src/gamut.c

SEE ALSO

kappserv(3)

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.