READ_JPEG

The READ_JPEG procedure reads JPEG (Joint Photographic Experts Group) format compressed images from files or memory. JPEG is a standardized compression method for full-color and gray-scale images. This procedure reads JFIF, the JPEG File Interchange Format, including those produced by WRITE_JPEG. Such files are usually called JPEG files

READ_JPEG can optionally quantize TrueColor images contained in files to a pseudo-color palette with a specified number of colors, and with optional color dithering.

This procedure is based in part on the work of the Independent JPEG Group. For a brief explanation of JPEG, see WRITE_JPEG.

Note: All JPEG files consist of byte data. Input data is converted to bytes before being written to a JPEG file.

Note: To find information about a potential JPEG file before trying to read its data, use the QUERY_JPEG function.

Examples

; Read a JPEG grayscale image:

READ_JPEG, 'test.jpg', a

; Display the image:

TV, a

; Read and display a JPEG TrueColor image on a TrueColor display:

READ_JPEG, 'test.jpg', a, TRUE=1

; Display the image returned with pixel interleaving

; (i.e., with dimensions 3, m, n):

TV, a, TRUE=1

Read the image, setting the number of colors to be quantized to the maximum number of available colors.

; Read a JPEG TrueColor image on an 8-bit pseudo-color display:

READ_JPEG, 'test.jpg', a, ctable, COLORS=!D.N_COLORS-1

; Display the image:

TV, a

; Load the quantized color table:

TVLCT, ctable

We could have also included the TWO_PASS_QUANTIZE and DITHER keywords to improve the image’s appearance.

Using the BUFFER keyword.

; Initialize buffer:

buff = 0

OPENR, 1, 'images.jpg'

; Process each image:

FOR i=1, nimages DO BEGIN

   ; Read next image:

   READ_JPEG, UNIT=1, BUFFER=buff, a

   ; Display the image:

    TV, a

ENDFOR

; Done:

CLOSE, 1

Syntax

READ_JPEG [, Filename], Image [, Colortable] [, BUFFER=variable] [, COLORS=value{8 to 256}] [, DITHER={0 | 1 | 2}] [, /GRAYSCALE] [, /ORDER] [, TRUE={1 | 2 | 3}] [, UNIT=lun][, /TWO_PASS_QUANTIZE]

Arguments

Filename

A scalar string specifying the full pathname of the JFIF format (JPEG) file to be read. If this parameter is not present, the UNIT and/or the BUFFER keywords must be specified.

Image

A named variable that will contain the image data read from the file.

Colortable

A named variable that will contain a colormap created by color-quantizing the TrueColor image being read. On completion, this variable contains a byte array with dimensions (nColors, 3), where nColors is derived from the value of the COLORS keyword. If this argument is not present, or if the specified JPEG image is grayscale, no color-quantization is performed.

Keywords

BUFFER

Set this keyword to a named variable that is used for a buffer. A buffer variable need only be supplied when reading multiple images per file. Initialize the buffer variable to empty by setting it to 0.

COLORS

If the image file contains a TrueColor image that is to be displayed on an indexed color destination, set COLORS to the desired number of colors to be quantized. COLORS can be set to a value from 8 to 256. The DITHER and TWO_PASS_QUANTIZE keywords affect the method, speed, and quality of the color quantization. These keywords have no effect if the file contains a grayscale image.

DITHER

Set this keyword to use dithering with color quantization (i.e., if the COLORS keyword is in use). Dithering is a method that distributes the color quantization error to surrounding pixels, to achieve higher-quality results. Set the DITHER keyword to one of the following values:

0 = No dithering. Images are read quickly, but quality is low.
1 = Floyd-Steinberg dithering. This method is relatively slow, but produces the highest quality results. This is the default behavior.
2 = Ordered dithering. This method is faster than Floyd-Steinberg dithering, but produces lower quality results.

GRAYSCALE

Set this keyword to return a monochrome (grayscale) image, regardless of whether the file contains an RGB or grayscale image.

ORDER

JPEG/JFIF images are normally written in top-to-bottom order. If the image is to be stored into the Image array in the standard IDL order (from bottom-to-top) set ORDER to 0. This is the default. If the image array is to be top-to-bottom order, set ORDER to 1.

TRUE

Use this keyword to specify the index of the dimension for color interleaving when reading a TrueColor image. The default is 1, for pixel interleaving, (3, m, n). A value of 2 indicates line interleaving (m, 3, n), and 3 indicates band interleaving, (m, n, 3).

TWO_PASS_QUANTIZE

Set this keyword to use a two-pass color quantization method when quantization is in effect (i.e., the COLORS keyword is in use). This method requires more memory and time, but produces superior results to the default one-pass quantization method.

UNIT

This keyword can be used to designate the logical unit number of an already open JFIF file, allowing the reading of multiple images per file or the embedding of JFIF images in other data files. When using this keyword, Filename should not be specified.

Note: When opening a file intended for use with the UNIT keyword, if the filename does not end in .jpg, or .jpeg, you must specify the STDIO keyword to OPEN in order for the file to be compatible with READ_JPEG.

Version History

Pre-4.0

Introduced