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 format files (often called "JPEG" files), including those produced by WRITE_JPEG.

READ_JPEG can optionally quantize true-color 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 .

Calling Sequence

READ_JPEG, [Filename,] Image [,Colortable]



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.


A named variable to contain the image data read from the file.


A named variable to contain the colormap, when reading a true-color image that is to be quantized. On completion, this variable contains a byte array with dimensions (NCOLORS, 3). This argument is filled only if the image is color quantized (refer to the COLORS keyword).



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.

buff = 0 ; Initialize buffer.

OPENR, 1, 'images.jpg', /STREAM

FOR i=1, nimages DO BEGIN ; Process each image.

    READ_JPEG, UNIT=1, BUFFER=buff, a
; Read next ; image.

    TV, a ; Display the image.


CLOSE, 1 ; Done.


If the image file contains a true-color 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.


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 with quality is low.

1 Floyd-Steinberg dithering. This method 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.


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


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.


Use this keyword to specify the index of the dimension for color interleaving when reading a true-color 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).


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.


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.

READ_JPEG buffers its input data. To read multiple images per file, use the BUFFER keyword. When using VMS, open the file with the /STREAM keyword.


READ_JPEG, 'test.jpg', a ; Read a JPEG grayscale image.

TV, a ; Display the image.

READ_JPEG, 'test.jpg', a, TRUE=1 ; Read and display a JPEG true-color image on a true-color display.

TV, a, TRUE=1 ; Display the image returned with pixel interleaving (i.e., with dimensions 3, m, n).

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

READ_JPEG, 'test.jpg', a, ctable, COLORS=!D.N_COLORS-1
; Read a JPEG true-color image on an 8-bit pseudo-color display.

TV, a ; Display the image.

TVLCT, ctable ; Load the quantized colortable.

See Also