Collect and combine CCD flat frames into a superflat frame


  The files are assumed to be named as 'root'NNN where 'root' is the
  root of the file name that you supply and NNN is a three digit number.
  If your file name has an imbedded '.' then add it to the root.

  The specified range of files are all read in from FITS files.  Then each
  image has the overscan mean subtracted (if desired), cropped (as indicated),
  input bias image is subtracted, and then the dark is multipled by each
  image's exposure time and then subtracted.  These images are then
  normalized using the mean of the SCALE region and then averaged weighting
  by the signal-to-noise ratio of each flat image.  The weighted averaging
  is done with AVGCLIP.PRO which does a robust average of the image
  stack so that cosmic rays, stars, and other transient image defects are
  eliminated.  This will do a very good sky flat if enough images are provided
  of different field pointings.

  When done, the resulting flat image is returned to the caller and the image
  is saved to a FITS file with the specified output filename.

  CCD data processing


  root    - Root of the file name (you must include . in the name).
  outsuf  - The suffix of the final output file.
  start   - First frame number to read (integer or long).
               Start can also be a vector of explicit frame numbers to load.
               In this case, nframes need not be specified and in fact will
               be ignored.
  nframes - Number of frames to average.
  bias    - Bias frame image name to subtract from each raw flat.
  dark    - Dark frame image name to subtract from each raw flat.



   CROP     = region of original image to save, default=no cropping.

   DDIR    - Path to the raw data, default = ''

  DIGITS   - Optional input to indicate how many digits are in the suffix
                of the file name.  The default for this input is 0.  In this
                case it uses the ROBOCCD scheme which is three digits up
                to 999.  After that, it gets complicated, see numtoflist
                for more information.  If you were to give it a value of
                three you would get the same behavior except you won't get
                the ROBOCDD extension.  This is really designed for when
                you have four or more digits.

   EXCLUDE - Optional vector of image numbers that should be excluded from
                average.  Default is to include all frames.

   EXPKEY = String, FITS keyword to read to get exposure time, default=EXPTIME

   JUSTMEDIAN - Flag, if set will stop processing after the initial median
                  combination of the image cube and this will be the final
                  answer.  This should used only if the intrinsic noise
                  level of the result can never drop below 1 DN.  Particularly
                  useful for a small number of flat images.

   OVERSCAN = column overscan region to use for frame bias level,
                 default=no overscan subtraction.

   RDNOISE  - Read noise of CCD, [DN], default=10

   SAVECHK - String with name of directory to save graphics to.  The images
               saved are the final flat, the original image, and the
               flattened flat images.  They are heavily binned if large
               and are useful for figuring out if the input flats are good
               or not.  The default is '[[none]]' which means to not save
               any of the graphics.  Using this option causes the program to
               use the current graphics device to open and use window 7.

   SCALE - 4 element vector which, if provide, defines the region of the
           array dimensions that are used to scale the mean
           of the arrays before combining (.  If combined in this
           manner, the arrays are combined weighted by the means.
           These coordinates apply to the pixel locations AFTER cropping.
           The default is to use the center 50% of the image but not any
           bigger than 200x200 subsection at the center.

   MINGOOD - Minimum number of frames required to be considered a good
                bias.  (Default=15)

   MAXSIG  - Maximum sigma threshold for filtering bad frames.
                Default is inherited from gradebias

  flat - Final robust averaged and normalized flat image.
  good - Flag, 1 if flat is considered good, 0 if not.


  95/03/10 - Initial crude version written, Marc W. Buie, Lowell Observatory
  95/06/04, MWB, added EXCLUDE keyword
  95/06/13, MWB, added SCALE, OVERSCAN, CROP keywords
  99/06/10, MWB, added EXPTIME keyword and added documentation.
  2000/02/03, MWB, rewrite to add support for multigroup FITS files.
  2000/02/28, MWB, added support for frame numbers > 999.
  2001/02/23, MWB, added option to provide input file list.
  2001/04/28, MWB, added DDIR keyword
  2004/05/05, MWB, fixed SCALE keyword default action.  It was not working
                     right at all and the region selected was much too large.
  2006/07/14, MWB, added RDNOISE keyword
  2006/07/27, MWB, added JUSTMEDIAN keyword
  2006/10/23, MWB, fixed output header keyword problem (remove BSCALE/BZERO)
  2013/10/05, MWB, added SAVECHK keyword
  2015/04/26, MWB, added use of gradeflat
  2016/05/29, MWB, added DIGITS keyword