; $Id: read_image.pro,v 1.14 2001/01/15 22:28:10 scottm Exp $
;
; Copyright (c) 1998-2001, Research Systems, Inc.  All rights reserved.
;	Unauthorized reproduction prohibited.
;+
; NAME:
;	READ_IMAGE
;
; PURPOSE:
;       The READ_IMAGE function reads the image contents of a file and
;       returns the image in an IDL variable. If the image contains a
;       palette it can be returned as well in three IDL variables.
;       READ_IMAGE returns the image in the form of a 2D array (for
;       grayscale images) or a (3, n, m) array (for true-color images.
;       READ_IMAGE can read most types of image files supported by IDL.
;       See QUERY_IMAGE for a list of supported formats.
;
; CATEGORY:
;       Input/Output
;
; CALLING SEQUENCE:
;       Result = READ_IMAGE(Filename [, Red, Green, Blue])
;
; INPUTS:
;	Filename: A scalar string containing the name of the file to read.
;
; OUTPUTS;
;       Red: A named variable to receive the red channel of the color
;            table if a colortable exists.
;
;       Green: A named variable to receive the green channel of the color
;            table if a colortable exists.
;
;       Blue: A named variable to receive the blue channel of the color
;            table if a colortable exists.
;
; OPTIONAL KEYWORDS:
;
;       IMAGE_INDEX - Set this keyword to the index of the image to read
;                     from the file.  The default is 0, the first image.
;
; OUTPUTS:
;	This function returns the selected image array. The default
;       is 0, the first image.
;
; EXAMPLE:
;       myImage = READ_IMAGE()
;
; MODIFICATION HISTORY:
; 	Written by:	Scott Lasica, July, 1998
;-
;

function READ_IMAGE, filename, red, green, blue, IMAGE_INDEX = iIndex

  ON_ERROR, 2         ; return to caller if error

  if (N_ELEMENTS(iIndex) eq 0) then begin
     iIndex=0
  endif else iIndex=(iIndex>0)

  if (not QUERY_IMAGE(filename, CHANNELS=chans, HAS_PALETTE=pal, $
                      IMAGE_INDEX=iIndex, TYPE=iType, $
                      NUM_IMAGES=nImages)) then begin
    MESSAGE,'Not a valid image file: '+STRTRIM(STRING(filename),2),/CONTINUE
    return, -1
  endif

  if (iIndex ge nImages) then begin
    MESSAGE,'Invalid image index: '+STRTRIM(STRING(iIndex),2),/CONTINUE
    return, -1
  endif

  case iType of
    'BMP':   iRet = READ_BMP(filename, red, green, blue, /RGB)
    'GIF':   READ_GIF, filename, iRet, red, green, blue
    'JPEG':  READ_JPEG, filename, iRet
    'PNG':   iRet = READ_PNG(filename, red, green, blue)
    'PPM':   READ_PPM, filename, iRet
    'SRF':   READ_SRF, filename, iRet, red, green, blue
    'TIFF':  BEGIN
    	iRet = READ_TIFF(filename, red, green, blue, IMAGE_INDEX=iIndex, $
    		PLANAR=planar)
    	IF (planar EQ 2) AND (N_ELEMENTS(iRet) EQ 1) THEN BEGIN
    	; convert RGB planes to pixel-interleave
    		dim = [1,SIZE(red,/DIMENSIONS)]
    		iRet = [REFORM(TEMPORARY(red),dim), $
    			REFORM(TEMPORARY(green),dim), $
    			REFORM(TEMPORARY(blue),dim)]
    	ENDIF
    	END
    'DICOM': iRet = READ_DICOM(filename, red, green, blue, IMAGE_INDEX=iIndex)
  endcase

  ;; There are situations where a file could pass the query, but an image
  ;; couldn't be read.
  if (N_ELEMENTS(iRet) eq 0) then iRet = -1

  return, iRet
end