WRITE_JPEG

The WRITE_JPEG procedure writes compressed images to files. JPEG (Joint Photographic Experts Group) is a standardized compression method for full-color and gray-scale images. This procedure is based in part on the work of the Independent JPEG Group.

As the Independent JPEG Group states, JPEG is intended for real-world scenes (such as digitized photographs). Line art, such as drawings or IDL plots, and other unrealistic images are not its strong suit. Note also that JPEG is a lossy compression scheme. That is, the output image is not identical to the input image. Hence you cannot use JPEG if you must have identical output bits. On typical images of real-world scenes, however, very good compression levels can be obtained with no visible change, and amazingly high compression levels are possible if you can tolerate a low-quality image. You can trade off output image quality against compressed file size by adjusting a compression parameter. Files are encoded in JFIF, the JPEG File Interchange Format; however, such files are usually called JPEG files.

If you need to store images in a format that uses lossless compression, consider using the WRITE_PNG procedure. This procedure writes a Portable Network Graphics (PNG) file using lossless compression with either 8 or 16 data bits per channel. To store 8-bit or 24-bit images without compression, consider using WRITE_BMP (for Microsoft Bitmap format files) or WRITE_TIFF (to write Tagged Image Format Files).

For a short technical introduction to the JPEG compression algorithm, see: Wallace, Gregory K. “The JPEG Still Picture Compression Standard”, Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.

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

Examples

The following command captures the contents of the current IDL graphics window and saves it to a JPEG file named test.jpg, using JPEG compression with a quality index of 25. The image is stored in bottom-to-top order:

WRITE_JPEG, 'test1.jpg', TVRD(), QUALITY=25

The following lines create an image in an IDL graphics window, read it from the window and write it as a TrueColor .jpg file in the temporary directory, then read the .jpg file and display it in the same graphics window:

; Save device settings and tell IDL to use a color table
DEVICE, GET_DECOMPOSED=old_decomposed
DEVICE, DECOMPOSED=0
LOADCT, 14
; Create an image and display it
IMAGE1 = DIST(300)
WINDOW, 1, XSIZE=300, YSIZE=300
TV, IMAGE1
; Write a bitmap file to the temporary directory
; Note the use of the TRUE keywords to TVRD and WRITE_JPEG
filename = FILEPATH('test.jpg', /TMP)
WRITE_JPEG, filename, TVRD(/TRUE), /TRUE
PRINT, 'File written to ', filename
; Read in the file
; Note the use of the TRUE keyword to READ_JPEG
READ_JPEG, filename, IMAGE2, /TRUE
; Display the IMAGE1 and IMAGE2 side by side
; Note the use of the TRUE keyword to TV
WINDOW, 1, XSIZE=600, YSIZE=300, $
   TITLE='Original (left) and Image read from file (right)'
TV, IMAGE1, 0
TV, IMAGE2, 1, /TRUE
; Restore device settings.
DEVICE, DECOMPOSED=old_decomposed

Syntax

WRITE_JPEG [, Filename], Image [, /ORDER] [, /PROGRESSIVE] [, QUALITY=value{0 to 100}] [, TRUE={1 | 2 | 3}] [, UNIT=lun]

Arguments

Filename

A string containing the name of file to be written in JFIF (JPEG) format. If this parameter is not present, the UNIT keyword must be specified.

Image

A byte array of either two or three dimensions, containing the image to be written. Grayscale images must have two dimensions. TrueColor images must have three dimensions with the index of the dimension that contains the color specified with the TRUE keyword.

Keywords

ORDER

JPEG/JFIF images are normally written in top-to-bottom order. If the image array is in the standard IDL order (i.e., from bottom-to-top) set ORDER to 0, its default value. If the image array is in top-to-bottom order, ORDER must be set to 1.

PROGRESSIVE

Set this keyword to write the image as a series of scans of increasing quality. When used with a slow communications link, a decoder can generate a low-quality image very quickly, and then improve its quality as more scans are received.

Not all JPEG applications can handle progressive JPEG files, and it is up the JPEG reader to progressively display the JPEG image. For example, IDL’s READ_JPEG routine ignores the progressive readout request and reads the entire image in at the first reading.

QUALITY

This keyword specifies the quality index, in the range of 0 (terrible) to 100 (excellent) for the JPEG file. The default value is 75, which corresponds to very good quality. Lower values of QUALITY produce higher compression ratios and smaller files.

TRUE

This keyword specifies the index, starting at 1, of the dimension over which the color is interleaved. For example, for an image that is pixel interleaved and has dimensions of (3, m, n), set TRUE to 1. Specify 2 for row-interleaved images (m, 3, n); and 3 for band-interleaved images (m, n, 3). If TRUE is not set, the image is assumed to have no interleaving (it is not a TrueColor image).

UNIT

This keyword designates the logical unit number of an already open file to receive the output, allowing multiple JFIF images per file or the embedding of JFIF images in other data files. If this keyword is used, 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 WRITE_JPEG.

Version History

Pre-4.0

Introduced