IMAGE_COLOR_QUANT Function

Reference Guide > I–L Routines > IMAGE_COLOR_QUANT Function

Quantizes a 24-bit image to 8-bit pseudo-color.

note	If you have 64-bit PV-WAVE and need to read and write images up to 32-bits without constraints on data size, use the PHOTO OPI routines.

Usage

result = IMAGE_COLOR_QUANT(image[, n_colors])

Input Parameters

image—Either an image associative array with a 24-bit color image or a 3D byte array.

n_colors—(optional) An integer specifying the number of colors desired in the output pseudo-color image. This value must be greater than 0 and less than or equal to 256. (Default: !D.Table_Size)

Returned Value

result—The returned value depends upon whether the input was a 24-bit color image or a 3D byte array:

Image associative array—Returns an image associative array containing the color quantized (8-bit) pseudo-color image. On error, returns an image associative array with the status key set to < 0.

3D byte array—Returns a 2D byte array containing the color quantized (8-bit) pseudo-color image. On error, returns < 0.

Keywords

Colormap—Specifies a variable to hold the colormap of the quantized image. Colormap is a 3-by-n_colors byte array.

Dither—If set, Floyd-Steinberg dithering is used to quantize the 24-bit image.

Intleave—A scalar string indicating the type of interleaving of 3D image arrays. This keyword can only be used when the input image is a 3D byte array. If Intleave is not specified, the default interleaving method corresponds to the minimum dimension of the array, where p is the minimum dimension.

Valid strings and the corresponding interleaving methods are:

'image'—The 3D image array arrangement is (x, y, p) for p image-interleaved images of x-by-y.

'row'—The 3D image array arrangement is (x, p, y) for p row-interleaved images of x-by-y.

'pixel'—The input array arrangement is (p, x, y) for p pixel-interleaved images of x-by-y.

note	If the input image is an associative array, the interleaving method is found in the interleave field of the array.

Loadcmap—If set, the generated colormap is automatically loaded using TVLCT.

Quiet—Suppresses successive levels of error messages, depending on the integer value specified. This keyword accepts the same integer values used with the system variable !Quiet.

Discussion

The IMAGE_COLOR_QUANT function is useful for converting 24-bit images for display on 8-bit devices. It can also be used to compress the amount of information in the image to reduce the amount of storage space needed when the image is saved to a file.

note	The original 24-bit image cannot be reconstructed from the 8-bit quantized result.

The function quantizes the image using the median-cut algorithm. For information on the algorithm used in this function, refer to:

Paul Heckbert. “Color Image Quantization for Frame Buffer Display”, Siggraph ‘82 Proceedings, pp. 297-307.

Example 1

The first example uses an image associative array as input.

note	The filename used in this example is a UNIX specific filename, which must be modified for use on other platforms.

; Read in a 24-bit image-interleaved image.

chautauqua = IMAGE_READ(GETENV('RW_DIR') + $

   '/image-2_0/data/chautauqua24.tif')

; Convert the image to 8-bit pseudo-color.

chautauqua_8bit = IMAGE_COLOR_QUANT(chautauqua, 256)

; Display the 8-bit image.

IMAGE_DISPLAY, chautauqua_8bit

Example 2

This example reads 24-bit image data that has been stored in three separate image files—one red, one green, and one blue. Each file is read separately and then combined in one 3D array before being quantized and displayed.

The data used in the example comes from the red, green, and blue images of Boulder in the PV‑WAVE data directory.

imgx = 477

imgy = 512

red_img = BYTARR(imgx, imgy, /Nozero)

grn_img = BYTARR(imgx, imgy, /Nozero)

blu_img = BYTARR(imgx, imgy, /Nozero)

; Read the separate red, green, and blue image files.

OPENR, 1, !Data_Dir + 'boulder_red.img'

READU, 1, red_img

CLOSE, 1

OPENR, 1, !Data_Dir + 'boulder_grn.img'

READU, 1, grn_img

CLOSE, 1

OPENR, 1, !Data_Dir + 'boulder_blu.img'

READU, 1, blu_img

CLOSE, 1

; Combine the image files into a single 3D array.

boulder = BYTARR(imgx, imgy, 3, /Nozero)

boulder(*, *, 0) = red_img

boulder(*, *, 1) = grn_img

boulder(*, *, 2) = blu_img

; Convert the image to 8-bit pseudo-color.

boulder_8bit = IMAGE_COLOR_QUANT(boulder, 256, /Loadcmap)

; Display the 8-bit image.

WINDOW, Xsize=477, Ysize=512

TV, boulder_8bit