diff options
Diffstat (limited to 'pkg/proto/doc/imalign.hlp')
| -rw-r--r-- | pkg/proto/doc/imalign.hlp | 328 |
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 |