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