PHOTO_COLOR_QUANT Function

Reference Guide > P Routines > PHOTO_COLOR_QUANT Function

Quantizes a 24-bit image or LIST of images to 8-bit pseudo color.

note	The PHOTO routines are only available on 64-bit PV-WAVE.

Usage

result = PHOTO_COLOR_QUANT(image[, n_colors])

Input Parameters

image — Either an image associative array, a list of image associative arrays, or a 3D byte array containing a 24-bit color image.

n_colors — (optional) An integer specifying the number of colors to quantize the image to. (Default: !D.Table_Size)

Returned Value

result — The returned value depends upon the input:

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.

List of image associative arrays — Returns a list of image associative arrays 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 color map of the generated 8-bit image. Colormap is a 3-by-n_colors byte array.

note	Colormap is ignored if the input is a list of image associative arrays.

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

Intleave — A scalar string used to resolve ambiguities when automatically determining the type of interleaving of 3D pixel arrays. This keyword is only used when the input image is a 3D byte array.

Interleaving is determined by the following steps:

1. Find the dimension of size '3' in the pixel array. If two or more exist it is ambiguous and requires the Intleave keyword.

2. If no dimension of size '3' exists in the pixel array, use the minimum dimension size as the color channel. If two or more dimensions have the same minimum size then it is ambiguous and requires the Intleave keyword.

Valid strings and the corresponding interleaving methods are:

'image' or 'plane' — The RGB pixel array arrangement is (x, y, 3) for 3 image-interleaved channels of x-by-y pixels.

'row' or 'line' — The RGB pixel array arrangement is (x, 3, y) for 3 row-interleaved channels of x-by-y pixels.

'pixel' or 'none' — The RGB pixel array arrangement is (3, x, y) for 3 pixel-interleaved channels of x-by-y pixels.

note	If the input image is a list of image associative arrays, the interleaving method is found in the interleave field of the first image associative array.

Loadcmap — If set, the generated color map is automatically loaded using the TVLCT Procedure.

note	If the input image is a list of image associative arrays the generated colormap from the last image is loaded.

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 PHOTO_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 = PHOTO_READ(GETENV('RW_DIR') + $

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

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

chautauqua_8bit = PHOTO_COLOR_QUANT(chautauqua, 256)

; Display the 8-bit image.

PHOTO_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 = PHOTO_COLOR_QUANT(boulder, 256, /Loadcmap)

; Display the 8-bit image.

WINDOW, Xsize=477, Ysize=512

TV, boulder_8bit