; $Id: query_image.pro,v 1.25 2004/06/29 17:50:30 scottm Exp $
;
; Copyright (c) 1993-2004, Research Systems, Inc.  All rights reserved.
;       Unauthorized reproduction prohibited.

;
;+
; NAME:
;   QUERY_IMAGE
;
; PURPOSE:
;   Read the header of an file and determine if it is recognized as an
;   image file.  If it is an image file retrieve a structure containing
;   information about the image.
;
; CATEGORY:
;   Input/Output.
;
; CALLING SEQUENCE:
;   result = QUERY_IMAGE([File, Info])
;
; INPUTS:
;   File:   Scalar string containing the name of the file to query.
;
; Keyword Inputs:
;   IMAGE_INDEX:  Set this keyword to the index of the image to query
;       from the file.  The default is 0, the first image.
;
; Keyword Outputs:
;   CHANNELS:  Set this keyword to a named variable to retrieve the number
;       of channels in the image.
;   DIMENSIONS:  Set this keyword to a named variable to retrieve the IDL
;       Type code of the image pixel format.  See the documentation for
;       the SIZE routine for a complete list of IDL Type Codes.  The valid
;       types for PIXEL_TYPE are:
;     1    Byte
;     2    Integer
;     3    Longword Integer
;     4    Floating Point
;     5    Double-precision Floating Point
;     12   Unsigned Integer
;     13   Unsigned Longword Integer
;     14   64-bit Integer
;     15   Unsigned 64-bit Integer
;   HAS_PALETTE:  Set this keyword to a named variable to retrieve a
;       value that is true if a palette is present.
;   NUM_IMAGES:  Set this keyword to a named variable to retrieve the number
;       of images in the file.
;   PIXEL_TYPE:  Set this keyword to a named variable to retrieve the IDL
;       basic type code for a pixel sample.
;   SUPPORTED_READ:  Set this keyword to a named variable to retrieve a
;       string array of image types supported by READ_IMAGE.  If the
;       SUPPORTED_READ keyword is used the filename and info arguments
;       are optional.
;   SUPPORTED_WRITE:  Set this keyword to a named variable to retrieve a
;       string array of image types supported by WRITE_IMAGE.  If the
;       SUPPORTED_WRITE keyword is used the filename and info arguments
;       are optional.
;   TYPE:  Set this keyword to a named variable to retrieve a string
;       identifying the file format.  Valid Type values are:
;     'BMP'
;     'GIF'
;     'JPEG'
;     'PNG'
;     'PPM'
;     'SRF'
;     'TIFF'
;     'DICOM'
;       'JPEG2000'
;
; OUTPUTS:
;   Result is a long with the value of 1 if the query was successful (the
;   file was recognized as an image file) 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 image types 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
;
;       If the file is recognized as a PPM file the Info structure will
;       contain the additional field:
;
;           MAXVAL      Long            The maximum pixel value in the image.
;
;       If the file is recognized as a TIFF file the Info structure will
;       contain the additional field:
;
;           PLANAR_CONFIG   Long        Equal to 2 if the image has been stored
;                                       as separate images for the red, green
;                                       and blue planes.  See the documentation
;                                       for READ_TIFF for details on reading
;                                       a TIFF image stored with PLANAR_CONFIG
;                                       set to 2.
;
; EXAMPLE:
;   To retrieve information from the image file named "foo.bmp"
;   in the current directory, enter:
;
;       result = QUERY_IMAGE("foo.bmp", info)
;       IF (result GT 0) THEN BEGIN
;           HELP, /STRUCT, info
;       ENDIF ELSE BEGIN
;           PRINT, 'Image file not found or file is not a valid image format.'
;       ENDELSE
;
; MODIFICATION HISTORY:
;   Written June 1998, ACY
;   Modified February 2000, JLP - Continue query if suffix match fails
;   CT, RSI, May 2004: Added JPEG2000 support. Add GIF support back in.
;
;-
FUNCTION QUERY_IMAGE, filename, info, $
   CHANNELS=channels, $
   DIMENSIONS=dimensions, $
   HAS_PALETTE=has_palette, $
   IMAGE_INDEX=image_index, $
   NUM_IMAGES=num_images, $
   PIXEL_TYPE=pixel_type, $
   SUPPORTED_READ=supported_read, $
   SUPPORTED_WRITE=supported_write, $
   TYPE=type


