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