.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