csColorQuantizer Class Reference (Crystal Space 2.0 Public API Reference)

| ## Public API Reference

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions
csColorQuantizer Class Reference
Graphics

Color quantizer. More...

`#include <csgfx/quantize.h>`

List of all members.

## Public Member Functions
void | Begin ()
| Begin quantization.
void | Bias (csRGBpixel *colors, int count, int weight)
| Bias the color histogram towards given colors (weight = 0..100)
void | Count (csRGBpixel *image, int pixels, csRGBpixel *transp=0)
| Count the colors in a image and update the color histogram.
| csColorQuantizer ()
| Construct a new quantizer object.
void | DoRGB (csRGBpixel *image, int pixels, int pixperline, uint8 *&outimage, csRGBpixel *&outpalette, int &maxcolors, bool dither)
| Quantize a RGB image into a paletted image.
void | End ()
| Finish quantization.
void | Palette (csRGBpixel *&outpalette, int &maxcolors, csRGBpixel *transp=0)
| Compute the optimal palette for all images passed to QuantizeCount()
void | Remap (csRGBpixel *image, int pixels, uint8 *&outimage, csRGBpixel *transp=0)
| Remap a image to the palette computed by Palette()
void | RemapDither (csRGBpixel *image, int pixels, int pixperline, csRGBpixel *palette, int colors, uint8 *&outimage, csRGBpixel *transp=0)
| Same but apply Floyd-Steinberg dithering for nicer (but slower) results.
| ~csColorQuantizer ()
| Destruct and cleanup.

## Detailed Description

Color quantizer.

The algorithm presented here is a variation of well-known and widely-used Heckbert quantization algorithm. It works in the following way: first, we build a 3-D histogram that describes which colors and how many times the corresponding colors were used. Since we deal with RGB images, all possible colors counts to 256^3 = 16777216 colors, too much to keep in memory. Because of this, we ignore several lowest bits from each color component, taking into consideration human eye's sensivity to different color components we take 5 bits for R, 6 bits for G and 4 bits for B. This summary reduces to 32*64*16 = 32768 histogram cells, which is a reasonable size for an dynamically-allocated array.

Next, we take the entire color box and split it into subboxes. The split happens along the longest of R,G,B axis into half (and taking again into account eye sensivity). After which we take again the biggest box, and split it again and so on until we have that much boxes how much colors we want. Then we assign to each box a color index, and compute the median RGB value for each box.

To keep memory requirements in reasonable bounds, we scale down R/G/B components to 5/6/4 bits respectively. This produces results that are different from those we'll get with, say, 6/7/6 resolution but its a quite suitable solution, for a quality vs speed choice. I've tried 5/6/5 as well as 6/6/4 and its really hard to say they are better - the results are definitely different but it's hard to say they are really better.

WARNING: If the sum of R+G+B bits exceeds 16, you will a need special case for big endian machines for the INDEX_B macro (see below). With big-endian machines the B component starts at bit 8, thus the right shift counter becomes negative. Probably the best solution is to add an #if B_BIT + 8 - HIST_B_BITS - HIST_G_BITS - HIST_R_BITS < 0.

Quantizing
The following routines can be used to split the quantization process into small steps. First, you should call Begin(). This will allocate some memory for color histogram and also do some other maintenance work. Then you call Count () as much times as you want, to count the frequencies of colors. This is a quite fast operation, thus you can use it, for example, to compute a optimal palette for a large number of images (for example, software 3D renderer uses it for computing the optimal palette in paletted modes, by passing every texture to Count()).

When you're finished with images, call Palette(). This will compute the optimal palette. If you need just that, you can call End() and you're done. If you need to remap all those textures to the optimal palette, you can call Remap() as much times as you wish. Finally you anyway should call End() to free all the memory used by quantizer.

Now, a typical quantization sequence could look like this:

     Begin ();

        Count (image, pixels);
       Count (...);
       ...

       int maxcolors = 256;
       Palette (outpalette, maxcolors);
       // now maxcolors contains the actual number of palette entries

       Remap (image, pixels, outimage);
       Remap (...);
       ...

     End ();

