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.

  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

  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.

  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:
  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.

 KEYWORD OUTPUT PARAMETERS:

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

 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