pro READ_AMIEW, image, label, getpath = getpath

;+
; NAME:
;   READ_AMIEW
;
; PURPOSE:
;   Reads an AMIE label and image file into an 'image' array and 'label' array.
;
; CATEGORY:
;   AMIE Calibration
;
; CALLING SEQUENCE:
;   read_amiew, image [, label, getpath = getpath]
;
; INPUTS:
;   none
;
; OPTIONAL INPUT PARAMETERS:
;   None.
;
; OUTPUTS:
;    image: a structure containing the browse image and the full image:
;      image.images: the number of images, LONG value
;      image.image0: a 128 x 128 array containing an 8 bit downsampled image (BYTE)
;      image.image1: a LONG array containing the image, the size depends
;                    on the filter the AMIE data file contains.
;
; OPTIONAL OUTPUT PARAMETERS:
;   label: a string array containing the label
;
;   getpath: set to a variable which returns the path of the input file (useful if
;            a calling program needs to know the path to write files)
;
; EXAMPLE:
;   To read in an AMIE image and display it, do the following:
;
;   read_amiew, image
;
;   This will open a dialog window, select the image file you want to open and
;   click ok. 'image' will now contain a structure with the browse image and
;   the full image.
;
;   To display the full image, use
;
;   tvscl, image.image1
;
; USED ROUTINES:
;   AMIE library: READ_AMIE
;   SBN library:  READPDS (called by READ_AMIE)
;         Used by READPDS: HEADPDS, PDSPAR, IMAGEPDS, TASCPDS, TBINPDS, ARASCPDS,
;                   ARBINPDS
; COMMON BLOCKS:
;   None.
;
; SIDE EFFECTS:
;   Hopefully none.
;
; RESTRICTIONS:
;   Don't know.
;
; PROCEDURE:
;   (1) Pick a file using dialog_pickfile ()
;   (2) Call READ_AMIE
;
; MODIFICATION HISTORY:
;    V0.1 - 2001 Jun 13, dvk: first go
;    V0.9 - 2002 Mar 03, dvk: added documentation header
;    V1.0 - 2002 Mar 08, ma:  added PDS reader
;    V1.1 - 2003 Jun 13, ma:  added suport for all AMIE generated files (mmi, pds, img) and
;                             browse image reading
;    V1.2 - 2003 Oct 13, ma:  added sample_bit_mask identification
;    V1.3 - 2004 Feb 06, dvk: added keyword 'getpath' in call to return the path to the opened file
;    V1.4 - 2004 Oct 14, dvk: updated the header to clarify useage
;    V1.5 - 2005 Sep 26, dvk: Updated to call READ_AMIE rather than duplicating the code
;
; (c) 2001 - 2005, Miguel Almeida, Detlef Koschny, ESA/RSSD
;-

;-----------------------------------------------------------------------------------------
; Definition of constants and handling of keywords
;-----------------------------------------------------------------------------------------
cDefaultFileType1 = 'mmi'
cDefaultFileType2 = 'pds'
cDefaultFileType3 = 'img'

;-----------------------------------------------------------------------------------------
; (1) Pick the file
;-----------------------------------------------------------------------------------------
filename = dialog_pickfile (/read, $
     filter = ['*.' + cDefaultFileType1,'*.' + cDefaultFileType2,'*.' + cDefaultFileType3], $
     title = 'Select AMIE image file to read', /must_exist, get_path = getpath)

if filename EQ "" then begin
    message, 'no file selected'
    return
endif

;-----------------------------------------------------------------------------------------
; (2) Call READ_AMIE
;-----------------------------------------------------------------------------------------
image = READ_AMIE (filename, label)

end ;procedure read_AMIEw