From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001
From: Joseph Hunkeler <jhunkeler@gmail.com>
Date: Wed, 8 Jul 2015 20:46:52 -0400
Subject: Initial commit

---
 pkg/images/imcoords/doc/starfind.hlp | 304 +++++++++++++++++++++++++++++++++++
 1 file changed, 304 insertions(+)
 create mode 100644 pkg/images/imcoords/doc/starfind.hlp

(limited to 'pkg/images/imcoords/doc/starfind.hlp')

diff --git a/pkg/images/imcoords/doc/starfind.hlp b/pkg/images/imcoords/doc/starfind.hlp
new file mode 100644
index 00000000..9817735e
--- /dev/null
+++ b/pkg/images/imcoords/doc/starfind.hlp
@@ -0,0 +1,304 @@
+.help starfind May97 images.imcoords
+.ih
+NAME
+starfind -- automatically detect stellar objects in a list of images
+.ih
+USAGE
+starfind image output hwhmpsf threshold
+.ih
+PARAMETERS
+.ls image
+The list of input images. The input images must be two-dimensional.
+.le
+.ls 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.
+.le
+.ls hwhmpsf
+The half-width half-maximum of the image PSF in pixels.
+.le
+.ls threshold
+The detection threshold above local background in ADU.
+.le
+.ls 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.
+.le
+.ls fradius = 2.5 (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.
+.le
+.ls sepmin = 5.0 (hwhmpsf)
+The minimum separation for detected objects in units of hwhmpsf.
+.le
+.ls npixmin = 5
+The minimum area of the detected objects in pixels.
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls wcs = ""
+The world coordinate system.  The options are:
+.ls "     "
+The world coordinate system is undefined. Only logical (pixel) coordinates
+are printed.
+.le
+.ls logical
+The world coordinate system is the same as the logical (pixel) coordinate
+system,  but two sets of identical logical (pixel) coordinates are printed.
+.le
+.ls physical
+The world coordinate system is the same as the logical (pixel) coordinate
+system of the parent image if any.
+.le
+.ls world
+The world coordinate system of the image if any.
+.le
+.le
+.ls 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.
+.le
+.ls boundary = "nearest"
+The boundary extension type. The choices are:
+.ls nearest
+Use the value of the nearest boundary pixel.
+.le
+.ls constant
+Use a constant value.
+.le
+.ls reflect
+Generate a value by reflecting around the boundary.
+.le
+.ls wrap
+Generate a value by wrapping around to the other side of the image.
+.le
+.le
+.ls constant = 0.0
+The constant for constant boundary extension.
+.le
+.ls 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.
+.le
+.ls verbose = no
+Print messages about the progress of the task ?
+.le
+
+.ih
+DESCRIPTION
+
+STARFIND searches the input images \fIimage\fR for local density maxima
+with half-widths at half-maxima of ~ \fIhwhmpsf\fR and peak amplitudes
+greater than ~ \fIthreshold\fR above the local background, and writes
+the list of detected objects to \fIoutput\fR.
+
+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.
+
+.ih
+ALGORITHMS
+
+STARFIND assumes that the point spread function can be approximated by a radial
+Gaussian function whose sigma is 0.84932 * \fIhwhmpsf\fR pixels. STARFIND uses
+this model to construct a convolution kernel which is truncated at
+max (2.0, \fIfradius * hwhmpsf\fR) 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 \fIdatamin\fR and \fIdatamax\fR 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 \fIboundary\fR and \fIconstant\fR. 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 \fIthreshold\fR
+and brighter than any density enhancements within a radius of
+\fIsepmin * hwhmpsf\fR pixels. For each potential detection the
+local background is estimated and used, along with the values of
+\fIdatamin\fR and \fIdatamax\fR, 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.
+
+.nf
+   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 
+.fi
+
+The sums are computed using pixels which lie within \fIfradius * hwhmpsf\fR of
+the maximum density enhancement, and whose values are within the good data
+limits defined by \fIdatamin\fR and \fIdatamax\fR, and which are above the local
+background estimate (Sky).
+
+Objects whose magnitude, roundness, and sharpness characteristics are outside
+the values defined by \fImaglo\fR, \fImaghi\fR, \fIroundlo\fR, \fIroundhi\fR,
+\fIsharplo\fR, and \fIsharphi\fR and whose total areas is less than
+\fInpixmin\fR pixels are rejected from the list.
+
+If \fIwcs\fR 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 \fIwxformat\fR and \fIwyformat\fR.
+
+To minimize the memory requirements and increase efficiency, STARFIND
+is configured to operate on data blocks that are \fInxblock * nyblock\fR
+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.
+
+.ih
+FORMATS
+
+.nf
+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
+.fi
+
+.ih
+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.
+
+.nf
+cl> starfind dev$wpix default 1.25 100.
+cl> display dev$wpix 1 fi+
+cl> tvmark 1 wpix.obj.1 col=204 
+.fi
+
+2. Repeat the previous example but tell starfind to compute and print
+world coordinates in hours and degrees as well as pixel coordinates.
+
+.nf
+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 
+.fi
+
+.ih
+TIME REQUIREMENTS
+Starfind requires approximately 8 CPU seconds to search a 512 by  512
+image  using  a   7 by 7 pixel convolution kernel (SPARCStation2).
+		
+.ih
+BUGS
+
+.ih
+SEE ALSO
+imcentroid, apphot.daofind, daophot.daofind
+.endhelp
-- 
cgit 