ON_ERROR, 2     ; return to caller if error

; List of all file types supported by READ_IMAGE and WRITE_IMAGE.
; These lists can be returned to the caller, and are not available from
; READ_IMAGE and WRITE_IMAGE.
if (!version.os ne "AIX") then begin $
    supported_read=['BMP','GIF','JPEG','PNG','PPM','SRF','TIFF', 'DICOM', 'JPEG2000']
endif else begin
    supported_read=['BMP','GIF','JPEG','PNG','PPM','SRF','TIFF', 'DICOM']
endelse

; DICOM write not supported
supported_write=['BMP','GIF','JPEG','PNG','PPM','SRF','TIFF', 'JPEG2000']

if (ARG_PRESENT(supported_read) or ARG_PRESENT(supported_write)) then begin
   if (N_ELEMENTS(filename) LE 0) then return, 1
endif

if (N_ELEMENTS(image_index) eq 0) then image_index = 0
result = 0
pos = STRPOS(filename, '.', /REVERSE_SEARCH)

if (pos GT 0) then begin

   suffix = STRUPCASE(STRMID(filename, pos+1, STRLEN(filename)-pos-1))
   if (STRPOS(suffix,';') ne -1) then $
     suffix = STRMID(suffix, 0, STRPOS(suffix,';'))

   switch suffix of

      'BMP': begin
        result = QUERY_BMP(filename, info, IMAGE_INDEX=image_index)
        break
        end

      'GIF': begin
        result = QUERY_GIF(filename, info, IMAGE_INDEX=image_index)
        break
        end

      'JPEG': ; fall thru
      'JPG': begin
        result = QUERY_JPEG(filename, info, IMAGE_INDEX=image_index)
        break
        end

      'PNG': begin
        result = QUERY_PNG(filename, info, IMAGE_INDEX=image_index)
        break
        end

      'PPM': begin
        result = QUERY_PPM(filename, info, IMAGE_INDEX=image_index)
        break
        end

      'SRF': begin
        result = QUERY_SRF(filename, info, IMAGE_INDEX=image_index)
        break
        end

      'TIFF': ; fall thru
      'TIF': begin
        result = QUERY_TIFF(filename, info, IMAGE_INDEX=image_index)
        break
        end

      'DCM': ; fall thru
      'DICOM': begin
        result = QUERY_DICOM(filename, info, IMAGE_INDEX=image_index)
        break
        end

      'JP2': ; fall thru
      'JPX': begin
        result = QUERY_JPEG2000(filename, info, IMAGE_INDEX=image_index)
        break
        end

      else: begin
        result = 0
        break
        end

   endswitch

endif

if (result eq 0) then begin
   ; No suffix or suffix didn't match expected type, try each file type
   result = 0   ; assume failure
   index = 0
   while ((result eq 0) and (index lt N_ELEMENTS(supported_read))) do begin
      result = CALL_FUNCTION('QUERY_' + supported_read[index], $
                             filename, info, IMAGE_INDEX=image_index)
      index = index + 1
   endwhile
endif

; if valid file found, pass values back through keywords if necessary
if (result GT 0) then begin
   if (ARG_PRESENT(channels)) then channels = info.channels
   if (ARG_PRESENT(dimensions)) then dimensions = info.dimensions
   if (ARG_PRESENT(has_palette)) then has_palette = info.has_palette
   if (ARG_PRESENT(image_index)) then image_index = info.image_index
   if (ARG_PRESENT(num_images)) then num_images = info.num_images
   if (ARG_PRESENT(pixel_type)) then pixel_type = info.pixel_type
   if (ARG_PRESENT(type)) then type = info.type
endif

return, result

end