NAME:
  findsrc
 PURPOSE:
  Automatic source detection and photometry from a digital image.
 DESCRIPTION:

 CATEGORY:
  CCD data processing
 CALLING SEQUENCE:
  findsrc,file
 INPUTS:
  file - Name of image file to search for sources.  This can also be a
           2-d array rather than forcing this program to read from a file.
 OPTIONAL INPUT PARAMETERS:

 KEYWORD INPUT PARAMETERS:

  BINFAC   - Amount to bin the image by prior to source detection step.
               Default=1 (ie., no binning)

  EXTLIST  - If image is a multi-extension FITS image, this list will
                force the reduction of only the extension numbers listed.
                The default is to do all the extensions, one at a time.

  EXPTIME   - Exposure time of image in seconds, used only when input
                is an array.  In this case the header processing inputs
                are not needed.

  GAIN      - Gain of image, in photons/DN, default=1.0

  GAP       - This is a number used to avoid looking at pixels near the
                 object.  It should be set to a value that is roughly equal
                 to the FWHM of a typical stellar image.  Default=2 pixels.

  KEYLIST   - Name of a file containing a correspondence list. This list
                 associates a set of standard names with the actual keyword
                 names found in a FITS file header. If this keyword is
                 omitted, a default list is used, as if a file with the
                 following contents had been supplied:
                  AIRMASS   K  AIRMASS
                  DATE      K  DATE-OBS
                  DATETMPL  T  DD-MM-YYYY
                  EXPDELTA  V  0.0
                  EXPTIME   K  EXPTIME
                  FILTER    K  FILTERS
                  FILENAME  K  CCDFNAME
                  OBJECT    K  OBJECT
                  UT        K  UT 
                 The middle column is a flag. It may be K, for Keyword,
                 T, for Template, or V, for Value. If it is V, the contents
                 of the third field on that line should make sense for the
                 name in the first field.

  MAXPHOTSIG- Maximum DN value for a useful signal.  Any source with a peak
                above this level is passed over.  Default=60000.0 DN

  NOCRS     - Flag, if set, will suppress the filter step that tries to
                filter out cosmic ray strikes.  This usually works pretty
                well on properly sampled images and should generally be used.
                However, on very undersampled data, this option causes most
                sources to be dropped from consideration.

  NODISPLAY - Flag, when set will suppress all image display allowing program
                to be run in background or batch mode.  This will be somewhat
                faster as well.  The display steps take a small but non-trivial
                amount of time.

  NOINFO    - Flag, if set will suppress writing the aggregate info.log
                file with summary information for the image.

  OBJRAD    - Radius of object aperture, in pixels, for photometry extraction.
                Default=GAP

  OUTPATH   - Optional path for output directory for source files.
                If not specified, the current directory is used.

  PATH      - Optional path for original image directory.
                If not specified, the current directory is used.

  PHOTOGRAPHIC - Flag, if set will use photphot.pro for centroid and photometry
                   calculations rather than basphote.  This is for use on
                   scanned photographic data.

  SIGTHRESH - Sigma threshold for source detection.  Anything brighter
                than this many sigma above sky will be considered a source.
                Default = 2.5

  SILENT - Flag, if set suppresses all printed (non-error) output.

  WINDOW    - Size of region to average over in each direction, default=6

 OUTPUTS:
  If the input is a file name, then a fits file is written with the results
    of the extraction.  The file name is the same as the input file name
    with '.src' appended.  If the input file is a multi-group fits file
    then there will be as many output files as there are extensions.  In
    that case, the tag added looks like .srcxN where N is the extension
    number.  The data is written as a 2-D array but it is really a table of
    numbers (all floating point).  If you read the fits file you can extract
    the following information from the resulting array:

      xpos = data[*,0]       X position of source
      ypos = data[*,1]       Y position of source
      fwhm = data[*,2]       FWHM of source in pixels
      mag  = data[*,3]       Instrumental magnitude of source
      err  = data[*,4]       Uncertainty on the instrumental magnitude
      snr  = data[*,5]       SNR of source detection

  In addition to the array data, other useful information is stored in the
    header of the fits file.

  If the input is an array, then the only output is the anonymous structure
    returned via the RESULTS output keyword.  No files are written for this
    case.

 KEYWORD OUTPUT PARAMETERS:

 RESULTS    - The results of the source extraction are returned to this
                variable as an anonymous structure.  The following tags
                are returned in the structure:

               xc       - X position of sources [pixels]
               yc       - Y position of sources [pixels]
               fwhm     - full-width at half-max of sources [pixels]
               flux     - Raw flux of sources [photons/sec]
               mag      - Instrumental magnitude of sources
               err      - Uncertainty on the magnitude
               sky      - Mean sky signal for each source [DN]
               skysig   - Sky noise for each source [DN]
               snr      - signal-to-noise ratio for source
               nobj     - Number of sources
               avgfwhm  - Robust average of FWHM of all sources [pixels]
               avgsky   - Robust average of sky values [DN]
               skysg    - Robust average of sky noise [DN]
               obscura1 - Fraction of image obscured at 5*skysig
               obscura2 - Fraction of image obserred at 50*skysig

 COMMON BLOCKS:

 SIDE EFFECTS:

 RESTRICTIONS:

 PROCEDURE:

 MODIFICATION HISTORY:
   98/03/11, Written by Marc W. Buie, Lowell Observatory
   98/03/22, MWB, added OBJRAD keyword
   98/03/23, MWB, added EXTLIST keyword
  2003/02/21, MWB, added a blank padding character to make sure object name
                      never abuts the file name in the log file.
  2004/03/04, MWB, added option for array input
  2004/07/15, MWB, extracted the collapse function to an external routine
  2007/10/29, MWB, added PHOTOGRAPIC keyword for scanned plate data.
  2008/07/25, MWB, add flux to output results structure.  Impose minimum
                     sigma and flux values to 1 in CRS calculation
  2009/11/17, MWB, added OUTPATH keyword
  2010/05/06, MWB, added EXPTIME keyword, added more documentation
  2010/08/03, MWB, minor fix for pathological input
  2011/03/04, MWB, fix to make sure results structure exists no matter what
                      but if no objects found nobj is the only tag.
  2014/03/17, MWB, added NOCRS keyword
  2014/06/26, MWB, added NOINFO keyword
  2014/10/25, MWB, fixed minor bug with a variable name