COLOR_QUAN

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 displaying decomposed, TrueColor images, that contain a palette of up to 2²⁴ colors, on pseudo-color displays that can only display 256 (or fewer) simultaneous colors.

Using COLOR_QUAN

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 CUBE³ 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.

Syntax

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

Arguments

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.

Image

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

Dim

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.

Keywords

COLORS

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.

CUBE

If this keyword is set, the color space is divided into CUBE³ 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³= 8, to 6³= 216 output colors. If this keyword is set, the COLORS, DITHER, and ERROR keywords are ignored.

DITHER

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

ERROR

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.

GET_TRANSLATION

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.

MAP_ALL

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.

TRANSLATION

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.

Examples

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

;Open an input file:  
OPENR, unit, 'XXX.DAT', /GET_LUN  
  
;Dimensions of the input image:  
a = BYTARR(512, 3, 480, /NOZERO)  
  
;Read the image:  
READU, unit, a  
  
;Close the file:  
FREE LUN, unit  
  
;Show the quantized image. The 2 indicates that the colors are  
;interleaved by row:  
TV, COLOR_QUAN(a, 2, r, g, b, COLORS=128)  
  
;Load the new palette:  
TVLCT, r, g, b

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)

Converting RGB Images to Indexed Images

Although it is a relatively simple process to convert an RGB image to a grayscale image, the process needed to convert an RGB image to an indexed image is more complex. This process is more complex because the millions of possible colors provided by an RGB image must be decomposed into the 256 colors used by an indexed image. IDL's COLOR_QUAN function may be used to perform this process.

The following example shows how to use the COLOR_QUAN function to convert an RGB image to an indexed image. The elev_t.jpg file contains a pixel interleaved RGB image, which has its own color information. This example converts the image to an indexed image with an associated color table. Complete the following steps for a detailed description of the process.

Example Code
See rgbtoindexed.pro in the examples/doc/image subdirectory of the IDL installation directory for code that duplicates this example.

Determine the path to the elev_t.jpg file:

elev_tFile = FILEPATH('elev_t.jpg', $  
   SUBDIRECTORY = ['examples', 'data'])

Import the image from the elev_t.jpg file into IDL:

READ_JPEG, elev_tFile, elev_tImage

Determine the size of the imported image:

elev_tSize = SIZE(elev_tImage, /DIMENSIONS)

If you are running IDL on a TrueColor display, set the DECOMPOSED keyword to the DEVICE command to one before your first RGB image is displayed within an IDL session or program.

DEVICE, DECOMPOSED = 1

Initialize the display:

WINDOW, 0, TITLE = 'elev_t.jpg', $  
   XSIZE = elev_tSize[1], YSIZE = elev_tSize[2]

Display the imported image:

TV, elev_tImage, TRUE = 1

The following figure shows the original RGB image.

Figure 3-19: Example of an RGB Image

Figure 3-19: Example of an RGB Image

Note
If you are running IDL on a PseudoColor display, the RGB image will not be displayed correctly. A PseudoColor display only allows the display of indexed images. You can change the RGB image to an indexed image with the COLOR_QUAN routine. An example of this method is shown in this section.

The RGB image is converted to an indexed image with the COLOR_QUAN routine, but the DECOMPOSED keyword to the DEVICE command must be set to zero (for TrueColor displays) before using COLOR_QUAN because it is a color table related routine. See COLOR_QUAN for more information.

Note
COLOR_QUAN may result in some loss of color information since it quantizes the image to a fixed number of colors (stored in the color table).

If you are running IDL on a TrueColor display, set the DECOMPOSED keyword to the DEVICE command to zero before your first color table related routine is used within an IDL session or program.

DEVICE, DECOMPOSED = 0

Convert the RGB image to an indexed image with an associated color table:

imageIndexed = COLOR_QUAN(elev_tImage, 1, red, green, $  
   blue)

Export the resulting indexed image and its associated color table to a PNG file:

WRITE_PNG, 'elev_t.png', imageIndexed, red, green, blue

Version History


Pre 4.0	Introduced