Table of Contents
colorquant - variance-based color quantization
#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;
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.
Craig Kolb,
Yale University.
Martin Friedmann, MIT Media Lab did the accum_hist changes.
Wan,
Wong, and Prusinkiewicz, An Algorithm for Multidimensional Data Clustering,
Transactions on Mathematical Software, Vol. 14 #2 (June, 1988), pp. 153-162.
rlequant(1)
, inv_cmap(3)
.
Table of Contents