The COLOR_QUAN function quantizes a TrueColor 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 converting a decomposed color (TrueColor) image, which can contain a palette of up to 224 colors, into an 8-bit image along with red, green, and blue color vectors. This conversion may be useful if you need to:

  • display the image on a pseudo-color display where the number of available colors is limited to 256 or fewer
  • create an 8-bit image format file, such as GIF image.


One of two color quantization methods can be used:

  • Method 1 is a statistical method that attempts to find the N colors that most accurately represent the original color distribution. This algorithm uses a variation of the Median Cut Algorithm, described in “Color Image Quantization for Frame Buffer Display”, from Computer Graphics, Volume 16, Number 3 (July, 1982), Page 297. It repeatedly subdivides the color space into smaller and smaller rectangular boxes, until the requested number of colors are obtained.

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.

  • Method 2, selected by setting the keyword parameter CUBE, divides the three-dimensional color space into equal-volume cubes. Each color axis is divided into CUBE segments, resulting in CUBE3 volumes. The original input image is sampled to this color space using Floyd-Steinberg dithering, which distributes the quantization error to adjacent pixels.

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.


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

; Read in a TrueColor image.
file = FILEPATH('glowing_gas.jpg', $
   SUBDIRECTORY=['examples', 'data'])
READ_JPEG, file, image
; Tell IDL to use a maximum of 256 colors and load
; a greyscale color map.
; Create a quantized version of the image, using a
; maximum of 128 colors. Load the resulting color arrays
; into the current color table.
quantized_image=COLOR_QUAN(image, 1, r, g, b, COLORS=128)
TVLCT, r, g, b
; Display information about the original and
; quantized image arrays.
HELP, image, quantized_image
; Display the original TrueColor alongside the
; quantized image.
TV, image, 0, /TRUE
TV, quantized_image, 1
; Reset IDL to the original device setting
DEVICE, DECOMPOSED=orig_decomposed

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

quantized_image=COLOR_QUAN(image, 1, r, g, b, CUBE=6)

To export the quantized image to a GIF file:

WRITE_GIF, 'path/to/file', quantized_image, r, g, b


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


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

Keywords: [, COLORS=integer{2 to 256}] [, CUBE={2 | 3 | 4 | 5 | 6} | , GET_TRANSLATION=variable [, /MAP_ALL]] [, /DITHER] [, ERROR=variable] [, TRANSLATION=vector]

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.

Return Value

Returns a pseudo-color image composed of 2 to 256 colors.


Image_R, Image_G, Image_B

Arrays containing the red, green, and blue components of the decomposed TrueColor 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 TrueColor 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 be 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 CUBE3 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 23 = 8, to 63 = 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 TrueColor 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.

Version History

Pre 4.0


See Also