Quantization

Enumerations
enum	gdPaletteQuantizationMethod { GD_QUANT_DEFAULT = 0 , GD_QUANT_JQUANT = 1 , GD_QUANT_NEUQUANT = 2 , GD_QUANT_LIQ = 3 }

Functions
gdImagePtr	gdImageNeuQuant (gdImagePtr im, const int max_color, int sample_factor)
	Creates a new palette image from a truecolor image.
int	gdImageTrueColorToPaletteSetMethod (gdImagePtr im, int method, int speed)
	Selects quantization method used for subsequent gdImageTrueColorToPalette calls.
void	gdImageTrueColorToPaletteSetQuality (gdImagePtr im, int min_quality, int max_quality)
	Sets the quality range for subsequent gdImageTrueColorToPalette calls.
gdImagePtr	gdImageCreatePaletteFromTrueColor (gdImagePtr im, int ditherFlag, int colorsWanted)
	Converts a truecolor image to a palette-based image.
int	gdImageTrueColorToPalette (gdImagePtr im, int ditherFlag, int colorsWanted)
	Converts a truecolor image to a palette image.
int	gdImagePaletteToTrueColor (gdImagePtr src)
	Converts a palette-based image to a truecolor image.

Detailed Description

Enumeration Type Documentation

gdPaletteQuantizationMethod

enum gdPaletteQuantizationMethod

Note that GD_QUANT_JQUANT does not retain the alpha channel, and GD_QUANT_NEUQUANT does not support dithering.

See also

gdImageTrueColorToPaletteSetMethod

Enumerator
GD_QUANT_DEFAULT	Default quantization method
GD_QUANT_JQUANT	libjpeg's old median cut
GD_QUANT_NEUQUANT	NeuQuant - approximation using Kohonen neural network
GD_QUANT_LIQ	libimagequant combination aiming for highest quality

Function Documentation

gdImageCreatePaletteFromTrueColor()

gdImagePtr gdImageCreatePaletteFromTrueColor	(	gdImagePtr	im,
		int	ditherFlag,
		int	colorsWanted
	)

Converts a truecolor image to a palette-based image.

This function converts a truecolor image to a palette-based image using a high-quality two-pass quantization routine which attempts to preserve alpha channel information as well as R/G/B color information when creating a palette. If ditherFlag is set, the image will be dithered to approximate colors better, at the expense of some obvious "speckling." colorsWanted can be anything up to 256. If the original source image includes photographic information or anything that came out of a JPEG, 256 is strongly recommended.

Better yet, don't use these function – write real truecolor PNGs and JPEGs. The disk space gain of conversion to palette is not great (for small images it can be negative) and the quality loss is ugly.

DIFFERENCES: gdImageCreatePaletteFromTrueColor creates and returns a new image. gdImageTrueColorToPalette modifies an existing image, and the truecolor pixels are discarded.

Parameters

im	The image.
dither	Whether dithering should be applied.
colorsWanted	The number of desired palette entries.

Returns

a newly created palette image on success, NULL on failure.

gdImageNeuQuant()

gdImagePtr gdImageNeuQuant	(	gdImagePtr	im,
		const int	max_color,
		int	sample_factor
	)

Creates a new palette image from a truecolor image.

This is the same as calling gdImageCreatePaletteFromTrueColor with the quantization method GD_QUANT_NEUQUANT.

Parameters

im	- The image.
max_color	- The number of desired palette entries.
sample_factor	- The quantization precision between 1 (highest quality) and 10 (fastest).

Returns

A newly create palette image; NULL on failure.

gdImagePaletteToTrueColor()

int gdImagePaletteToTrueColor

(

gdImagePtr

src

)

Converts a palette-based image to a truecolor image.

This function converts a palette-based image to a truecolor image. The palette is discarded, and the image is converted to truecolor. The alpha channel information is preserved.

Parameters

src	The source image.

Returns

Non-zero if the conversion succeeded, zero otherwise.

gdImageTrueColorToPalette()

int gdImageTrueColorToPalette	(	gdImagePtr	im,
		int	ditherFlag,
		int	colorsWanted
	)

Converts a truecolor image to a palette image.

Parameters

im	The image.
dither	Whether dithering should be applied.
colorsWanted	The number of desired palette entries.

Returns

Non-zero if the conversion succeeded, zero otherwise.

See also

gdImageCreatePaletteFromTrueColor gdImageTrueColorToPaletteSetMethod gdImagePaletteToTrueColor

gdImageTrueColorToPaletteSetMethod()

int gdImageTrueColorToPaletteSetMethod	(	gdImagePtr	im,
		int	method,
		int	speed
	)

Selects quantization method used for subsequent gdImageTrueColorToPalette calls.

See gdPaletteQuantizationMethod enum (e.g. GD_QUANT_NEUQUANT, GD_QUANT_LIQ). Speed is from 1 (highest quality) to 10 (fastest). Speed 0 selects method-specific default (recommended).

Parameters

im	The image to set the quantization method for.
method	The quantization method to use.
speed	The speed/quality tradeoff for the selected method.

Returns

FALSE if the given method is invalid or not available.

gdImageTrueColorToPaletteSetQuality()

void gdImageTrueColorToPaletteSetQuality	(	gdImagePtr	im,
		int	min_quality,
		int	max_quality
	)

Sets the quality range for subsequent gdImageTrueColorToPalette calls.

Chooses quality range that subsequent call to gdImageTrueColorToPalette will aim for. Min and max quality is in range 1-100 (1 = ugly, 100 = perfect). Max must be higher than min. If palette cannot represent image with at least min_quality, then image will remain true-color. If palette can represent image with quality better than max_quality, then lower number of colors will be used. This function has effect only when GD_QUANT_LIQ method has been selected and the source image is true-color.

Parameters

im	The image.
min_quality	The minimum quality in range 1-100 (1 = ugly, 100 = perfect). If the palette cannot represent the image with at least min_quality, then no conversion is done.
max_quality	The maximum quality in range 1-100 (1 = ugly, 100 = perfect), which must be higher than the min_quality. If the palette can represent the image with a quality better than max_quality, then fewer colors than requested will be used.