The quantizer itself keeps track of its current state, and will silently ignore invalid calls. For example, if you call Remap() right after calling Begin() nothing will happen. You still can call Palette() right after Begin(), and you will get the expected black (or let's call it `empty') palette.

The Bias routine can be used to introduce a bias inside the currently open color histogram towards given colors. The "weight" parameter shows how important those colors are (0 - not at all, 100 - very). This can be used to bias the resulting palette towards some hard-coded values, for example you may want to use it to create a relatively uniform palette that is somewhat biased towards the colors contained in some picture(s).

Some routines accept an additional parameter (csRGBpixel *transp). If it is 0, nothing special is performed. If it is non-0, it should point to an valid csRGBpixel object; the color of that pixel will be treated in a special way: Count() will ignore pixels of that color, Palette() will allocate color index 0 for that color, and Remap will map all such pixel values to index 0.

Definition at line 129 of file quantize.h.

## Constructor & Destructor Documentation

csColorQuantizer::csColorQuantizer | ( |  | ) |

Construct a new quantizer object.

csColorQuantizer::~csColorQuantizer | ( |  | ) |

Destruct and cleanup.

## Member Function Documentation

void csColorQuantizer::Begin | ( |  | ) |

Begin quantization.

void csColorQuantizer::Bias | ( | csRGBpixel * | colors,
|  | int | count,
|  | int | weight
| ) |  |

Bias the color histogram towards given colors (weight = 0..100)

void csColorQuantizer::Count | ( | csRGBpixel * | image,
|  | int | pixels,
|  | csRGBpixel * | transp = `0`
| ) |  |

Count the colors in a image and update the color histogram.

void csColorQuantizer::DoRGB | ( | csRGBpixel * | image,
|  | int | pixels,
|  | int | pixperline,
|  | uint8 *& | outimage,
|  | csRGBpixel *& | outpalette,
|  | int & | maxcolors,
|  | bool | dither
| ) |  |

Quantize a RGB image into a paletted image.

This is a relatively expensive operation, in both CPU and memory resources terms. It is pretty fast though (more than 3.200.000 pixels/sec on a relatively weak P5/166) for what it does. It uses a variation of well-known Heckbert quantization algorithm. The side bonus after quantization is that the palette is ordered in most-used-first fashion. If outimage is 0, it is allocated. If outpalette is 0, it is allocated as well. If it is non-0, the routine supposes that the storage the pointers point to has enough size to store resulting image and palette (the size of resulting image is exactly "pixels" bytes, the size of resulting palette is palsize colors).

Parameters:

  image | input image
  pixels | number of pixels in input image
  pixperline | number of pixels in one line
  outimage | output image (allocated if 0)
  outpalette | output palette (allocated if 0)
  maxcolors | maximal number of colors in output palette (actual number of colors on return)
  dither | Use/do not use Floyd-Steinberg dithering

void csColorQuantizer::End | ( |  | ) |

Finish quantization.

void csColorQuantizer::Palette | ( | csRGBpixel *& | outpalette,
|  | int & | maxcolors,
|  | csRGBpixel * | transp = `0`
| ) |  |

Compute the optimal palette for all images passed to QuantizeCount()

void csColorQuantizer::Remap | ( | csRGBpixel * | image,
|  | int | pixels,
|  | uint8 *& | outimage,
|  | csRGBpixel * | transp = `0`
| ) |  |

Remap a image to the palette computed by Palette()

void csColorQuantizer::RemapDither | ( | csRGBpixel * | image,
|  | int | pixels,
|  | int | pixperline,
|  | csRGBpixel * | palette,
|  | int | colors,
|  | uint8 *& | outimage,
|  | csRGBpixel * | transp = `0`
| ) |  |

Same but apply Floyd-Steinberg dithering for nicer (but slower) results.

The documentation for this class was generated from the following file:

- csgfx/quantize.h