diff options
Diffstat (limited to 'pkg/proto/doc/imcentroid.hlp')
| -rw-r--r-- | pkg/proto/doc/imcentroid.hlp | 247 |
1 files changed, 247 insertions, 0 deletions
diff --git a/pkg/proto/doc/imcentroid.hlp b/pkg/proto/doc/imcentroid.hlp new file mode 100644 index 00000000..2bedc548 --- /dev/null +++ b/pkg/proto/doc/imcentroid.hlp @@ -0,0 +1,247 @@ +.help imcentroid Feb90 proto +.ih +NAME +imcentroid -- center sources in images, optionally find shifts +.ih +USAGE +imcentroid images coords +.ih +PARAMETERS +.ls images +The list of images within which sources are to be centered. If a +\fIreference\fR image is specified, IMCENTROID will calculate the mean +X and Y shifts between the centered sources within each image and those +same sources within the \fIreference\fR. The list of \fIimages\fR +should normally include the \fIreference\fR so that its borders are +used in the calculation of the trim section for the overlap region of +the list of \fIimages\fR. +.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. If +a \fIreference\fR is specified the mean X and Y shifts between each of +the \fIimages\fR and the \fIreference\fR will be calculated, otherwise +only the centers for the individual sources will be reported. +.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 \fIYshift=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 \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 verbose = yes +Print the centers for the individual objects? If \fIverbose\fR is no +only the shifts relative to the reference coordinates will be reported. +If no \fIreference\fR image is supplied, \fIverbose\fR is automatically +set to yes. +.le +.ih +DESCRIPTION +IMCENTROID measures the X and Y coordinates of a list of sources in a +list of images. Optionally, IMCENTROID will find the mean X and Y +shifts between the \fIimages\fR and a \fIreference\fR image, that is, +the shifts that should be added to the input image coordinates to +convert them into the reference coordinates. 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 in each axis and contain enough high +signal-to-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 in the coordinate frame of each image and +then to subtract the corresponding centers found in the reference +image. The shifts of the objects are averaged for each image. + +The IMALIGN task 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 pass 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. + +IMCENTROID 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 tasks such as IMSHIFT 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. IMCENTROID will cause the +coordinate system of the small image to be shifted such that the object +will be positioned at the same pixel location as in the reference. If +the shift is performed, 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, IMCENTROID will print a warning +message and both the vignetted and unvignetted trim sections. 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. + +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 +.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. If the sky background is not +flat, but varies across the image, it can be removed before processing. +.ih +EXAMPLES +1. Calculate the shifts between three images using the list of +registration star coordinates in the file "x1.coords". + +.nf + pr> imcentroid x1,x2,x3 x1.coords refer=x1 +.fi + +2. Calculate the shifts between a list of images contained in the file +"imlist": + +.nf + pr> imcentroid @imlist x1.coords refer=x1 +.fi + +3. Perform the centering, don't calculate the shifts, i.e., don't +supply a reference image. Note that the \fIinput\fR list of shifts, +or a coarse centering pass are still needed: + +.nf + pr> imcentroid @imlist x1.coords +.fi +.ih +BUGS +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. +.ih +SEE ALSO +imalign, center, imshift, geomap, geotran +.endhelp |