javax.media.jai.operator
Class ColorQuantizerDescriptor

java.lang.Object
  |
  +--javax.media.jai.OperationDescriptorImpl
        |
        +--javax.media.jai.operator.ColorQuantizerDescriptor

All Implemented Interfaces:

OperationDescriptor, RegistryElementDescriptor, Serializable

public class ColorQuantizerDescriptor

extends OperationDescriptorImpl

This OperationDescriptor defines the "ColorQuantizer" operation.

This operation generates an optimal lookup table (LUT) based on the provided 3-band RGB source image by executing a color quantization algorithm. This LUT is stored in the property "JAI.LookupTable" that has a type of LookupTableJAI. Thus, it can be retrieved by means of getProperty. This LUT can be further utilized in other operations such as "errordiffusion" to convert the 3-band RGB image into a high-quality color-indexed image. The computation of the LUT can be deferred by defining a DeferredProperty from the property "JAI.LookupTable" and providing that as the parameter value for "errordiffusion". This operation also creates a color-indexed destination image based on the nearest distance classification (without dithering). However, the quality of this classification result may not be as good as the result of "errordiffusion".

The supported source image data type is implementation-dependent. For example, the Sun implementation will support only the byte type.

The data set used in the color quantization can be defined by the optional parameters xPeriod, yPeriod and ROI. If these parameters are provided, the pixels in the subsampled image (and in the ROI) will be used to compute the LUT.

Three built-in color quantization algorithms are supported by this operation: Paul Heckbert's median-cut algorithm, Anthony Dekker's NeuQuant algorithm, and the Oct-Tree color quantization algorithm of Gervautz and Purgathofer.

The median-cut color quantization computes the 3D color histogram first, then chooses and divides the largest color cube (in number of pixels) along the median, until the required number of clusters is obtained or all the cubes are not separable. The NeuQuant algorithm creates the cluster centers using Kohonen's self-organizing neural network. The Oct-Tree color quantization constructs an oct-tree of the color histogram, then repeatedly merges the offspring into the parent if they contain a number of pixels smaller than a threshold. With the equivalent parameters, the median-cut algorithm is the fastest, and the NeuQuant algorithm is the slowest. However, NeuQuant algorithm can still generate a good result with a relatively high subsample rate, which is useful for large images. In these three algorithms, the Oct-Tree algorithm is the most space consuming one. For further details of these algorithms, please refer to the following references:

Algorithm	References
Median-Cut	Color Image Quantization for Frame Buffer Display, Paul Heckbert, SIGGRAPH proceedings, 1982, pp. 297-307
NeuQuant	Kohonen Neural Networks for Optimal Colour Quantization, Anthony Dekker, In Network: Computation in Neural Systems, Volume 5, Institute of Physics Publishing, 1994, pp 351-367.
Oct-Tree	Interactive Computer Graphics: Functional, Procedural, and Device-Level Methods by Peter Burger and Duncan Gillis, Addison-Wesley, 1989, pp 345.

The generated LUT may have fewer entries than expected. For example, the source image might not have as many colors as expected. In the oct-tree algorithm, all the offspring of a node are merged if they contain a number of pixels smaller than a threshold. This may result in slightly fewer colors than expected.

The learning procedure of the NeuQuant algorithm randomly goes through all the pixels in the training data set. To simplify and speed up the implementation, the bounding rectangle of the provided ROI may be used (by the implementation) to define the training data set instead of the ROI itself.

Resource List

Name	Value
GlobalName	ColorQuantizer
LocalName	ColorQuantizer
Vendor	com.sun.media.jai
Description	Generates an optimal LUT by executing a color quantization algorithm, and a color-indexed image by the nearest distance classification.
DocURL	http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/operator/ColorQuantizerDescriptor.html
Version	1.1
arg0Desc	The color quantization algorithm name. One of ColorQuantizerDescriptor.MEDIANCUT, ColorQuantizerDescriptor.NEUQUANT, or ColorQuantizerDescriptor.OCTTREE
arg1Desc	The maximum color number, that is, the expected number of colors in the result image.
arg2Desc	This is an algorithm-dependent parameter. For the median-cut color quantization, it is the maximum size of the three-dimensional histogram. For the neuquant color quantization, it is the number of cycles. For the oct-tree color quantization, it is the maximum size of the oct-tree.
arg3Desc	The ROI in which the pixels are involved into the color quantization.
arg4Desc	The subsample rate in x direction.
arg4Desc	The subsample rate in y direction.

Parameter List

