com.gif4j.quantizer
Class Quantizer

java.lang.Object
  extended bycom.gif4j.quantizer.Quantizer

public final class Quantizer
extends java.lang.Object

Java implementation of Wu's Color Quantizer algorithm (see Graphics Gems vol. II, pp. 126-133, Author: Xiaolin Wu wu@csd.uwo.ca).

Algorithm description: "Greedy orthogonal bipartition of RGB space for variance minimization aided by inclusion-exclusion tricks."

Quantizer reduces the number of unique colors (quantizes) of BufferedImage instances to the specified number of colors (this parameter is set by actual color number or by color bit depth (hereinafter CBD) value). The available CBD values are between 2 (4 colors) and 16 (65536 colors). Quantized BufferedImage instances have IndexColorModel as ColorModel (if CBD less than or equal to 8) or DirectColorModel for CBD values more than 8.
Quantizer automatically detects the presence of alpha-channel (image transparency) and retains it unchangeable if CBD more than 8 (result - DirectColorModel based BufferedImage instance) or converts Transparency.TRANSLUCENT transparency to Transparency.BITMASK transparency.
Please note, that GIF format support images with CBD less than or equal to 8 and one transparent color which equals (from the viewpoint of Java) to IndexColorModel based BufferedImage(s) with Transparency.BITMASK or Transparency.OPAQUE transparency.

This implementation supports 2 memory-oriented modes and 4 optimization-oriented modes. The final processing mode is received by combination of one memory and one optimization modes.

In LOW MEMORY mode Quantizer uses less memory (up to 4 times) but usually (not always!) generates coarser results.
In NORMAL MEMORY mode Quantizer works more accurately but slower (up to 2 times).

Optimization-oriented modes are the next:

  1. FAST mode - the fastest mode (up to 5 times than others modes) but the most rough.
  2. OPTIMIZED mode - optimized version of the FAST mode. In this mode quantizer executes some additional operations during color correlation between source and generated color tables.
  3. FAST DITHER mode - based on the FAST mode but Quantizer executes additional error dispersion operation based on Floyd-Steinberg dithering algorithm. Please note that due to speed-targeting implementation some small color errors can be occured.
  4. OPTIMIZED DITHER mode - based on the OPTIMIZED mode but Quantizer executes additional error dispersion operation based on Floyd-Steinberg dithering algorithm.

  5. Floyd-Steinberg dithering algorithm implementation is based on ppmquant.c (Copyright (C) 1989, 1991 by Jef Poskanzer)

Within the Gif4J Library Quantizer is used by default. The default quantizer mode is initialized by MEMORY_NORMAL_FAST and can be changed using setDefaultMode(int) method.


Version:
2.1
Author:
Gif4J Software - Java GIF image processing solutions

Field Summary
static int MEMORY_LOW_FAST
          fast low memory mode.
static int MEMORY_LOW_FAST_DITHER
          fast low memory mode + dithering.
static int MEMORY_LOW_OPTIMIZED
          optimized low memory mode.
static int MEMORY_LOW_OPTIMIZED_DITHER
          optimized low memory mode + dithering.
static int MEMORY_NORMAL_FAST
          fast normal memory mode.
static int MEMORY_NORMAL_FAST_DITHER
          fast normal memory mode + dithering.
static int MEMORY_NORMAL_OPTIMIZED
          optimized normal memory mode.
static int MEMORY_NORMAL_OPTIMIZED_DITHER
          optimized normal memory mode + dithering.
static int MEMORY_NORMAL_OPTIMIZED_DITHER_SOFT
          optimized normal memory mode + soft dithering.
 
Constructor Summary
Quantizer()
           
 
Method Summary
static java.awt.image.BufferedImage quantize(java.awt.image.BufferedImage source, int colorBitDepth)
          Quantize the specified image using the default mode.
static java.awt.image.BufferedImage quantize(java.awt.image.BufferedImage source, int colorBitDepth, boolean forceTransparency)
          Quantize the specified image with transparency forcing using the default mode.
static java.awt.image.BufferedImage quantize(int quantizerMode, java.awt.image.BufferedImage source, int colorBitDepth)
          Quantize the specified image using the specified quantizer mode.
static java.awt.image.BufferedImage quantize(int quantizerMode, java.awt.image.BufferedImage source, int colorBitDepth, boolean forceTransparency)
          Quantize the specified image with transparency forcing using the specified quantizer mode.
static void setDefaultMode(int quantizerMode)
          Set the default quantizer mode.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MEMORY_LOW_FAST

public static final int MEMORY_LOW_FAST
fast low memory mode. The fastest among modes.

See Also:
Constant Field Values

MEMORY_LOW_FAST_DITHER

public static final int MEMORY_LOW_FAST_DITHER
fast low memory mode + dithering.

See Also:
Constant Field Values

MEMORY_LOW_OPTIMIZED

public static final int MEMORY_LOW_OPTIMIZED
optimized low memory mode.

See Also:
Constant Field Values

MEMORY_LOW_OPTIMIZED_DITHER

public static final int MEMORY_LOW_OPTIMIZED_DITHER
optimized low memory mode + dithering.

See Also:
Constant Field Values

MEMORY_NORMAL_FAST

public static final int MEMORY_NORMAL_FAST
fast normal memory mode.

See Also:
Constant Field Values

MEMORY_NORMAL_FAST_DITHER

public static final int MEMORY_NORMAL_FAST_DITHER
fast normal memory mode + dithering.

See Also:
Constant Field Values

MEMORY_NORMAL_OPTIMIZED

