Repatch (from linux) of OSX IRAF

1 files changed, 328 insertions, 0 deletions

diff --git a/pkg/proto/doc/imalign.hlp b/pkg/proto/doc/imalign.hlp
new file mode 100644
index 00000000..bf666b6c
--- /dev/null
+++ b/pkg/proto/doc/imalign.hlp
@@ -0,0 +1,328 @@
+.help imalign Feb90 proto
+.ih
+NAME
+imalign -- register a list of images 
+.ih
+USAGE
+imalign images coords
+.ih
+PARAMETERS
+.ls images
+The list of images to be shifted and trimmed.  This list should
+normally contain the \fIreference\fR to include its borders in the
+calculation of the trim section as well as to preserve the image
+alignment following trimming.
+.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.  Note
+that \fIreference\fR is a query parameter to IMALIGN, but a hidden
+parameter to IMCENTROID.
+.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 \fBYshift=Yref-Yin\fR.  If \fIshifts\fR
+is null, a coarse centering pass will be made to attempt to determine
+the initial shifts.
+.le
+.ls prefix = "rg"
+The output images will have root names that are prefixed by this
+string.  If \fIprefix\fR is null, the input \fIimages\fR will be
+overwritten.
+.le
+.ls shiftimages = yes
+If \fIshiftimages\fR is yes, the IMSHIFT task will be used to align the
+images.  If \fIshiftimages\fR is no, the images will not be aligned but
+only centered.
+.le
+.ls trimimages = yes
+If \fItrimimages\fR is yes, the output images will be trimmed to
+include only the region over which they all overlap.  The
+trim section that is actually used may differ slightly from that
+reported by IMCENTROID.  A correction may be applied to compensate for
+the boundary extension "contamination" due to multi-pixel (e.g.,
+\fIinterp_type\fR = poly5) interpolation near the edges of the images.
+.le
+.ls verbose = yes
+Print the centers, shifts, and trim section?
+.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 interp_type = "spline3"
+The interpolation function type for the IMSHIFT task.  See the help
+page for IMSHIFT for more information.
+.le
+.ls boundary_type = "constant"
+The boundary extension type for the IMSHIFT task.  See the help page
+for IMSHIFT for more information.
+.le
+.ls constant = 0.
+The constant to be used if \fIboundary_type\fR is "constant".  See the
+help page for IMSHIFT for more information.
+.le
+.ih
+DESCRIPTION
+IMALIGN measures the X and Y axis shifts between a list of images,
+\fIimages\fR and a reference image, \fIreference\fR, that is, the
+shifts that should be added to the input image coordinates to convert
+them into the reference coordinates.  By default it will apply the
+measured shifts and then trim the \fIimages\fR to consistent borders.
+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 and contain
+enough high signal/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 or features in the coordinate
+frame of each image and then to subtract the corresponding centers
+found in the reference image.  The shifts of the registration objects
+are averaged for each image.
+
+IMALIGN 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 passes 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.
+
+If \fIshiftimages\fR is yes the images will actually be shifted using
+the IMSHIFT task.  Note that if \fIinterp_type\fR is "nearest" the
+effect on the images is the same as if the shifts were rounded to
+integral values.  In this case, the pixels will be shifted without
+interpolation.  This can be used for data in which it is more important
+to preserve the pixel values than it is to achieve perfect
+registration.
+
+If \fItrimimages\fR is yes, the output images will be trimmed to
+include only the region over which they all overlap.  The trim section
+that is actually used may differ slightly from that reported by
+IMCENTROID.  A one or two pixel correction may be applied to each edge
+to compensate for the boundary extension "contamination" due to
+multi-pixel (e.g., \fIinterp_type\fR = poly5) interpolation near the
+edges of the images.
+
+IMALIGN 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 the IMSHIFT task 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.  IMALIGN will cause the
+small image to be shifted such that the object is positioned at the same
+pixel location as in the reference.  In performing the shift, 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, IMALIGN will print a warning message and refuse to proceed
+with the trimming although the vignetting will occur whether or not the
+images are trimmed.  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.
+
+Trimming will also not be performed if the entire overlap region vanishes.
+
+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 and disable trimming
+.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.  A sky level that varies across
+the image should be removed before processing.  The centering and
+calculation of the shifts may be performed with \fIshiftimages\fR = no
+(or directly with IMCENTROID) and the calculated shifts applied to the
+images directly with IMSHIFT.
+.ih
+EXAMPLES
+1. Align three images to the first using the list of registration star
+coordinates in the file "x1.coords".
+
+.nf
+    cl> imalign x1,x2,x3 x1.coords refer=x1
+.fi
+
+2. Align a list of images contained in the file "imlist", overwriting the
+original images with the shifted and trimmed images:
+
+.nf
+    cl> imalign @imlist x1.coords refer=x1 prefix=""
+.fi
+
+3. Align the images leaving the output images the same size as the input
+images:
+
+.nf
+    cl> imalign @imlist x1.coords refer=x1 trimimages-
+.fi
+
+4. Perform the centering but not the shifts:
+
+.nf
+    cl> imalign @imlist x1.coords refer=x1 shiftimages-
+.fi
+
+5. Perform the centering, don't calculate the shifts at all (i.e., don't
+supply a reference image):
+
+.nf
+    pr> imalign @imlist x1.coords shiftimages-
+.fi
+
+6. Take previously measured shifts and apply them directly:
+
+.nf
+    pr> imshift @imlist shiftfile=x1.shifts
+.fi
+.ih
+BUGS
+The images being shifted must be in the current directory.
+
+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.
+
+The task can produce output images that do not contain the entire
+overlap region.  This can only occur if the images are of varying sizes.
+This behavior is caused by the action of the IMSHIFT task to preserve the
+size of an input image, thus implicitly "trimming" the image.  A work
+around is to use IMCOPY to place the images into subsections of blank
+images that are the size (in each dimension) of the largest image(s)
+and use IMALIGN with \fItrimimages\fR set to no.  The borders of the output
+images can be trimmed manually.  This is discussed above in more detail.
+
+If \fIimages\fR does not contain the \fIreference\fR and \fItrimimages\fR
+is set to yes then the set of shifted and trimmed images may no longer
+be aligned to the reference.  This occurs because any place holder
+pixels at the bottom and left edges of the images will be trimmed off.
+This is also discussed above.
+.ih
+SEE ALSO
+imcentroid, center, imshift, geomap, geotran
+.endhelp