path: root/pkg/proto/doc/imcentroid.hlp

.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