STScI Logo

starfind images.imcoords


NAME · USAGE · PARAMETERS · DESCRIPTION · ALGORITHMS · FORMATS
EXAMPLES · TIME_REQUIREMENTS · BUGS · SEE_ALSO

NAME

starfind -- automatically detect stellar objects in a list of images

USAGE

starfind image output hwhmpsf threshold

PARAMETERS

image
The list of input images. The input images must be two-dimensional.
output
The list of output object files. The number of output files must equal the number of input images. If output is "default", or "dir$default", or a directory specification then a default name of the form dir$root.extension.version is constructed, where dir$ is the directory name, root is the root image name, extension is "obj", and version is the next available version number.
hwhmpsf
The half-width half-maximum of the image PSF in pixels.
threshold
The detection threshold above local background in ADU.
datamin = INDEF, datamax = INDEF
The minimum and maximum good data values in ADU. Datamin and datamax default to the constants -MAX_REAL and MAX_REAL respectively.
fradius = 2.(hwhmpsf)
The fitting radius in units of hwhmpsf. Fradius defines the size of the Gaussian kernel used to compute the density enhancement image, and the size of the image region used to do the moment analysis.
sepmin = 5.(hwhmpsf)
The minimum separation for detected objects in units of hwhmpsf.
npixmin = 5
The minimum area of the detected objects in pixels.
maglo = INDEF, maghi = INDEF
The minimum and maximum magnitudes of the detected objects. Maglo and maghi default to the constants -MAX_REAL and MAX_REAL respectively.
roundlo = 0.0, roundhi = 0.2
The minimum and maximum ellipticity values of the detected objects, where ellipticity is defined as 1 - b / a, and a and b are the semi-major and semi-minor axis lengths respectively.
sharplo = 0.5, sharphi = 2.0
The minimum and maximum sharpness values of the detected objects, where sharpness is defined to be the ratio of the object size to the hwhmpsf parameter value.
wcs = ""
The world coordinate system. The options are:
" "
The world coordinate system is undefined. Only logical (pixel) coordinates are printed.
logical
The world coordinate system is the same as the logical (pixel) coordinate system, but two sets of identical logical (pixel) coordinates are printed.
physical
The world coordinate system is the same as the logical (pixel) coordinate system of the parent image if any.
world
The world coordinate system of the image if any.
wxformat = "", wyformat = ""
The output format for the x and y axis world coordinates. If wxformat and wyformat are undefined then: 1) the value of the wcs format attribute is used if the output wcs is "world" and the attribute is defined, 2) "%9.3f" is used if the output wcs is "logical" or "physical", and "%11.8g" is used if the output wcs is "world". If the input image is a sky projection image and the x and y axes are ra and dec respectively, then the formats "%12.2H" and "%12.1h" will print the world coordinates in hours and degrees respectively.
boundary = "nearest"
The boundary extension type. The choices are:
nearest
Use the value of the nearest boundary pixel.
constant
Use a constant value.
reflect
Generate a value by reflecting around the boundary.
wrap
Generate a value by wrapping around to the other side of the image.
constant = 0.0
The constant for constant boundary extension.
nxblock = INDEF, nyblock = 256
The working block size. If undefined nxblock and nyblock default to the number of columns and rows in the input image respectively.
verbose = no
Print messages about the progress of the task ?

DESCRIPTION

STARFIND searches the input images image for local density maxima with half-widths at half-maxima of ~ hwhmpsf and peak amplitudes greater than ~ threshold above the local background, and writes the list of detected objects to output .

STARFIND is a modified version of the DAOPHOT package DAOFIND algorithm. However STARFIND is intended for use with the IMAGES package image matching and image coordinates tasks and is therefore configured somewhat differently than the version used in the photometry packages.

ALGORITHMS

STARFIND assumes that the point spread function can be approximated by a radial Gaussian function whose sigma is 0.84932 * hwhmpsf pixels. STARFIND uses this model to construct a convolution kernel which is truncated at max (2.0, fradius * hwhmpsf ) pixels and normalized to zero power.

For each point in the image density enhancement values are computed by convolving the input image with the radial Gaussian function. This operation is mathematically equivalent to fitting the image data at each point, in the least-squares sense, with a truncated, lowered, radial Gaussian function. After the convolution each density enhancement value is an estimate of the amplitude of the best fitting radial Gaussian function at that point. If datamin and datamax are defined then bad data is ignored, i.e. rejected from the fit, during the computation of the density enhancement values. Out of bounds image pixels are evaluated using the boundary extension algorithm parameters boundary and constant . Out of bounds density enhancement values are set to zero.

