The COLOR_QUAN function quantizes a true-color image and returns a pseudo-color image and palette to display the image on standard pseudo-color displays. The output image and palette can have from 2 to 256 colors.

COLOR_QUAN solves the general problem of accurately displaying decomposed, true-color images, that contain a palette of up to 2 24 colors, on pseudo-color displays that can only display 256 (or fewer) simultaneous colors.

One of two color quantization methods can be used:

The original colors are then mapped to the nearest output color, and the original image is resampled to the new palette with optional Floyd-Steinberg color dithering. The resulting pseudo-color image and palette are usually a good approximation of the original image.

The number of colors in the output palette defaults to the number of colors supported by the currently-selected graphics output device. The number of colors can also be specified by the COLOR keyword parameter.

The CUBE method has the advantage that the color tables it produces are independent of the input image, so that multiple quantized images can be viewed simultaneously. The statistical method usually provides a better-looking result and a smaller global error.

COLOR_QUAN can use the same color mapping for a series of images. See the descriptions of the GET_TRANSLATION, MAP_ALL, and TRANSLATION keywords, below.

Calling Sequence

Result = COLOR_QUAN( Image_R, Image_G, Image_B, R, G, B )


Result = COLOR_QUAN( Image, Dim, R, G, B )

Note that the input image parameter can be passed as either three, separate color-component arrays ( Image_R , Image_G , Image_B ) or as a three-dimensional array containing all three components, Image , and a scalar, Dim , indicating the dimension over which the colors are interleaved.


Image_R, Image_G, Image_B

Arrays containing the red, green, and blue components of the decomposed true-color image. For best results, the input image(s) should be scaled to the range of 0 to 255.


A three-dimensional array containing all three components of the true-color image.


A scalar that indicates the method of color interleaving in the Image parameter. A value of 1 indicates interleaving by pixel: (3, n , m ). A value of 2 indicates interleaving by row: ( n , 3, m ). A value of 3 indicates interleaving by image: ( n , m , 3).

R, G, B

Three output byte arrays containing the red, green, and blue components of the output palette.



The number of colors in the output palette. This value must at least 2 and not greater than 256. The default is the number of colors supported by the current graphics output device.


If this keyword is set, the color space is divided into CUBE 3 volumes, to which the input image is quantized. This result is always Floyd-Steinberg dithered. The value of CUBE can range from 2 to 6; providing from 2 3 = 8, to 6 3 = 216 output colors. If this keyword is set, the COLORS, DITHER, and ERROR keywords are ignored.


Set this keyword to dither the output image. Dithering can improve the appearance of the output image, especially when using relatively few colors.


Set this optional keyword to a named variable. A measure of the quantization error is returned. This error is proportional to the square of the Euclidean distance, in RGB space, between corresponding colors in the original and output images.


Set this keyword to a named variable in which the mapping between the original RGB triples (in the true-color image) and the resulting pseudo-color indices is returned as a vector. Do not use this keyword if CUBE is set.


Set this keyword to establish a mapping for all possible RGB triples into pseudo-color indices. Set this keyword only if GET_TRANSLATION is also present. Note that mapping all possible colors requires more compute time and slightly degrades the quality of the resultant color matching.


Set this keyword to a vector of translation indices obtained by a previous call to COLOR_QUAN using the GET_TRANSLATION keyword. The resulting image is quantized using this vector.


The following code segment reads a true-color, row interleaved, image from a disk file, and displays it on the current graphics display, using a palette of 128 colors:

OPENR, unit, 'XXX.DAT', /GET_LUN ; Open an input file.

a = BYTARR(512, 3, 480) ; Dimensions of the input image.

READU, unit, a ; Read the image.

FREE LUN, unit ; Close the file.

TV, COLOR_QUAN(a, 2, r, g, b, COLORS=128) ; Show the quantized image. The 2 indicates that the colors are interleaved by row.

TVLCT, r, g, b ; Load the new palette.

To quantize the image into 216 equal-volume color cubes, replace the call to COLOR_QUAN with the following:

TV, COLOR_QUAN(a, 2, r, g, b, CUBE=6)

See Also