The WRITE_GIF procedure writes an image and its color table vectors to a Graphics Interchange Format (GIF) file.

WRITE_GIF produces 8-bit non-interlaced GIF files.

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

Example


The following command captures the contents of the current IDL graphics window and saves it to a GIF file named test.gif. Note that this works only on a PseudoColor (8-bit) display:

WRITE_GIF, 'test.gif', TVRD()

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

   
  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
  filename = FILEPATH('test.gif', /TMP)
   
  ;WRITE_GIF produces 8-bit non-interlaced GIF files, therefore needs to be bytscl()
  WRITE_GIF, filename,  bytscl(image1)
  PRINT, 'File written to ', filename
   
  ; Read in the bitmap file
  READ_GIF, filename, image2
   
  ; Display the IMAGE1 and IMAGE2 side by side
  WINDOW, 1, XSIZE=600, YSIZE=300, $
  TITLE = 'Original (left) and Image read from file (right)'
  TV, IMAGE1, 0
  TV, IMAGE2, 1

Syntax


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

Arguments


Filename

A scalar string containing the full pathname of the GIF file to write.

Image

The array to write into the new GIF file.

R, G, B

The Red, Green, and Blue color vectors to be written with to the GIF file. If R, G, B values are not provided, the last color table established using LOADCT is saved, and the table is padded to 256 entries. If no color table has been established, WRITE_GIF calls LOADCT to load the grayscale entry (table 0). For GIF files with multiple images, when writing the second and subsequent images, if R, G, B are present then they will be written into the local color map for the current image.

Keywords


BACKGROUND_COLOR

Set this keyword to a byte value giving the index within the global color table to be designated as the background. The default value is 0.

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 being written. If the CLOSE keyword is specified, nothing is written to the file, and all other parameters are ignored.

DELAY_TIME

For multi-image GIF files, set this keyword to an integer giving the delay in hundredths (1/100) of a second after the decoder displays the current image. This keyword can be set to a different value for each image within the file.

DISPOSAL_METHOD

For multi-image GIF files, set this keyword to an integer giving the method that the decoder should use for disposing the current image after display. 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.

This keyword can be set to a different value for each image within the file.

MULTIPLE

Set this keyword to write multiple images to a file. Each call to WRITE_GIF writes the next image, with the file remaining open between calls. The Filename argument is ignored after the first call, but must be supplied. All images written to a GIF file must be the same size.

Note: After using MULTIPLE, you should always issue a final call to WRITE_GIF with the CLOSE keyword and no other parameters or data except the Filename.

REPEAT_COUNT

For multi-image GIF files, set this keyword to an integer giving the number of times that the decoder should repeat the animation. Set this keyword to zero to repeat an infinite number of times.

Note: This keyword uses a non-standard Netscape extension and may ignored or interpreted differently by certain applications and browsers. For example, setting REPEAT_COUNT=1 may give either one or two cycles of the animation.

TRANSPARENT

Set this keyword to a byte value giving the index within the color table to be designated as the transparent color. If this keyword is not present or is set to -1 then no transparent index is written. This keyword can be set to a different value for each image within the file.

USER_INPUT

Set this keyword to a flag indicating whether the decoder should require user input before continuing processing. The nature of the user input is determined by the application (carriage return, mouse button click, etc.). When DELAY_TIME is used and USER_INPUT is set, the decoder should continue processing when user input is received or when the delay time expires, whichever occurs first. This keyword may be set to 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


READ_GIF, WRITE_JPEG, QUERY_* Routines