; $Id: query_gif.pro,v 1.2 1999/01/16 01:24:55 scottm Exp $
;
; Copyright (c) 1993-1999, Research Systems, Inc.  All rights reserved.
;       Unauthorized reproduction prohibited.

FUNCTION QUERY_GIF, FILE, INFO, IMAGE_INDEX=I
;
;+
; NAME:
;   QUERY_GIF
;
; PURPOSE:
;   Read the header of a GIF format image file and return a structure
;   containing information about the image.
;
; CATEGORY:
;   Input/Output.
;
; CALLING SEQUENCE:
;   result = QUERY_GIF(File, Info)
;
; INPUTS:
;   File:   Scalar string giving the name of the GIF file to query.
;
; Keyword Inputs:
;   IMAGE_INDEX:  For some image query functions this keyword can be used
;       to specify for which image in a multi-image file the information
;       should be returned.  For QUERY_GIF this keyword is ignored.
;
; OUTPUTS:
;   Result is a long with the value of 1 if the query was successful (and the
;   file type was correct) or 0 on failure.  The return status will indicate
;   failure for files that contain formats that are not supported by the
;   corresponding READ_ routine, even though the file may be valid outside
;   the IDL environment.
;
;   Info:   An anonymous structure containing information about the image.
;       This structure is valid only when the return value of the function
;       is 1.  The Info structure for all query routines has the following
;       fields:
;
;           Field       IDL data type   Description
;           -----       -------------   -----------
;           CHANNELS    Long            Number of samples per pixel
;           DIMENSIONS  2-D long array  Size of the image in pixels
;           HAS_PALETTE Integer         True if a palette is present
;           NUM_IMAGES  Long            Number of images in the file
;           IMAGE_INDEX Long            Image number for this struct
;           PIXEL_TYPE  Integer         IDL basic type code for a pixel sample
;           TYPE        String          String identifying the file format
;
; RESTRICTIONS:
;   This routine only retrieves information on the first image in a file
;   (the format allows many). Local colormaps are not supported.
;   Only 8 bit images are supported.
;
;   The Graphics Interchange Format(c) is the Copyright property
;   of CompuServ Incorporated.  GIF(sm) is a Service Mark property of
;   CompuServ Incorporated.
;
; EXAMPLE:
;   To retrieve information from the GIF image file named "foo.gif"
;   in the current directory, enter:
;
;       result = QUERY_GIF("foo.gif", info)
;       IF (result GT 0) THEN BEGIN
;           HELP, /STRUCT, info
;       ENDIF ELSE BEGIN
;           PRINT, 'GIF file not found or file is not a valid GIF format.'
;       ENDELSE
;
; MODIFICATION HISTORY:
;   Written June 1998, ACY
;
;-
;

; Set up error handling
CATCH, errorStatus
if errorStatus ne 0 then begin
    if N_ELEMENTS(unit) gt 0 then FREE_LUN, unit
    RETURN, 0L
endif

; Define the GIF header
header   = {     magic:bytarr(6),                $
        width_lo:0b, width_hi:0b,           $
        height_lo:0b, height_hi:0b,         $
        screen_info:0b, background:0b, reserved:0b }

OPENR, unit, file, /GET_LUN, /BLOCK

READU, unit, header      ;Read gif header

FREE_LUN, unit

;   Check Magic in header: GIF87a or GIF89a.
gif = STRING(header.magic[0:2])
vers = STRING(header.magic[3:5])

;File is not valid a GIF file.
if gif ne 'GIF' then RETURN, 0L

;GIF Version incompatible with IDL
if vers ne '87a' and vers ne '89a' then RETURN, 0L

width   = header.width_hi * 256 + header.width_lo
height  = header.height_hi * 256 + header.height_lo
bits_per_pixel  = (header.screen_info AND 'F'X) + 1

; Define the info structure after error returns so that
; info argument stays undefined in error cases.
info = {CHANNELS:       0L, $
        DIMENSIONS:     [0L,0], $
        HAS_PALETTE:    0, $
        NUM_IMAGES:     0L, $
        IMAGE_INDEX:    0L, $
        PIXEL_TYPE:     0, $
        TYPE:           '' $
        }

;   Fill in the info structure
info.CHANNELS =     bits_per_pixel / 8
info.DIMENSIONS =   [width, height]
info.HAS_PALETTE =  ((header.screen_info and '80'X) ne 0)
info.NUM_IMAGES =   1       ; only look at first image in multi-image file
info.IMAGE_INDEX =  0       ; only look at first image in multi-image file
info.PIXEL_TYPE =   1       ; byte data
info.TYPE=          'GIF'

RETURN, 1L  ;success

end