JIU 0.12.0 Homepage

net.sourceforge.jiu.color.quantization
Class MedianCutQuantizer

java.lang.Object
  extended bynet.sourceforge.jiu.ops.Operation
      extended bynet.sourceforge.jiu.ops.ImageToImageOperation
          extended bynet.sourceforge.jiu.color.quantization.MedianCutQuantizer
All Implemented Interfaces:
RGBIndex, RGBQuantizer

public class MedianCutQuantizer
extends ImageToImageOperation
implements RGBIndex, RGBQuantizer

Performs the Median Cut color quantization algorithm for a given list of colors.

Supported image types

The input image must implement RGB24Image.

Usage example

The following code snippet uses the default settings with a palette of 256 entries.
 MedianCutQuantizer quantizer = new MedianCutQuantizer();
 quantizer.setInputImage(image);
 quantizer.setPaletteSize(256);
 quantizer.process();
 PixelImage quantizedImage = quantizer.getOutputImage();
 
If you want to combine Median Cut quantization with error diffusion dithering to improve the visual quality of the output, try the ErrorDiffusionDithering class. However, note that noise is introduced into the image with dithering methods so that the resulting image may not be suitable for automatic processing.

Credits

The Median Cut algorithm was designed by Paul Heckbert. He described it in the article Color image quantization for frame buffer display. Comput. Graphics 16(3), 1982, 297 - 304. CiteSeer page of the article.

Author:
Marco Schmidt
See Also:
MedianCutContourRemoval, ErrorDiffusionDithering

Field Summary
static int DEFAULT_METHOD_REPR_COLOR
          The default method to determine the representative color from a list of colors.
static int METHOD_REPR_COLOR_AVERAGE
          Constant value for a method of determining the representative color for a set of colors by computing the average of all samples for each of the three components red, green and blue.
static int METHOD_REPR_COLOR_MEDIAN
          Constant value for a method of determining the representative color for a set of colors by picking the median value of all samples for each of the three components red, green and blue.
static int METHOD_REPR_COLOR_WEIGHTED_AVERAGE
          Constant value for a method of determining the representative color for a set of colors by computing the weighted average of all samples for each of the three components red, green and blue.
 
Fields inherited from interface net.sourceforge.jiu.data.RGBIndex
INDEX_BLUE, INDEX_GREEN, INDEX_RED
 
Constructor Summary
MedianCutQuantizer()
          Creates a MedianCutQuantizer object and initializes its fields to default values.
 
Method Summary
 MedianCutNode[] createLeafList()
          Creates a linear list of leaf nodes.
 Palette createPalette()
          Creates a palette with the representative colors of all leaf nodes.
 void findAllRepresentativeColors()
           
 MedianCutNode findNearestNeighbor(int[] rgb)
          For a given RGB value, searches the node in the internal node tree whose representative color is closest to this color.
 int findNearestNeighbor(MedianCutNode[] nodes, int red, int green, int blue)
          For each node in the argument array computes the distance between the representative color of that node and the color given by the three argument samples.
 void findPalette()
           
 int getMethodToDetermineRepresentativeColors()
          Returns the method (to be) used to determine the representative color for the list of colors of a node.
 int getPaletteSize()
          Returns the number of colors in the destination image.
 boolean getTruecolorOutput()
          Returns if this operation is supposed to generate truecolor or paletted output.
 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.
 void mapImage(RGB24Image in, Paletted8Image out)
           
 void mapImage(RGB24Image in, RGB24Image out)
           
 void process()
          This method does the actual work of the operation.
 void setAllPaletteIndexValues()
           
 void setMapping(boolean doMap)
          Defines whether process will map the input image to an output image.
 void setMethodToDetermineRepresentativeColors(int newMethod)
          Sets the method to determine the representative color for a list of colors.
 void setPaletteSize(int newPaletteSize)
          Sets the number of colors that this operations is supposed to reduce the original image to.
 void setTruecolorOutput(boolean useTruecolor)
          Lets the user specify if the output image is to be truecolor (argument useTruecolor is true) or paletted (argument useTruecolor is false).
 void splitNode(MedianCutNode node)
           
 
Methods inherited from class net.sourceforge.jiu.ops.ImageToImageOperation
canInputAndOutputBeEqual, ensureImagesHaveSameResolution, ensureInputImageIsAvailable, ensureOutputImageResolution, getInputImage, getOutputImage, setCanInputAndOutputBeEqual, setInputImage, setOutputImage
 
Methods inherited from class net.sourceforge.jiu.ops.Operation
addProgressListener, addProgressListeners, getAbort, removeProgressListener, setAbort, setProgress, setProgress
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

METHOD_REPR_COLOR_AVERAGE

public static final int METHOD_REPR_COLOR_AVERAGE
Constant value for a method of determining the representative color for a set of colors by computing the average of all samples for each of the three components red, green and blue. #getMethodToDetermineRepresentativeColors #setMethodToDetermineRepresentativeColors

See Also:
Constant Field Values

METHOD_REPR_COLOR_WEIGHTED_AVERAGE