Name	Class Type	Default Value
quantizationAlgorithm	javax.media.jai.operator.ColorQuantizerType	ColorQuantizerDescriptor.MEDIANCUT
maxColorNum	java.lang.Integer	256
upperBound	java.lang.Integer	32768 for median-cut, 100 for neuquant, 65536 for oct-tree
roi	javax.media.jai.ROI	null
xPeriod	java.lang.Integer	1
yPeriod	java.lang.Integer	1

Since:

JAI 1.1.2

See Also:

ROI, OperationDescriptor, Serialized Form

Field Summary

static ColorQuantizerType	MEDIANCUT The pre-defined median-cut color quantization algorithm.
static ColorQuantizerType	NEUQUANT The pre-defined NeuQuant color quantization algorithm.
static ColorQuantizerType	OCTTREE The pre-defined Oct-Tree color quantization algorithm.

Fields inherited from class javax.media.jai.OperationDescriptorImpl

resources, sourceNames, supportedModes

Fields inherited from interface javax.media.jai.OperationDescriptor

NO_PARAMETER_DEFAULT

Constructor Summary

ColorQuantizerDescriptor()
Constructor.

Method Summary

static RenderedOp	create(RenderedImage source0, ColorQuantizerType algorithm, Integer maxColorNum, Integer upperBound, ROI roi, Integer xPeriod, Integer yPeriod, RenderingHints hints) Color quantization on the provided image.
Range	getParamValueRange(int index) Returns the minimum legal value of a specified numeric parameter for this operation.
protected boolean	validateParameters(String modeName, ParameterBlock args, StringBuffer msg) Returns true if this operation is capable of handling the input parameters.

Methods inherited from class javax.media.jai.OperationDescriptorImpl

arePropertiesSupported, getDefaultSourceClass, getDestClass, getDestClass, getInvalidRegion, getName, getNumParameters, getNumSources, getParamClasses, getParamDefaults, getParamDefaultValue, getParameterListDescriptor, getParamMaxValue, getParamMinValue, getParamNames, getPropertyGenerators, getPropertyGenerators, getRenderableDestClass, getRenderableSourceClasses, getResourceBundle, getResources, getSourceClasses, getSourceClasses, getSourceNames, getSupportedModes, isImmediate, isModeSupported, isRenderableSupported, isRenderedSupported, makeDefaultSourceClassList, validateArguments, validateArguments, validateParameters, validateRenderableArguments, validateRenderableSources, validateSources, validateSources

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MEDIANCUT

public static final ColorQuantizerType MEDIANCUT

The pre-defined median-cut color quantization algorithm.

NEUQUANT

public static final ColorQuantizerType NEUQUANT

The pre-defined NeuQuant color quantization algorithm.

OCTTREE

public static final ColorQuantizerType OCTTREE

The pre-defined Oct-Tree color quantization algorithm.

Constructor Detail

ColorQuantizerDescriptor

public ColorQuantizerDescriptor()

Constructor.

Method Detail

getParamValueRange

public Range getParamValueRange(int index)

Returns the minimum legal value of a specified numeric parameter for this operation.

validateParameters

protected boolean validateParameters(String modeName,
                                     ParameterBlock args,
                                     StringBuffer msg)

Returns true if this operation is capable of handling the input parameters.

In addition to the default validations done in the super class, this method verifies that the provided quantization algorithm is one of the three predefined algorithms in this class.

Overrides:

validateParameters in class OperationDescriptorImpl

Throws:

IllegalArgumentException - If args is null.

IllegalArgumentException - If msg is null and the validation fails.

create

public static RenderedOp create(RenderedImage source0,
                                ColorQuantizerType algorithm,
                                Integer maxColorNum,
                                Integer upperBound,
                                ROI roi,
                                Integer xPeriod,
                                Integer yPeriod,
                                RenderingHints hints)

Color quantization on the provided image.

Creates a ParameterBlockJAI from all supplied arguments except hints and invokes JAI.create(String,ParameterBlock,RenderingHints).

Parameters:

source0 - RenderedImage source 0.

algorithm - The algorithm to be chosen. May be null.

maxColorNum - The maximum color number. May be null.

upperBound - An algorithm-dependent parameter. See the parameter table above. May be null.

roi - The region of interest. May be null.

xPeriod - The X subsample rate. May be null.

yPeriod - The Y subsample rate. May be null.

hints - The RenderingHints to use. May be null.

Returns:

The RenderedOp destination.

Throws:

IllegalArgumentException - if source0 is null.

See Also:

JAI, ParameterBlockJAI, RenderedOp