DragonFly On-Line Manual Pages

Search: Section:  

COLORQUANT(3)         DragonFly Library Functions Manual         COLORQUANT(3)


NAME

       colorquant - variance-based color quantization


SYNOPSIS

       #include <colorquant.h>
       int colorquant(red, green, blue, npix, colormap, colors, bits, rgbmap,
              flags, accum_hist)
       unsigned char *red, *green, *blue;
       unsigned long npix;
       unsigned char *colormap[3];
       int colors, bits;
       unsigned char *rgbmap;
       int flags;
       int accum_hist;


DESCRIPTION

       Colorquant performs variance-based color quantization on a given image.
       A representative colormap and a table for performing RGB to colormap
       index mapping are computed.  The number of colors to which the image
       was quantized (the total number of colormap entries computed) is
       returned.  The arguments to colorquant are:

       red, green, blue
              The red, green and blue channels of the image.  The ith pixel is
              represented as the RGB triple (red[i], green[i], blue[i]).
              These arrays usually contain values that have been
              'prequantized' (see below).

       npix   The length, in bytes, of the red, green and blue arrays.  Equal
              to the total number of pixels in the image.

       colormap
              Points to a pre-allocated, three-channel colormap.  These arrays
              will be filled with the colormap values computed by the
              variance-based color quantization algorithm.  colormap[0][i],
              colormap[1][i], and colormap[2][i] are, respectively, the red,
              green and blue components of the ith colormap entry.

       colors The number of pre-allocated colormap entries.  The image will be
              quantized to at most this many colors.

       bits   The number of significant bits in each entry of the red, green
              and blue arrays.  Normally, the red, green and blue arrays
              contain values that have been prequantized to fewer than eight
              significant bits (see flags below).  Five significant bits
              usually represents a good tradeoff between image quality and
              running time.  Anything above six significant bits will likely
              lead to excessive paging, as the size of rgbmap and the internal
              histogram are proportional to (2^bits)^3.

       rgbmap A pointer to an array of unsigned chars of size (2^bits)^3.
              This array is used to map from pixels to colormap entries.  The
              prequantized red, green and blue components of a pixel are used
              as an index into this array to retrieve the colormap index that
              should be used to represent the pixel.  The array is indexed as:
                   colorindex = rgbmap[(((r << bits) | g) << bits) | b];
              where r, g, and b are the prequantized red, green and blue
              components of the pixel in question.

       flags  A collection of bit-flags that modify the operation of
              colorquant.  Currently defined values are CQ_FAST, CQ_QUANTIZE,
              and CQ_NO_RGBMAP.
              If CQ_FAST is set, the construction of rgbmap will be relatively
              fast.  If not, rgbmap will be built slowly but more accurately.
              In most cases, the error introduced by the 'fast' approximation
              is barely noticeable.
              If CQ_QUANTIZE is set, the values in red, green, and blue are
              taken as 8-bit values and will be quantized to bits significant
              bits by colorquant.  If not set, these values are assumed to be
              prequantized.
              If CQ_NO_RGBMAP is set, rgbmap will not be built.

       accum_hist
              This argument provides a facility to accumulate multiple images
              into a single colormap.  If accum_hist is zero, the routine
              works normally.  To build a colormap for several images,
              accum_hist should have the value 1 for the first image, and 2
              for subsequent images.  Finally, after all the images have been
              processed, a value of 3 for accum_hist will compute the colormap
              and rgbmap.  The values of colors and bits should not change
              during this process.  The arguments colormap, rgbmap, and fast
              are ignored if accum_hist is 1 or 2, and red, green, blue, and
              npix are ignored if accum_hist is 3.


AUTHOR

       Craig Kolb, Yale University.
       Martin Friedmann, MIT Media Lab did the accum_hist changes.


REFERENCE

       Wan, Wong, and Prusinkiewicz, An Algorithm for Multidimensional Data
       Clustering, Transactions on Mathematical Software, Vol. 14 #2 (June,
       1988), pp. 153-162.


SEE ALSO

       rlequant(1), inv_cmap(3).

4th Berkeley Distribution       August 14, 1989                  COLORQUANT(3)

Search: Section: