Class MedianCutQuantizer
java.lang.Object
net.sourceforge.jiu.ops.Operation
net.sourceforge.jiu.ops.ImageToImageOperation
net.sourceforge.jiu.color.quantization.MedianCutQuantizer
- All Implemented Interfaces:
RGBQuantizer
,RGBIndex
Performs the Median Cut color quantization algorithm
for a given list of colors.
Supported image types
The input image must implementRGB24Image
.
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:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
The default method to determine the representative color from a list of colors.private boolean
private RGBColorList
private int
private int
static final int
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 final int
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 final int
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.private boolean
private int
private MedianCutNode
Fields inherited from interface net.sourceforge.jiu.data.RGBIndex
INDEX_BLUE, INDEX_GREEN, INDEX_RED
-
Constructor Summary
ConstructorsConstructorDescriptionCreates a MedianCutQuantizer object and initializes its fields to default values. -
Method Summary
Modifier and TypeMethodDescriptionprivate void
addNodes
(MedianCutNode[] nodeList, MedianCutNode node) private RGBColorList
createColorList
(RGB24Image image) Creates a linear list of leaf nodes.Creates a palette with the representative colors of all leaf nodes.void
private MedianCutNode
Traverses tree given by argument node and returns leaf with largest distribution of samples for any of its three components.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
private int[]
findRepresentativeColor
(int index1, int index2) Computes a representative color for a set of colors in the color list.private void
Calls findRepresentativeColor with node if node is a leaf.int
Returns the method (to be) used to determine the representative color for the list of colors of a node.int
Returns the number of colors in the destination image.boolean
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
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.private int
setPaletteIndexValues
(MedianCutNode node, int index) Recursively visits node and its descendants, assigning ascending palette index values to leaves via MedianCutNode.setPaletteIndex(int).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 istrue
) or paletted (argument useTruecolor isfalse
).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
-
Field Details
-
METHOD_REPR_COLOR_AVERAGE
public static final int METHOD_REPR_COLOR_AVERAGEConstant 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:
-
METHOD_REPR_COLOR_WEIGHTED_AVERAGE
public static final int METHOD_REPR_COLOR_WEIGHTED_AVERAGEConstant 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:
-
METHOD_REPR_COLOR_MEDIAN
public static final int METHOD_REPR_COLOR_MEDIANConstant 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:
-
DEFAULT_METHOD_REPR_COLOR
public static final int DEFAULT_METHOD_REPR_COLORThe 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 viasetMethodToDetermineRepresentativeColors(int)
.- See Also:
-
doNotMap
private boolean doNotMap -
list
-
maxValue
private int maxValue -
method
private int method -
outputTruecolor
private boolean outputTruecolor -
paletteSize
private int paletteSize -
root
-
-
Constructor Details
-
MedianCutQuantizer
public MedianCutQuantizer()Creates a MedianCutQuantizer object and initializes its fields to default values.
-
-
Method Details
-
addNodes
-
createColorList
- Throws:
OperationFailedException
-
createLeafList
Creates a linear list of leaf nodes. Assumes thatfindPalette()
was successfully run before. -
createPalette
Creates a palette with the representative colors of all leaf nodes. Assumes thatfindPalette()
was successfully run before.- Specified by:
createPalette
in interfaceRGBQuantizer
- Returns:
- palette with all representative colors
-
findLeafToBeSplit
Traverses tree given by argument node and returns leaf with largest distribution of samples for any of its three components. -
findNearestNeighbor
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
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() -
findRepresentativeColor
private int[] findRepresentativeColor(int index1, int index2) Computes a representative color for a set of colors in the color list. Returns the color as a length three int array of sample values (which can be accessed using the index constants fromRGBIndex
. The method of determining the color (the REPR_xxx constants from this class) has been given to the constructor. -
findRepresentativeColors
Calls findRepresentativeColor with node if node is a leaf. Otherwise, recursively calls itself with both successor nodes. -
getMethodToDetermineRepresentativeColors
public int getMethodToDetermineRepresentativeColors()Returns the method (to be) used to determine the representative color for the list of colors of a node. Default isDEFAULT_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:
-
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 interfaceRGBQuantizer
- Parameters:
origRgb
- the three samples red, green and blue for which a good match is searched in the palettequantizedRgb
- 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
-
mapImage
-
process
public void process() throws MissingParameterException, OperationFailedException, WrongParameterExceptionDescription 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 classOperation
- Throws:
MissingParameterException
- if any mandatory parameter was not given to the operationWrongParameterException
- 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
-
setPaletteIndexValues
Recursively visits node and its descendants, assigning ascending palette index values to leaves via MedianCutNode.setPaletteIndex(int). If this method is called with root and 0 as parameters, all leaves will get a unique palette index. -
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:
-
setTruecolorOutput
public void setTruecolorOutput(boolean useTruecolor) Lets the user specify if the output image is to be truecolor (argument useTruecolor istrue
) or paletted (argument useTruecolor isfalse
). 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
-