com.gif4j.quantizer
Class ExactQuantizer

java.lang.Object
  com.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.

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