NAME:
   QUERY_ASCII

 PURPOSE:
   Query an ASCII format file and return a structure
   containing information about the file.

 CATEGORY:
   Input/Output.

 CALLING SEQUENCE:
   result = QUERY_ASCII(File, Info)

 INPUTS:
   File:   Scalar string giving the name of the file to query.

 Keyword Inputs:
   None.

 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. A file is considered to be a valid ASCII file
   if 80% of the first 32768 characters have byte values in the range
   7-13 or 32-127.

   Info:   An anonymous structure containing information about the file.
       This structure is valid only when the return value of the function
       is 1.  The Info structure has the following fields:

       Field       IDL type    Description
       -----       --------    -----------
       NAME        String      File name (including full path)
       TYPE        String      File format (always 'ASCII')
       BYTES       Long64      File length in bytes
       LINES       Long64      Number of lines
       WORDS       Long64      Number of words

   WORDS are assumed to be separated by whitespace, including
   carriage returns, line feeds, tabs, and spaces.

   Tip: If you have a data file that contains only columns of data
       (without any header lines), then the number of LINES divided
       by the number of WORDS should give you the number of columns.

 CALLS: ***
	QUERY_ASCII_VERIFY, QUERY_ASCII_WORDS
 CALLED BY:
	ASCII_TEMPLATE, READ_ASCII
 EXAMPLE:
   To retrieve information from a text file, enter:

       file = FILEPATH("irreg_grid1.txt", SUBDIR=['examples', 'data'])
       result = QUERY_ASCII(file, info)
       if (result) then HELP, info, /STRUCT $
       else PRINT, 'File not found or file is not a valid ASCII file.'


 MODIFICATION HISTORY:
   Written: CT, RSI, Dec 2004
   Modified:

 NAME:
   QUERY_BMP

 PURPOSE:
   Read the header of a BMP format image file and return a structure
   containing information about the image.

 CATEGORY:
   Input/Output.

 CALLING SEQUENCE:
   result = QUERY_BMP(File, Info)

 INPUTS:
   File:   Scalar string giving the name of the BMP 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_BMP 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

 CALLS: ***
	SWAP_ENDIAN
 CALLED BY:
	QUERY_IMAGE
 EXAMPLE:
   To retrieve information from the BMP image file named "foo.bmp"
   in the current directory, enter:

       result = QUERY_BMP("foo.bmp", info)
       IF (result GT 0) THEN BEGIN
           HELP, /STRUCT, info
       ENDIF ELSE BEGIN
           PRINT, 'BMP file not found or file is not a valid BMP format.'
       ENDELSE

 MODIFICATION HISTORY:
   Written June 1998, ACY
   CT, RSI, Aug 2003: Fix bug in error code if unable to open file.

 NAME:
 QUERY_DICOM

 PURPOSE:
   This function queries image information from a DICOM format file using
 the IDLffDICOM object interface.

 CATEGORY:
     Input/Output

 CALLING SEQUENCE:
     Result = QUERY_DICOM(File[, info])

 INPUTS:
   File: The full path name of the file to read.

 OPTIONAL KEYWORDS:
       IMAGE_INDEX - Set this keyword to the index of the image to
                     read from the file.

       DICOMEX - Set this keyword to zero to force the use of the
                 IDLffDicom object regardless of the availability of
                 IDLffDicomEX.

 OUTPUTS:
 This function returns 1 if the file can be read as a DICOM file
 and 0 otherwise

 OPTIONAL OUTPUTS:
   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 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

 KEYWORDS:
   IMAGE_INDEX:  For files containing multiple images this
       keyword can be used to specify for which image in a multi-image
       file the information should be returned.

 CALLS: ***
	QUERYDICOMGETFIRSTBEFORE
 CALLED BY:
	QUERY_IMAGE
 SIDE EFFECTS:
   IO is performed.

 RESTRICTIONS:
 Only uncompressed data format is supported (as per current DICOM obj).

 EXAMPLE:

 MODIFICATION HISTORY:
   RJF, RSI.   Sep, 1998. Original version.
   RJF, RSI.   Jan, 1999. Filter searches by sequence value.
   CT, RSI, September 2002: Better check for interleave dimension.
   AGEH, RSI, February, 2005: Use IDLffDicomEx object if licensed.

 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

 CALLS: ***
	QGIFGETNIMAGES, QGIFREADBYTE
 CALLED BY:
	QUERY_IMAGE
 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
   Aug 2000, KDB  - Added code to get the number of images in a file.
   CT, RSI, Aug 2003: Fix bug in error code if unable to open file.

 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.

 CALLS: ***
	QUERY_BMP, QUERY_DICOM, QUERY_GIF, QUERY_JPEG2000, QUERY_PPM, QUERY_SRF
 CALLED BY:
	CW_FILESEL, DIALOG_READ_IMAGE, DIALOG_WRITE_IMAGE, READ_IMAGE
 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.

 NAME:
   QUERY_JPEG2000

 PURPOSE:
   Query a JPEG2000 file. Return a structure
   containing the information about the image.

 CATEGORY:
   Input/Output.

 CALLING SEQUENCE:
   result = QUERY_JPEG2000(File, Info)

 INPUTS:
   File:   Scalar string giving the name of the 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_JPEG2000 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
           N_LAYERS    Integer         Number of quality layers
           N_LEVELS    Integer         Wavelet decomposition levels.
           OFFSET      2-element vec   X and Y offsets of image components

 CALLED BY:
	QUERY_IMAGE
 EXAMPLE:
   See READ_JPEG2000.

 MODIFICATION HISTORY:
   Written: CT, RSI, Feb 2004

 NAME:
   QUERY_PICT

 PURPOSE:
   Read the header of a PICT format image file and return a structure
   containing information about the image.

 CATEGORY:
   Input/Output.

 CALLING SEQUENCE:
   result = QUERY_PICT(File, Info)

 INPUTS:
   File:   Scalar string giving the name of the PICT 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_PICT 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

 CALLS: ***
	READ_PICT_ITEM
 COMMON BLOCKS:
   write_pict_rev

 EXAMPLE:
   To retrieve information from the PICT image file named "foo.pict"
   in the current directory, enter:

       result = QUERY_PICT("foo.pict", info)
       IF (result GT 0) THEN BEGIN
           HELP, /STRUCT, info
       ENDIF ELSE BEGIN
           PRINT, 'PICT file not found or file is not a valid PICT format.'
       ENDELSE

 MODIFICATION HISTORY:
   Written June 1998, ACY
   CT, RSI, Aug 2003: Fix bug in error code if unable to open file.

 NAME:
   QUERY_PPM

 PURPOSE:
   Read the header of a PPM format image file and return a structure
   containing information about the image.

 CATEGORY:
   Input/Output.

 CALLING SEQUENCE:
   result = QUERY_PPM(File, Info)

 INPUTS:
   File:   Scalar string giving the name of the PPM 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_PPM this keyword is ignored.

 Keyword Outputs:
   MAXVAL: Set this keyword to a named variable to retrieve the
        maximum pixel value in the image.

 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

       In addition, QUERY_PPM has the additional field:

           MAXVAL      Long            The maximum pixel value in the image.

 CALLS: ***
	READ_PPM_NEXT_TOKEN
 CALLED BY:
	QUERY_IMAGE
 EXAMPLE:
   To retrieve information from the PPM image file named "foo.ppm"
   in the current directory, enter:

       result = QUERY_PPM("foo.ppm", info)
       IF (result GT 0) THEN BEGIN
           HELP, /STRUCT, info
       ENDIF ELSE BEGIN
           PRINT, 'PPM file not found or file is not a valid PPM format.'
       ENDELSE

 MODIFICATION HISTORY:
   Written June 1998, ACY
   CT, RSI, July 2000: Make "magic" binary to avoid buffer overflow.
   CT, RSI, Aug 2003: Fix bug in error code if unable to open file.

 NAME:
   QUERY_SRF

 PURPOSE:
   Read the header of a SRF format image file and return a structure
   containing information about the image.

 CATEGORY:
   Input/Output.

 CALLING SEQUENCE:
   result = QUERY_SRF(File, Info)

 INPUTS:
   File:   Scalar string giving the name of the SRF 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_SRF 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

 CALLED BY:
	QUERY_IMAGE
 EXAMPLE:
   To retrieve information from the SRF image file named "foo.srf"
   in the current directory, enter:

       result = QUERY_SRF("foo.srf", info)
       IF (result GT 0) THEN BEGIN
           HELP, /STRUCT, info
       ENDIF ELSE BEGIN
           PRINT, 'SRF file not found or file is not a valid SRF format.'
       ENDELSE

 MODIFICATION HISTORY:
   Written June 1998, ACY
   CT, RSI, Aug 2003: Fix bug in error code if unable to open file.

 NAME:
	QUERY_WAV

 PURPOSE:
 	This function queries information from a Microsoft Windows .WAV
	(RIFF) file

 CATEGORY:
   	Input/Output

 CALLING SEQUENCE:
   	Result = QUERY_WAV(File[, info])

 INPUTS:
 	File: The full path name of the file to read.

 OUTPUTS:
	This function returns 1 if the file can be read as a .WAV file
	and 0 otherwise

 OPTIONAL OUTPUTS:
	Info : Anonymous structure containing file information.

 KEYWORDS:
	None

 CALLS: ***
	SWAP_ENDIAN
 SIDE EFFECTS:
   	IO is performed.

 RESTRICTIONS:
	Only the PCM (uncompressed) data only format is supported.

 PROCEDURE:
   	Straightforward. Will work on both big endian and little endian
	machines.

 EXAMPLE:

 MODIFICATION HISTORY:
   RJF, RSI.   Sep, 1998. Original version.
   CT, RSI, Aug 2003: Fix bug in error code if unable to open file.