public static final int MEMORY_NORMAL_OPTIMIZED
optimized normal memory mode.

See Also:
Constant Field Values

MEMORY_NORMAL_OPTIMIZED_DITHER

public static final int MEMORY_NORMAL_OPTIMIZED_DITHER
optimized normal memory mode + dithering.

See Also:
Constant Field Values

MEMORY_NORMAL_OPTIMIZED_DITHER_SOFT

public static final int MEMORY_NORMAL_OPTIMIZED_DITHER_SOFT
optimized normal memory mode + soft dithering.

See Also:
Constant Field Values
Constructor Detail

Quantizer

public Quantizer()
Method Detail

quantize

public static java.awt.image.BufferedImage quantize(java.awt.image.BufferedImage source,
                                                    int colorBitDepth)
Quantize the specified image using the default mode.

Parameters:
source - the image to quantize
colorBitDepth - desired color table bit depth. Should be between 2 and 16. To determine actual size of the color table, raise 2 to this parameter: for example, to quantize the specified image to 256 colors this parameter has to be equal to 8 (raise 2 to 8 = 256).
Returns:
quantized instance of BufferedImage
Throws:
java.lang.IllegalArgumentException - If color bit depth less than 2 or more than 16;
java.lang.NullPointerException - If source image is null

quantize

public static java.awt.image.BufferedImage quantize(java.awt.image.BufferedImage source,
                                                    int colorBitDepth,
                                                    boolean forceTransparency)
Quantize the specified image with transparency forcing using the default mode. "Force Transparency" parameter lets to receive quantized instance with alpha-channel (transparent) support even if the source image is opaque. It's useful if the result image should have an alpha-channel for the following processing. (For example, this feature is used by MorphingFilter sub-classes.)

Parameters:
source - the image to quantize
colorBitDepth - desired color table bit depth. Should be between 2 and 16. To determine actual size of the color table, raise 2 to this parameter: for example, to quantize the specified image to 256 colors this parameter has to be equal to 8 (raise 2 to 8 = 256).
forceTransparency - if true force transparency in returned BufferedImage instance
Returns:
quantized instance of BufferedImage
Throws:
java.lang.IllegalArgumentException - If color bit depth less than 2 or more than 16;
java.lang.NullPointerException - If source image is null

quantize

public static java.awt.image.BufferedImage quantize(int quantizerMode,
                                                    java.awt.image.BufferedImage source,
                                                    int colorBitDepth)
Quantize the specified image using the specified quantizer mode.

Parameters:
quantizerMode - one of the predefined quantizer modes: MEMORY_LOW_FAST, MEMORY_LOW_FAST_DITHER, MEMORY_LOW_OPTIMIZED, MEMORY_LOW_OPTIMIZED_DITHER, MEMORY_NORMAL_FAST, MEMORY_NORMAL_FAST_DITHER, MEMORY_NORMAL_OPTIMIZED, MEMORY_NORMAL_OPTIMIZED_DITHER
source - the specified image to quantize
colorBitDepth - desired color bit depth. Should be between 2 and 16. To determine actual size of the color table, raise 2 to this parameter: for example, to quantize the specified image to 256 colors this parameter has to be equal to 8 (raise 2 to 8 = 256).
Returns:
quantized instance of BufferedImage
Throws:
java.lang.IllegalArgumentException - If color bit depth less than 2 or more than 16;
java.lang.IllegalArgumentException - If unknown quantizer mode;
java.lang.NullPointerException - If source image is null

quantize

public static java.awt.image.BufferedImage quantize(int quantizerMode,
                                                    java.awt.image.BufferedImage source,
                                                    int colorBitDepth,
                                                    boolean forceTransparency)
Quantize the specified image with transparency forcing using the specified quantizer mode. "Force Transparency" parameter lets to receive quantized instance with alpha-channel (transparent) support even if the source image is opaque. It's useful if the result image should have an alpha-channel for the following processing. (For example, this feature is used by MorphingFilter sub-classes.)

Parameters:
quantizerMode - one of the predefined quantizer modes: MEMORY_LOW_FAST, MEMORY_LOW_FAST_DITHER, MEMORY_LOW_OPTIMIZED, MEMORY_LOW_OPTIMIZED_DITHER, MEMORY_NORMAL_FAST, MEMORY_NORMAL_FAST_DITHER, MEMORY_NORMAL_OPTIMIZED, MEMORY_NORMAL_OPTIMIZED_DITHER
source - the specified image to quantize
colorBitDepth - desired color table bit depth. Should be between 2 and 16. To determine actual size of the color table, raise 2 to this parameter: for example, to quantize the specified image to 256 colors this parameter has to be equal to 8 (raise 2 to 8 = 256).
forceTransparency - if true force transparency in returned BufferedImage instance
Returns:
quantized instance of BufferedImage
Throws:
java.lang.IllegalArgumentException - If color bit depth less than 2 or more than 16;
java.lang.IllegalArgumentException - If unknown quantizer mode;
java.lang.NullPointerException - If source image is null

setDefaultMode

public static void setDefaultMode(int quantizerMode)
Set the default quantizer mode.

Parameters:
quantizerMode - one of the predefined quantizer modes: MEMORY_LOW_FAST, MEMORY_LOW_FAST_DITHER, MEMORY_LOW_OPTIMIZED, MEMORY_LOW_OPTIMIZED_DITHER, MEMORY_NORMAL_FAST, MEMORY_NORMAL_FAST_DITHER, MEMORY_NORMAL_OPTIMIZED, MEMORY_NORMAL_OPTIMIZED_DITHER