com.gif4j.quantizer
Class ExactQuantizer

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

public final class ExactQuantizer
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. Quantized BufferedImage instances have IndexColorModel as ColorModel (if number of colors <= 256) or DirectColorModel for number of colors more than 256.
Quantizer automatically detects the presence of alpha-channel (image transparency) and retains it unchangeable if number of colors more than 256 (result - DirectColorModel based BufferedImage instance) or converts Transparency.TRANSLUCENT transparency to Transparency.BITMASK transparency.
Please note, that GIF format support images with number of colors less than or equal to 256 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.


Since:
2.3
Version:
1.0
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
ExactQuantizer()
           
 
Method Summary
static java.awt.image.BufferedImage quantize(java.awt.image.BufferedImage source, int colorsNum)
          Quantize the specified image using the default mode.
static java.awt.image.BufferedImage quantize(java.awt.image.BufferedImage source, int colorsNum, 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 colorsNum)
          Quantize the specified image using the specified quantizer mode.
static java.awt.image.BufferedImage quantize(int quantizerMode, java.awt.image.BufferedImage source, int colorsNum, 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

ExactQuantizer

public ExactQuantizer()
Method Detail

quantize

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

Parameters:
source - the image to quantize
colorsNum - desired number of colors. Should be between 4 and 65536.
Returns:
quantized instance of BufferedImage
Throws:
java.lang.IllegalArgumentException - If desired number of colors less than 4 or more than 65536;
java.lang.NullPointerException - If source image is null

quantize

public static java.awt.image.BufferedImage quantize(java.awt.image.BufferedImage source,
                                                    int colorsNum,
                                                    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
colorsNum - desired number of colors. Should be between 4 and 65536.
forceTransparency - if true force transparency in returned BufferedImage instance
Returns:
quantized instance of BufferedImage
Throws:
java.lang.IllegalArgumentException - If desired number of colors less than 4 or more than 65536;
java.lang.NullPointerException - If source image is null

quantize

public static java.awt.image.BufferedImage quantize(int quantizerMode,
                                                    java.awt.image.BufferedImage source,
                                                    int colorsNum)
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
colorsNum - desired number of colors. Should be between 4 and 65536.
Returns:
quantized instance of BufferedImage
Throws:
java.lang.IllegalArgumentException - If desired number of colors less than 4 or more than 65536;
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 colorsNum,
                                                    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
colorsNum - desired number of colors. Should be between 4 and 65536.
forceTransparency - if true force transparency in returned BufferedImage instance
Returns:
quantized instance of BufferedImage
Throws:
java.lang.IllegalArgumentException - If desired number of colors less than 4 or more than 65536;
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