After the convolution, STARFIND steps through the density enhancement image searching for density enhancements greater then threshold and brighter than any density enhancements within a radius of sepmin * hwhmpsf pixels. For each potential detection the local background is estimated and used, along with the values of datamin and datamax , to estimate the position (Xc and Yc), size (Area and Hwhm), shape (E and Sharp), orientation (Pa), and brightness (Mag) of each object using the second order moments analysis shown below.

   I0 = sum (I)
    N = sum (1.0)
    if (N <= 0)
        Sky = maxdata - maxden
    else
        Sky = I0 / N

   M0 = sum (I - Sky)
   Mx = sum (X * (I - Sky))
   My = sum (Y * (I - Sky))

   Xc = Mx / M0
   Xc = My / M0
  Mag = -2.5 * log10 (M0)
 Area = N

  Mxx = sum ((X - Xc) * (X - Xc) * (I - Sky))
  Mxy = sum ((X - Xc) * (Y - Yc) * (I - Sky))
  Myy = sum ((Y - Yc) * (Y - Yc) * (I - Sky))

 Hwhm = sqrt (log (2) * (Mxx + Myy))
    E = sqrt ((Mxx - Myy) ** 2 + 4 * Mxy ** 2) / (Mxx + Myy))
   Pa = 0.5 * atan (2 * Mxy / (Mxx - Myy))
Sharp = Hmhw / Hwhmpsf 

The sums are computed using pixels which lie within fradius * hwhmpsf of the maximum density enhancement, and whose values are within the good data limits defined by datamin and datamax , and which are above the local background estimate (Sky).

Objects whose magnitude, roundess, and sharpness characteristics are outside the values defined by maglo , maghi , roundlo , roundhi , sharplo , and sharphi and whose total areas is less than npixmin pixels are rejected from the list.

If wcs parameter is defined, the world coordinates as well as the pixel coordinates of the detected objects are computed and printed using the formats defined by wxformat and wyformat .

To minimize the memory requirements and increase efficiency, STARFIND is configured to operate on data blocks that are nxblock * nyblock in size. To keep the image i/o operation to a minimum nxblock is set to INDEF and defaults to the number of columns in the input image. Setting both parameter to INDEF will force STARFIND to perform the whole operation in memory.

FORMATS

b       boolean (YES or NO)
c       single character (c or '\c' or '\0nnn')
d       decimal integer
e       exponential format (D specifies the precision)
f       fixed format (D specifies the number of decimal places)
g       general format (D specifies the precision)
h       hms format (hh:mm:ss.ss, D = no. decimal places)
m       minutes, seconds (or hours, minutes) (mm:ss.ss)
o       octal integer
rN      convert integer in any radix N
s       string (D field specifies max chars to print)
t       advance To column given as field W
u       unsigned decimal integer
w       output the number of spaces given by field W
x       hexadecimal integer
z       complex format (r,r) (D = precision)
 

Conventions for w (field width) specification:
 
    W =  n      right justify in field of N characters, blank fill
        -n      left justify in field of N characters, blank fill
        0n      zero fill at left (only if right justified)
 absent, 0      use as much space as needed (D field sets precision)
 
Escape sequences (e.g. "\n" for newline):
 
\b      backspace   (not implemented)
\f      formfeed
\n      newline (crlf)
\r      carriage return
\t      tab
\"      string delimiter character
\'      character constant delimiter character
\\      backslash character
\nnn    octal value of character
 
Examples
 
%s          format a string using as much space as required
%-10s       left justify a string in a field of 10 characters
%-10.10s    left justify and truncate a string in a field of 10 characters
%10s        right justify a string in a field of 10 characters
%10.10s     right justify and truncate a string in a field of 10 characters
 
%7.3f       print a real number right justified in floating point format
%-7.3f      same as above but left justified
%15.7e      print a real number right justified in exponential format
%-15.7e     same as above but left justified
%12.5g      print a real number right justified in general format
%-12.5g     same as above but left justified

%h          format as nn:nn:nn.n
%15h        right justify nn:nn:nn.n in field of 15 characters
%-15h       left justify nn:nn:nn.n in a field of 15 characters
%12.2h      right justify nn:nn:nn.nn
%-12.2h     left justify nn:nn:nn.nn
 
%H          / by 15 and format as nn:nn:nn.n
%15H        / by 15 and right justify nn:nn:nn.n in field of 15 characters
%-15H       / by 15 and left justify nn:nn:nn.n in field of 15 characters
%12.2H      / by 15 and right justify nn:nn:nn.nn
%-12.2H     / by 15 and left justify nn:nn:nn.nn

\n          insert a newline

EXAMPLES

1. Find stellar objects with peak values greater than 100 counts above local background in the test image dev$wpix whose fwhm is ~2.5 pixels.

cl> starfind dev$wpix default 1.25 100.
cl> display dev$wpix 1 fi+
cl> tvmark 1 wpix.obj.1 col=204 

2. Repeat the previous example but tell starfind to compute and print world coordinates in hours and degrees as well as pixel coordinates.

cl> starfind dev$wpix default 1.25 100. wcs=world wxf="%12.2H"\
    wyf="%12.1h"
cl> display dev$wpix 1 fi+
cl> tvmark 1 wpix.obj.1 col=204 

TIME REQUIREMENTS

Starfind requires approximately 8 CPU seconds to search a 512 by 512 image using a 7 by 7 pixel convolution kernel (SPARCStation2).

BUGS

SEE ALSO

imcentroid, apphot.daofind, daophot.daofind


Source Code · Search Form · STSDAS