NAME: 
  ldcalib
 PURPOSE: 
  Load calibration frames and information as instructed by calib file.
 DESCRIPTION:
 CATEGORY:
  CCD data processing
 CALLING SEQUENCE:
  ldcalib,calibfile,calib,valid
 INPUTS:
  calibfile - Name of calibration file to read.
 OPTIONAL INPUT PARAMETERS:
 KEYWORD INPUT PARAMETERS:
  CALIBPATH - Optional path to the calibration information directory.
                Default is the current directory.
  EMPTY     - Don't look for or load files.cal.  Instead, create a calib
                structure with "empty" values.  The empty values depend on
                the field but should work with programs requiring this
                structure.  The empty values will ensure that nothing would
                be done in "calibrating" an image.
 OUTPUTS:
  calib - anonymous structure with calibration information
           tag contents and usage:
              cxsize - Xsize of calibration frames (unknown if -1)
              cysize - Ysize of calibration frames (unknown if -1)
              xl     - overscan left boundary (-1 means no overscan).
              xr     - overscan right boundary (-1 means no overscan).
              x1     - LLHC (x) of cropping region.
              x2     - URHC (x) of cropping region.
              y1     - LLHC (y) of cropping region.
              y2     - URHC (y) of cropping region.
              bias   - Bias image.
              dark   - dark image (scalar 0 if no dark correction needed).
              flat   - Array of flat images.
              frngarr- Array of fringe correction images.
              frngptr- Array of pointers into frngarr for each filter.
              filter - String array of filter names for flat array.
  valid - Flag, if true indicates a valid calibration set was loaded.  The
            contents of calib are unreliable if this flag is false.
 KEYWORD OUTPUT PARAMETERS:
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
  This program reads the given calibration file, decodes the information into
    a structure with all the was in the file.  It handles reading all the
    supported version of calibration files with the hope that all older
    versions can always be read and made (in some way) to be upward
    compatible.  The organization of the returned structure is, however,
    subject to future change and expansion as the need arises.

  The following describe the file format for the supported versions.

  Version 1 files:
     Line 1 - ID line, "calib_file_v01"
     Line 2 - Instrument  (rest of file depends on this).

     LCCD
        Line 3 - Name, including path, of bias frame.
        Line 4 to end - Filter code, and file name of flat field
                       image for this filter.

     LORAL
        Line 3 - overscan limits (x1, x2)
        Line 4 - cropping region (x1:x2,y1:y2)
        Line 5 - Name, including path, of bias frame.
        Line 6 to end - Filter code, and file name of flat field
                     image for this filter.

  Version 2 files:
     Line 1 - ID line, calib_file_v02
     Line 2 - overscan limits (x2,x2), if none, use -1 -1
     Line 3 - cropping region (x1:x2,y1:y2)
     Line 4 - Name, including path, of bias frame.
     Line 5 to end - Filter code, and file name of flat field
                       image for this filter.

  Version 3 files:
     Line 1 - ID line, calib_file_v03
     Line 2 - overscan limits (x2,x2), if none, use -1 -1
     Line 3 - cropping region (x1:x2,y1:y2)
     Line 4 - Name, including path, of bias frame.
     Line 5 - Name, including path, of dark frame.  [none] means not needed.
     Line 6 to end - Filter code, and file name of flat field
                       image for this filter plus optional fringe
                       correction image.

 MODIFICATION HISTORY:
  95/08/08, Written by Marc W. Buie, Lowell Observatory
  99/05/16, MWB, Added support for optional fringe correction image(s).
  99/05/20, MWB, near total rewrite to legitimize this routine for
                   inclusion in ccdphot.pro.  Numerous changes were made
                   that change the contents of the calibration structure
                   but make it more general as is needed by ccdphot.
  99/10/28, MWB, fixed cxsize,cysize bug
  99/11/15, MWB, added EMPTY keyword
  2000/10/12, MWB, fixed bug that caused crash when loading a file that
                   did not have any flat field frame information.
  2001/05/01, MWB, changed behavior so that if x1,x2 or y1,y2 make it to the
                   end, then these values are loaded from the cxsize or cysize.
  2010/04/22, MWB, changed to ignore blank lines in the filter section.
  2010/11/17, MWB, added silent keyword