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
MINVALIDFWHM - If provided, sets the minimum allowable FWHM to be
returned as a valid source. The default is to take
everything.
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
2019/02/05, MWB, added MINVALIDFWHM keyword