idlastro / DAOPHOT-Type Photometry Procedures: FIND

[Source code]

NAME
FIND
PURPOSE
Find positive brightness perturbations (i.e stars) in an image 
EXPLANATION
Also returns centroids and shape parameters (roundness & sharpness).
Adapted from 1991 version of DAOPHOT, but does not allow for bad pixels
nd uses a slightly different centroid algorithm.
odified in March 2008 to use marginal Gaussian fits to find centroids       
CALLING SEQUENCE
FIND, image, [ x, y, flux, sharp, round, hmin, fwhm, roundlim, sharplim 
        PRINT= , /SILENT, /MONITOR]
INPUTS
image - 2 dimensional image array (integer or real) for which one
        wishes to identify the stars present
OPTIONAL INPUTS
FIND will prompt for these parameters if not supplied
hmin -  Threshold intensity for a point source - should generally 
        be 3 or 4 sigma above background RMS
fwhm  - FWHM (in pixels) to be used in the convolve filter
sharplim - 2 element vector giving low and high cutoff for the
        sharpness statistic (Default: [0.2,1.0] ).   Change this
        default only if the stars have significantly larger or 
        or smaller concentration than a Gaussian
roundlim - 2 element vector giving low and high cutoff for the
        roundness statistic (Default: [-1.0,1.0] ).   Change this 
        default only if the stars are significantly elongated.
OPTIONAL INPUT KEYWORDS
/MONITOR - Normally, FIND will display the results for each star 
         only if no output variables are supplied.   Set /MONITOR
         to always see the result of each individual star.
 /SILENT - set /SILENT keyword to suppress all output display 
 PRINT - if set and non-zero then FIND will also write its results to
         a file find.prt.   Also one can specify a different output file 
         name by setting PRINT = 'filename'.
OPTIONAL OUTPUTS
x - vector containing x position of all stars identified by FIND
y-  vector containing y position of all stars identified by FIND
flux - vector containing flux of identified stars as determined
        by a Gaussian fit.  Fluxes are NOT converted to magnitudes.
sharp - vector containing sharpness statistic for identified stars
round - vector containing roundness statistic for identified stars
NOTES
(1) The sharpness statistic compares the central pixel to the mean of 
he surrounding pixels.   If this difference is greater than the 
riginally estimated height of the Gaussian or less than 0.2 the height of the
Gaussian (for the default values of SHARPLIM) then the star will be
rejected. 
2) More recent versions of FIND in DAOPHOT allow the possibility of
gnoring bad pixels.    Unfortunately, to implement this in IDL
ould preclude the vectorization made possible with the CONVOL function
nd would run extremely slowly.
3) Modified in March 2008 to use marginal Gaussian distributions to 
ompute centroid.   (Formerly, find.pro determined centroids by locating
here derivatives went to zero -- see cntrd.pro for this algorithm.   
his was the method used in very old (~1984) versions of DAOPHOT. )   
s discussed in more  detail in the comments to the code, the  centroid
omputation here is  the same as in IRAF DAOFIND but differs slightly 
rom the current DAOPHOT.
PROCEDURE CALLS
GETOPT()
REVISION HISTORY
Written W. Landsman, STX  February, 1987
ROUND now an internal function in V3.1   W. Landsman July 1993
Change variable name DERIV to DERIVAT    W. Landsman Feb. 1996
Use /PRINT keyword instead of TEXTOUT    W. Landsman May  1996
Changed loop indices to type LONG       W. Landsman Aug. 1997
eplace DATATYPE() with size(/TNAME)   W. Landsman Nov. 2001
ix problem when PRINT= filename   W. Landsman   October 2002
ix problems with >32767 stars   D. Schlegel/W. Landsman Sep. 2004
ix error message when no stars found  S. Carey/W. Landsman Sep 2007
ewrite centroid computation to use marginal Gaussians W. Landsman 
         Mar 2008
dded Monitor keyword, /SILENT now suppresses all output 
           W. Landsman    Nov 2008
ork when threshold is negative (difference images) W. Landsman May 2010