Package net.sourceforge.jiu.color.quantization

# Interface RGBQuantizer

All Known Implementing Classes:
  `ArbitraryPaletteQuantizer`, `MedianCutQuantizer`, `OctreeColorQuantizer`, `PopularityQuantizer`, `UniformPaletteQuantizer`

public interface RGBQuantizer
An interface for an RGB color quantizer. Color quantizers take an input image and produce an output image that looks like the original but uses less colors. Keeping the error (the difference between input and output image) as small as possible is important - the more similar input and output are, the better.

Similarity between to pixels (or, more accurately, the colors of two pixels) can be defined by their distance in color space. Imagine two colors given by (r1, g1, b1) and (r2, g2, b2). The distance can then be defined as sqrt((r1 - r2)2 + (g1 - g2)2 + (b1 - b2)2) (with sqrt being the square root).

A quantizer has two main tasks:

1. Find a palette. Some quantizers create custom palettes for a given input (e.g. `MedianCutQuantizer` or `OctreeColorQuantizer`, other quantizers use fixed palettes (e.g. `UniformPaletteQuantizer`). Using a custom palette typically results in a better output image (it is more similar because it takes into consideration the content of the input). However, using fixed palettes requires less CPU time and memory and is sufficient in many cases from a point of view of output quality.

   If a quantizer does use a fixed palette, this first step obviously is not so much about finding the palette but about specifying it.

2. Map the input image to the palette. For each pixel in the truecolor input image the mapping procedure must find the color in the palette that is closest to that input pixel so that the difference between source and destination pixel is as small as possible.

   The code that does the mapping from the original to any given palette could be shared among quantizers - after all, the goal is always the same, picking the palette entry with the smallest distance in color space to the original pixel. However, sometimes the data structures built while finding the palette can be reused for faster mapping from the original to output. This is the case for both the MedianCutQuantizer and the OctreeColorQuantizer.

Dithering methods like error diffusion dithering may be used to increase the quality of the output. Note however that dithering introduces noise that makes the quantized image harder to compress and in some cases unusable for post-processing (the noise may be an obstacle for image processing algorithms).

This quantizer interface was designed with JIU's error diffusion dithering operation `ErrorDiffusionDithering` in mind.

Author:
  Marco Schmidt

## Method Summary

Modifier and Type
Method
Description
`Palette`
`createPalette()`
Return a Palette object with the list of colors to be used in the quantization process.
`int`
`map(int[] origRgb, int[] quantizedRgb)`
This method maps a triplet of intensity values to its quantized counterpart and returns the palette index of that quantized color.

## Method Details

### createPalette

Palette createPalette()
Return a Palette object with the list of colors to be used in the quantization process. That palette may be fixed or created specifically for a given input image.

Returns:
  Palette object for destination image

### map

int map(int[] origRgb, int[] quantizedRgb)
This method maps a triplet of intensity values to its quantized counterpart and returns the palette index of that quantized color. The index values for the two arrays are taken from RGBIndex.

Parameters:
  `origRgb` - the three samples red, green and blue for which a good match is searched in the palette
  `quantizedRgb` - will hold the three samples found to be closest to origRgb after the call to this method
Returns:
  int index in the palette of the match quantizedRgb