Repatch (from linux) of OSX IRAF

1 files changed, 247 insertions, 0 deletions

diff --git a/pkg/proto/doc/imcentroid.hlp b/pkg/proto/doc/imcentroid.hlp
new file mode 100644
index 00000000..2bedc548
--- /dev/null
+++ b/pkg/proto/doc/imcentroid.hlp
@@ -0,0 +1,247 @@
+.help imcentroid Feb90 proto
+.ih
+NAME
+imcentroid -- center sources in images, optionally find shifts
+.ih
+USAGE
+imcentroid images coords
+.ih
+PARAMETERS
+.ls images
+The list of images within which sources are to be centered.  If a
+\fIreference\fR image is specified, IMCENTROID will calculate the mean
+X and Y shifts between the centered sources within each image and those
+same sources within the \fIreference\fR.  The list of \fIimages\fR
+should normally include the \fIreference\fR so that its borders are
+used in the calculation of the trim section for the overlap region of
+the list of \fIimages\fR.
+.le
+.ls coords
+A text file containing the coordinates of the registration objects to
+be centered in each image, one object per line with the x and y
+coordinates in columns one and two respectively.  These coordinates
+should be measured in the frame of the reference image.
+.le
+.ls reference = ""
+The reference image to which the \fIimages\fR will be aligned.  If
+a \fIreference\fR is specified the mean X and Y shifts between each of
+the \fIimages\fR and the \fIreference\fR will be calculated, otherwise
+only the centers for the individual sources will be reported.
+.le
+.ls shifts = ""
+A text file containing the initial estimate for each image of the
+shift in each axis relative to the \fIreference\fR image.  These
+estimates are used to modify the coordinates of the registration
+objects prior to centering.  The format of the file is one image per
+line with the (fractional) x and y shifts in columns one and two
+respectively.  The sense of the shifts is such that:
+\fIXshift=Xref-Xin\fR and \fIYshift=Yref-Yin\fR.
+ If \fIshifts\fR is null, a coarse centering pass will be made to
+attempt to determine the initial shifts.
+.le
+.ls boxsize = 7
+The size in pixels of the box to use for the final centering, during
+which all the sources in \fIcoords\fR are recentered in each image
+using the initial estimate of the relative shift for each image.
+Care should be taken to choose an appropriate value for this parameter,
+since it is highly data dependent.
+.le
+.ls bigbox = 11
+The size in pixels of the box to use for coarse centering.  The coarse
+pass through the centering algorithm is made with the box centered at
+the nominal position of the first source in the coordinate list.
+Coarse centering is performed only if \fIshifts\fR is null.
+Care should be taken to choose an appropriate value for this parameter,
+since it is highly data dependent.  Large value should be suspect until
+the final results are checked to see that the centering did not converge
+on the wrong coordinates, although the usual result for an inappropriate
+\fIbigbox\fR size is that the algorithm fails to converge and the task
+aborts.
+.le
+.ls negative = no
+Are the features negative?
+.le
+.ls background = INDEF
+The absolute reference level for the marginal centroid calculation.
+If \fIbackground\fR is INDEF, this is set to the mean value (between the
+thresholds) of the individual sources.
+.le
+.ls lower = INDEF
+The lower threshold for the data.  Individual pixels less than this
+value will be given zero weight in the centroids.
+.le
+.ls upper = INDEF
+The upper threshold for the data.  Individual pixels greater than this
+value will be given zero weight in the centroids.
+.le
+.ls niterate = 2
+The maximum number of centering iterations to perform.  The centering
+will halt when this limit is reached or when the desired \fItolerance\fR
+is achieved.
+.le
+.ls tolerance = 0
+The tolerance for convergence of the centering algorithm.  This is the
+integral shift of the centering box from one iteration to the next.
+.le
+.ls verbose = yes
+Print the centers for the individual objects?  If \fIverbose\fR is no
+only the shifts relative to the reference coordinates will be reported.
+If no \fIreference\fR image is supplied, \fIverbose\fR is automatically
+set to yes.
+.le
+.ih
+DESCRIPTION
+IMCENTROID measures the X and Y coordinates of a list of sources in a
+list of images.  Optionally, IMCENTROID will find the mean X and Y
+shifts between the \fIimages\fR and a \fIreference\fR image, that is,
+the shifts that should be added to the input image coordinates to
+convert them into the reference coordinates.  The task is meant to
+address the class of two dimensional image registration problems in
+which the images have the same pixel scale, are shifted relative to
+each other by simple translations in each axis and contain enough high
+signal-to-noise, point-like sources in common to form good average
+positions.  The basic operation of the task is to find centers for the
+list of registration objects in the coordinate frame of each image and
+then to subtract the corresponding centers found in the reference
+image.  The shifts of the objects are averaged for each image.
+
+The IMALIGN task is a simple script front end for IMCENTROID, IMSHIFT,
+and IMCOPY (which is used to perform the trimming).  Other scripts can
+be constructed for similar purposes.  You can type:  `help imalign
+option=source' to view the script.
+
+A list of the X and Y coordinates of the registration objects should be
+provided in the parameter \fIcoords\fR.  The registration objects do not
+all have to be common to each frame, rather only that subset of the
+objects that is contained within the bounds of a given image will be
+centered.  Only the objects that are common to both the given image and
+the reference will be used to calculate the shifts.  The coordinates
+should be measured in the frame of the \fIreference\fR.  If coarse
+centering is to be done, which is to say, if no \fIshifts\fR file is
+provided, then the first registration source should be separated from
+other sources by at least the maximum expected relative shift.
+
+An initial estimate of the shifts between each of the \fIimages\fR and
+the \fIreference\fR is required for the centering algorithm (a marginal
+centroid) to work.  This estimate can be explicitly supplied in a file
+\fIshifts\fR (\fIXshift=Xref-Xin\fR and \fIYshift=Yref-Yin\fR)
+or can be generated from the images by measuring the relative shift of
+the first source listed in \fIcoords\fR for each image.  This coarse
+centering pass requires that the first source be detached from other
+sources and from the border of each image by a distance that is at
+least the maximum shift between the \fIreference\fR and an image.  This
+source should be point-like and have a high signal to noise ratio.  The
+value of the \fIbigbox\fR parameter should be chosen to include the
+location of the source in each of the images to be aligned while
+excluding other sources.  Large values of \fIbigbox\fR should be held
+suspect until the final convergence of the centering algorithm is
+verified, although given a small value for the \fItolerance\fR, the
+quality of the final centers is independent of the estimate for the
+initial shifts.  Better convergence may also be obtained by increasing
+the \fIniterate\fR parameter, although the default value of three
+should work for most cases.  \fINiterate\fR should be kept small to
+avoid runaway.
+
+The \fIboxsize\fR parameter controls the size of the centering box for
+the fine centering pass and should be chosen so as to exclude sky
+background and other sources while including the wings of the point
+spread function.  The sense of the shifts that are calculated is
+consistent with the file supplied to the \fIshifts\fR parameter and
+with that used with the IMSHIFT task.
+
+IMCENTROID may be used with a set of \fIimages\fR which vary in size.
+This can result in vignetting of the calculated overlap region because
+of the nature of tasks such as IMSHIFT to preserve the size of an input
+image.  To visualize this, imagine a large reference image and a single
+small image to be aligned to it, both containing the same registration
+object which is at the center of each image.  IMCENTROID will cause the
+coordinate system of the small image to be shifted such that the object 
+will be positioned at the same pixel location as in the reference.  If
+the shift is performed, a large fraction of the area of the small image
+may be shifted outside of its own borders, whereas the physical overlap
+of the large and small images includes ALL of the pixels of the small
+image.  In the case of such vignetting, IMCENTROID will print a warning
+message and both the vignetted and unvignetted trim sections.  Note
+that the vignetting will not occur if the small image is used as the
+\fIreference\fR.
+
+The vignetting message may also be printed if the \fIimages\fR are all
+the same size but the \fIreference\fR is not included in the list.
+This will occur if the sense of the measured shifts in a coordinate are
+all positive or all negative since in this case the border of the
+\fIreference\fR would have provided one of the limits to the trim
+section.  The reality of this vignetting depends on your point of view.
+
+Note that many of these difficulties are due to the intrinsically fuzzy
+nature of the process of image registration.  This all leads to a few
+"rules of thumb":
+
+.nf
+    o	Include the \fIreference\fR as one of the \fIimages\fR
+
+    o	Use the smallest image as the \fIreference\fR
+
+    o	Choose the \fIreference\fR such that the \fIimages\fR are
+	scattered to either side in the shifts in each axis
+
+    o	Align images that are the same size, OR
+
+    o	Pad dissimilar sized images with blanks to the largest size
+.fi
+.ih
+CENTERING ALGORITHM
+The algorithm is a "marginal" centroid in which the fit for each axis
+is performed separately upon a vector created by collapsing the
+centering box perpendicular to that axis.  The centroid is calculated
+with respect to the level specified by \fIbackground\fR.  If
+\fIbackground\fR is INDEF, the reference level for each source in each
+image is the local mean for those pixels that lie between the
+\fIlower\fR and \fIupper\fR thresholds.  The thresholds are set to the
+local data minimum or maximum if \fIlower\fR or \fIupper\fR,
+respectively, are INDEF.  If \fInegative\fR is yes, than the marginal
+vector will be inverted before being passed to the centroid algorithm.
+
+The maximum number of centering iterations and the tolerance for
+convergence are controlled by \fIniterate\fR and \fItolerance\fR.  Note
+that the tolerance is an integer value that represents the maximum
+movement of the centering box between two successive iterations.  The
+default value of 0 requires that the centroid lie within the center
+pixel of the centering box which is \fIboxsize\fR in extent (note that
+\fIboxsize\fR must be an odd number).  This should normally be the case
+for bright, circularly symmetric point sources in images with a flat
+sky background.  If the registration sources are not circular symmetric
+try increasing the tolerance gingerly.  If the sky background is not
+flat, but varies across the image, it can be removed before processing.
+.ih
+EXAMPLES
+1. Calculate the shifts between three images using the list of
+registration star coordinates in the file "x1.coords".
+
+.nf
+    pr> imcentroid x1,x2,x3 x1.coords refer=x1
+.fi
+
+2. Calculate the shifts between a list of images contained in the file
+"imlist":
+
+.nf
+    pr> imcentroid @imlist x1.coords refer=x1
+.fi
+
+3. Perform the centering, don't calculate the shifts, i.e., don't
+supply a reference image.  Note that the \fIinput\fR list of shifts,
+or a coarse centering pass are still needed:
+
+.nf
+    pr> imcentroid @imlist x1.coords
+.fi
+.ih
+BUGS
+The coarse centering portion of the algorithm can be fooled if the
+first source on the list is not well separated from other sources, or
+if the first source has a low signal to noise ratio, or if there is a
+complicated shape to the background.
+.ih
+SEE ALSO
+imalign, center, imshift, geomap, geotran
+.endhelp