.TH COLORQUANT 3 "August 14, 1989"
.UC 4
.SH NAME
colorquant \- variance-based color quantization
.SH SYNOPSIS
#include <colorquant.h>
.PD 0
.HP
.B
int colorquant(red, green, blue, npix, colormap, colors, bits, rgbmap, flags, accum_hist)
.LP
.B
unsigned char *red, *green, *blue;
.br
.B
unsigned long npix;
.br
.B
unsigned char *colormap[3];
.br
.B
int colors, bits;
.br
.B
unsigned char *rgbmap;
.br
.B
int flags;
.br
.B
int accum_hist;
.PD
.SH DESCRIPTION
.I 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
.I colorquant 
are:
.TP
.I red, green, blue
The red, green and blue channels of the image.  The ith pixel is represented
as the RGB triple (\fIred\fR[i], \fIgreen\fR[i], \fIblue\fR[i]).  These
arrays usually contain values that have been 'prequantized' (see below).
.TP
.I npix
The length, in bytes, of the \fIred\fR, \fIgreen\fR and \fIblue\fR arrays.
Equal to the total number of pixels in the image.
.TP
.I 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.  \fIcolormap\fR[0][i], \fIcolormap\fR[1][i], and
\fIcolormap\fR[2][i] are, respectively, the red, green and blue components
of the ith colormap entry.
.TP
.I colors
The number of pre-allocated colormap entries.  The image will be quantized to
at most this many colors.
.TP
.I bits
The number of significant bits in each entry of the \fIred\fR, \fIgreen\fR and
\fIblue\fR arrays.  Normally, the red, green and blue arrays contain
values that have been prequantized to fewer than eight
significant bits (see \fIflags\fP 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 \fIrgbmap\fR and the internal histogram are
proportional to (2^\fIbits\fR)^3. 
.TP
.I rgbmap
A pointer to an array of unsigned chars of size (2^\fIbits\fR)^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:
.ce 1
colorindex = \fIrgbmap\fR[(((r << \fIbits\fR) | g) << \fIbits\fR) | b];
where r, g, and b are the prequantized red, green and blue components of
the pixel in question.
.TP
.I flags
A collection of bit-flags that modify the operation of
\fIcolorquant\fP.  Currently defined values are \fBCQ_FAST\fP,
\fBCQ_QUANTIZE\fP, and \fBCQ_NO_RGBMAP\fP.  
.br
If \fBCQ_FAST\fP is set, the construction of \fIrgbmap\fP will be
relatively fast.  If not, \fIrgbmap\fR will be built slowly but more
accurately.  In most cases, the error introduced by the 'fast'
approximation is barely noticeable.
.br
If \fBCQ_QUANTIZE\fP is set, the values in \fIred\fP, \fIgreen\fP, and
\fIblue\fP are taken as 8-bit values and will be quantized to
\fIbits\fP significant bits by \fIcolorquant\fP.  If not set, these
values are assumed to be prequantized.  
.br
If \fBCQ_NO_RGBMAP\fP is set, \fIrgbmap\fP will not be built.
.TP
.I accum_hist
This argument provides a facility to accumulate multiple images into a
single colormap.  If 
.I accum_hist
is zero, the routine works normally.  To build a colormap for several
images, \fIaccum_hist\fP 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 \fIaccum_hist\fP will compute the
\fIcolormap\fP and \fIrgbmap\fP.  The values of \fIcolors\fP and
\fIbits\fP should not change during this process.  The arguments
\fIcolormap\fP, \fIrgbmap\fP, and \fIfast\fP are ignored if
\fIaccum_hist\fP is 1 or 2, and 
.IR red ,
.IR green ,
.IR blue ,
and
.IR npix
are ignored if \fIaccum_hist\fP is 3.
.SH AUTHOR
Craig Kolb, Yale University.
.br
Martin Friedmann, MIT Media Lab did the \fIaccum_hist\fP changes.
.SH REFERENCE
Wan, Wong, and Prusinkiewicz,
\fIAn Algorithm for Multidimensional Data Clustering,\fR
Transactions on Mathematical Software, Vol. 14 #2 (June, 1988), pp. 153-162.
.SH SEE ALSO
.IR rlequant (1),
.IR inv_cmap (3).