Routines (alphabetical) > Routines: R > READ_GIF

# READ_GIF

The READ_GIF procedure reads the contents of a GIF format image file and returns the image and color table vectors (if present) in the form of IDL variables. Only 8-bit images are supported.

This routine is written in the IDL language. Its source code can be found in the file `read_gif.pro` in the `lib` subdirectory of the IDL distribution.

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

## Example

To open and read the GIF image file named `foo.gif` in the current directory, store the image in the variable `image1.`

; Store the color vectors in the variables R, G, and B:

READ_GIF, 'foo.gif', image1, R, G, B

; Load the new color table and display the image:

TVLCT, R, G, B

TV, image1

## Syntax

READ_GIF, Filename, Image [, R, G, B] [, BACKGROUND_COLOR=variable] [, /CLOSE] [, DELAY_TIME=variable] [, DISPOSAL_METHOD=variable] [, /MULTIPLE] [, REPEAT_COUNT=variable] [, TRANSPARENT=value] [, USER_INPUT=variable]

## Arguments

### Filename

A scalar string specifying the full path name of the image file to read.

### Image

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

### R, G, B

Named variables that will contain the Red, Green, and Blue color vectors, if the rasterfile contains colormaps. For GIF files with multiple images, when reading the second and subsequent images, R, G, and B are not returned unless there is a local color table for that image.

## Keywords

### BACKGROUND_COLOR

Set this keyword to a named variable that will contain the index of the background color within the global color table.

### CLOSE

Set this keyword to close any open files. The CLOSE keyword is only useful if a file containing multiple images (as specified by the MULTIPLE keyword) is in use. Note that you do not need to specify the normal arguments to READ_GIF (Filename, Image, etc.) when using this keyword.

### DELAY_TIME

Set this keyword to a named variable that will contain the delay in hundredths (1/100) of a second that the decoder should wait after displaying the current image. If the delay time is not defined in the file, a value of 0 will be returned. There can be a different value for each image within the file.

### DISPOSAL_METHOD

Set this keyword to a named variable that will contain the disposal method that the decoder should use after displaying the current image. Possible values are:

0 | No disposal specified. The decoder is not required to take any action.
1 | Do not dispose. The graphic is to be left in place.
2 | Restore to background color. The area used by the graphic must be restored to the background color.
3 | Restore to previous. The decoder is required to restore the area overwritten by the graphic with what was there prior to rendering the graphic.

There can be a different value for each image within the file.

### MULTIPLE

Set this keyword to read files that contain multiple images. Each call to READ_GIF returns the next image, with the file remaining open between calls. The Filename argument is ignored and may be omitted after the first call. Reading past the last image returns a scalar value of -1 in the variable specified in the Image argument, and closes the file.

### REPEAT_COUNT

Set this keyword to a named variable that will contain the repeat count for the animation within the file. A repeat count of zero indicates an infinite repeat. If the repeat count is not defined within the file then a value of -1 is returned.

### TRANSPARENT

Set this keyword to a named variable that will contain a byte value giving the index within the color table to be designated as the transparent color. If there is no transparency, then a value of -1 is returned. There can be a different value for each image within the file.

### USER_INPUT

Set this keyword to a named variable that will contain the user input flag for the current image. A value of 0 indicates that no user input should be required, while a value of 1 indicates that the application should wait before continuing processing. The nature of the user input is determined by the application (carriage return, mouse button click, etc.). When both DELAY_TIME and USER_INPUT are present, the decoder should continue processing when user input is received or when the delay time expires, whichever occurs first. For multiple images there may be a different value for each image within the file.

## Version History

Pre-4.0 | Introduced
6.4 | Added BACKGROUND_COLOR, DELAY_TIME, DISPOSAL_METHOD, REPEAT_COUNT, TRANSPARENT, and USER_INPUT keywords

## See Also

IOPEN, WRITE_GIF, QUERY_GIF