public static final int METHOD_REPR_COLOR_WEIGHTED_AVERAGE
Constant value for a method of determining the representative color for a set of colors by computing the weighted average of all samples for each of the three components red, green and blue. Weighted means that each color is multiplied by the number of times it occurs in the input image. The values of samples multiplied by their frequency are then divided by the total number of times the colors appear in the image. #getMethodToDetermineRepresentativeColors #setMethodToDetermineRepresentativeColors

See Also:
Constant Field Values

METHOD_REPR_COLOR_MEDIAN

public static final int METHOD_REPR_COLOR_MEDIAN
Constant value for a method of determining the representative color for a set of colors by picking the median value of all samples for each of the three components red, green and blue. #getMethodToDetermineRepresentativeColors #setMethodToDetermineRepresentativeColors

See Also:
Constant Field Values

DEFAULT_METHOD_REPR_COLOR

public static final int DEFAULT_METHOD_REPR_COLOR
The default method to determine the representative color from a list of colors. Will be used if none is set by the user of this class via setMethodToDetermineRepresentativeColors(int).

See Also:
Constant Field Values
Constructor Detail

MedianCutQuantizer

public MedianCutQuantizer()
Creates a MedianCutQuantizer object and initializes its fields to default values.

Method Detail

createLeafList

public MedianCutNode[] createLeafList()
Creates a linear list of leaf nodes. Assumes that findPalette() was successfully run before.


createPalette

public Palette createPalette()
Creates a palette with the representative colors of all leaf nodes. Assumes that findPalette() was successfully run before.

Specified by:
createPalette in interface RGBQuantizer
Returns:
palette with all representative colors

findNearestNeighbor

public MedianCutNode findNearestNeighbor(int[] rgb)
For a given RGB value, searches the node in the internal node tree whose representative color is closest to this color.

Parameters:
rgb - the color for which a match is searched; the array must have at least three entries; RGBIndex constants are used to address the samples
Returns:
node with best match

findNearestNeighbor

public int findNearestNeighbor(MedianCutNode[] nodes,
                               int red,
                               int green,
                               int blue)
For each node in the argument array computes the distance between the representative color of that node and the color given by the three argument samples.

Returns:
index of the node with the smallest distance or -1 if the array has a length of 0

findPalette

public void findPalette()

findAllRepresentativeColors

public void findAllRepresentativeColors()

getMethodToDetermineRepresentativeColors

public int getMethodToDetermineRepresentativeColors()
Returns the method (to be) used to determine the representative color for the list of colors of a node. Default is DEFAULT_METHOD_REPR_COLOR.

Returns:
the method, one of the METHOD_xyz constants

getPaletteSize

public int getPaletteSize()
Returns the number of colors in the destination image. If output is paletted, this is also the number of entries in the palette.

Returns:
number of colors in the destination

getTruecolorOutput

public boolean getTruecolorOutput()
Returns if this operation is supposed to generate truecolor or paletted output.

Returns:
if truecolor images are to be generated
See Also:
setTruecolorOutput(boolean)

map

public int map(int[] origRgb,
               int[] quantizedRgb)
Description copied from interface: RGBQuantizer
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.

Specified by:
map in interface RGBQuantizer
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

mapImage

public void mapImage(RGB24Image in,
                     RGB24Image out)

mapImage

public void mapImage(RGB24Image in,
                     Paletted8Image out)

process

public void process()
             throws MissingParameterException,
                    OperationFailedException,
                    WrongParameterException
Description copied from class: Operation
This method does the actual work of the operation. It must be called after all parameters have been given to the operation object.

Overrides:
process in class Operation
Throws:
MissingParameterException - if any mandatory parameter was not given to the operation
WrongParameterException - if at least one of the input parameters was not initialized appropriately (values out of the valid interval, etc.)
OperationFailedException

setAllPaletteIndexValues

public void setAllPaletteIndexValues()

setMapping

public void setMapping(boolean doMap)
Defines whether process will map the input image to an output image. If not, only the palette is determined.


setMethodToDetermineRepresentativeColors

public void setMethodToDetermineRepresentativeColors(int newMethod)
Sets the method to determine the representative color for a list of colors. After the algorithm has determined sets of colors that lie closely together in color space and will be mapped to the same color in the destination image, the algorithm will determine that color

Parameters:
newMethod - the new method, one of the METHOD_xyz constants in this class

setPaletteSize

public void setPaletteSize(int newPaletteSize)
Sets the number of colors that this operations is supposed to reduce the original image to.

Parameters:
newPaletteSize - the number of colors
Throws:
IllegalArgumentException - if the argument is smaller than 1 or larger than 256
See Also:
getPaletteSize()

setTruecolorOutput

public void setTruecolorOutput(boolean useTruecolor)
Lets the user specify if the output image is to be truecolor (argument useTruecolor is true) or paletted (argument useTruecolor is false). If the color type is to be changed afterwards, use PromoteToRgb24 to convert from paletted to truecolor. Reducing a truecolor image that uses only 256 or less colors to a paletted image can be done with AutoDetectColorType.

Parameters:
useTruecolor -

splitNode

public void splitNode(MedianCutNode node)

JIU 0.12.0 Homepage

Copyright © 2000, 2001, 2002, 2003, 2004 Marco Schmidt