Initial commit

1 files changed, 316 insertions, 0 deletions

diff --git a/pkg/images/immatch/doc/imalign.hlp b/pkg/images/immatch/doc/imalign.hlp
new file mode 100644
index 00000000..c63be5bc
--- /dev/null
+++ b/pkg/images/immatch/doc/imalign.hlp
@@ -0,0 +1,316 @@
+.help imalign Feb90 images.immatch
+.ih
+NAME
+imalign -- register a list of images by computing relative object shifts
+.ih
+USAGE
+imalign input reference coords output
+.ih
+PARAMETERS
+.ls input
+The input images to be shifted and trimmed.  The input image list should
+contain the reference image so that its borders are
+used in the computation of the overlap region.
+.le
+.ls reference
+The reference image to which the input images will be aligned. 
+.le
+.ls coords
+A text file containing the reference image 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.
+.le
+.ls output
+The output images. 
+.le
+.ls shifts = ""
+A text file containing the initial estimate for each image of the
+shift in each axis relative to the reference 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 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 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 the shifts file is undefined.
+Care should be taken to choose an appropriate value for this parameter,
+since it is highly data dependent.  Large values 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 background 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 = 3
+The maximum number of centering iterations to perform.  The centering
+will halt when this limit is reached or when the desired Itolerance
+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 maxshift = INDEFR
+The maximum permitted difference between the predicted shift and the
+the computed shift for each object. Objects with shifts greater than
+maxshift are ignored. If maxshift is undefined no shift checking is done.
+.le
+.ls shiftimages = yes
+If shiftimages is yes, the IMSHIFT task will be used to align the
+images.  If shiftimages is no, the images will not be aligned, but
+the coordinates will still be centered.
+.le
+.ls interp_type = "spline3"
+The interpolation function used by the IMSHIFT task.
+.le
+.ls boundary_type = "constant"
+The boundary extension type used by the IMSHIFT task.
+.le
+.ls constant = 0.
+The constant used by the IMSHIFT task if \fIboundary_type\fR is "constant". 
+.le
+.ls trimimages = yes
+If trimimages 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, due to a correction applied to compensate for
+the boundary extension "contamination" near the edges of the images.
+.le
+.ls verbose = yes
+Print the centers, shifts, and trim section?
+.le
+.ih
+DESCRIPTION
+IMALIGN measures the X and Y axis shifts between a list of input images
+\fIinput\fR and a reference image \fIreference\fR, registers the
+input images to the reference image using the computed shifts,
+and trims the input images to a common overlap region.
+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 x and y translations, and contain
+enough high signal / noise, pointlike sources in common to compute 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, which computes the
+shifts, IMSHIFT, which shifts the images, and
+IMCOPY, which performs the trimming.
+
+A list of the X and Y coordinates of the registration objects should be
+provided via the \fIcoords\fR parameter.  The registration objects do not
+all have to be common to each frame; 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
+must be measured in the frame of the reference image.  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 input images and
+the reference image is required for the centering algorithm (a marginal
+centroid) to work.  This estimate can be explicitly supplied in the 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 the coords file 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 reference and input image.  This
+source should be pointlike 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 reference image in the input image list
+
+    o	Use the smallest image as the reference image
+
+    o	Choose the reference image such that the input images 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 x1.coords x1.out,x2.out,x3.out
+.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 x1.coords @imlist
+.fi
+
+3. Align the images leaving the output images the same size as the input
+images:
+
+.nf
+    cl> imalign @imlist x1 x1.coords @outlist trimimages-
+.fi
+
+4. Perform the centering but not the shifts:
+
+.nf
+    cl> imalign @imlist x1 x1.coords shiftimages-
+.fi
+
+5. Perform the centering, but don't calculate the shifts at all,
+and don't shift the image.
+
+.nf
+    pr> imalign @imlist "" x1.coords shiftimages-
+.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