.help iralign Sep93 noao.nproto
.ih
NAME
iralign -- align the elements of the mosaiced image
.ih
USAGE
iralign input output database coords
.ih
PARAMETERS
.ls input
The mosaiced image written by IRMOSAIC.
.le
.ls output
The output aligned image.
.le
.ls database
The database file written by IRMOSAIC.
.le
.ls coords
If \fIalignment\fR = "coords", then \fBcoords\fR is
a text file containing the x and y coordinates, measured in the input
mosaiced image, of reference objects common
to adjacent subrasters in the input mosaiced
image. The reference coordinates are written with the following format:
line 1) the x and y coordinates of an object in the any subraster,
line 2) the x and y coordinates of the same object in any adjacent subraster,
line 3) the x and y coordinates of another object in the any subraster,
line 4) the x and y coordinates of the same object in any adjacent subraster,
etc.
If \fIalignment\fR = "file", then \fBcoords\fR is a text file containing
the x and y shifts in columns 1 and 2 respectively,
of each subraster relative to the reference subraster, in the order
in which the subrasters were written into the mosaiced input image.
This option can be used to make fine adjustments to the output aligned image
by manually editing the computed shifts and rerunning
IRALIGN with the new shifts.
.le
.ls xshift
The x shift in pixels used if \fIalignment\fR = "shifts".
.le
.ls yshift
The y shift in pixels used if \fIalignment\fR = "shifts".
.le
.ls alignment = "coords"
The method of aligning the subraster.
.ls coords
The x and y positions of the reference points common to adjacent subrasters
in the input mosaiced image are listed in a text file as described
under the help for the  \fIcoords\fR parameter.
.le
.ls shifts
The x and y shifts of each subraster with respect to its neighbour are
set to \fIxshift\fR and \fIyshift\fR.
.le
.ls file
The x and y  shifts of each input subraster with respect to the
reference subraster image are listed in a text file as described
under the help for the \fIcoords\fR parameter.
.le
.le
.ls nxrsub = INDEF, ls nyrsub = INDEF
The column and row index of the reference subraster.
The default reference subraster is the central subraster.
.le
.ls xref = 0, yref = 0
The x and y offset of the reference
subraster in the output aligned image.
By default the reference subraster occupies the same position in
the output image that it does in the input image.
.le
.ls trimlimits = "[1:1,1:1]"
The number of columns or rows to trim off each edge of each input subraster
before inserting it in the output image, specified in image section notation.
The default action is to trim 1 column or line at each edge of the subraster.
.le
.ls nimcols = INDEF, nimlines = INDEF
The number of columns and lines in the output image. The defaults are  the
number of columns and lines in the input image.
.le
.ls oval = INDEF
The value of undefined pixels in the output image. The default is the value
stored in the database file written by IRMOSAIC.
.le
.ls interpolant = linear
The type of interpolant used to shift the subrasters. The options are:
.ls nearest
Nearest neighbour interpolation.
.le
.ls linear
Bilinear interpolation.
.le
.ls poly3
Bicubic polynomial interpolation.
.le
.ls poly5
Biquintic polynomial interpolation.
.le
.ls spline3
Bicubic spline interpolation.
.le
.le
.ls verbose = yes
Print messages on the terminal describing the progress of the task?
.le
.ih
DESCRIPTION
IRALIGN takes the mosaiced image \fIinput\fR and database
\fIdatabase\fR files
written by IRMOSAIC, and a list of reference object
coordinates \fIcoords\fR created by the user, and writes
an output image \fIoutput\fR in which all the subrasters are aligned
with respect to a reference subraster.

If \fIalignment\fR = "coords", IRALIGN accumulates the relative shifts
between adjacent subrasters defined by the data in \fIcoords\fR,
into a total shift for each subraster with respect to the reference subraster.
Relative shifts defined for non-adjacent subrasters are ignored.
For those subrasters which have no relative shift information,
IRALIGN makes a best guess at the relative x and y shifts
based on the relative x andy shifts of nearby subrasters
which do have relative shift information.  If the x and y shifts
are sufficiently uniform over the whole input image the user may set
\fIalignment\fR to  "shifts" and supply values for
\fIxshift\fR and \fIyshift\fR.
Alternatively the total shifts may be read directly from the  file \fIcoords\fR
if \fIalignment\fR = "file".

Coordinate lists for the \fIalignment\fR = "coords" option,
may be generated interactively using the RIMCURSOR, 
or APPHOT package CENTER and APSELECT tasks. For example a coordinate list
written by RIMCURSOR for a 
4 by 4 mosaic of 51 by 51 pixel square images containing a single
reference object common to all the subrasters might look like the following.

.nf
41.3   42.6     1 \40 	# coordinates of ref object in subraster 1
62.0   38.5	1 \40   # coordinates of ref object in subraster 2
41.3   42.6     1 \40   # coordinates of ref object in subraster 1
38.1   95.8     1 \40   # coordinates of ref object in subraster 3
62.0   38.5     1 \40   # coordinates of ref object in subraster 2
70.3   89.0     1 \40   # coordinates of ref object in subraster 4
38.1   95.8     1 \40   # coordinates of ref object in subraster 3
70.3   89.0     1 \40   # coordinates of ref object in subraster 4
.fi

In this example subrasters 1 and 2 are in the lower-left and
lower-right hand corners of
the mosaiced image respectively, while subrasters 3 and 4 are in the
upper-left and upper- right hand corner of the mosaiced image.
Any number of reference objects may be used.

The subrasters are inserted into the output image using the
interpolation scheme defined by
\fIinterpolant\fR, and aligned with reference to the subraster defined
by \fInxrsub\fR and \fInyrsub\fR, using the shifts defined by
the data in the file \fIcoords\fR or defined by \fIxshift\fR and
\fIyshift\fR. Subrasters are inserted into the output image in the order
they were placed in the original mosaic with pixels in the most recently
placed subrasters replacing those in earlier placed ones in the overlap regions.
Undefined pixels in the output image
are assigned the value \fIoval\fR. The position of the reference subraster
in the output image may be adjusted by setting the offset parameters
\fIxref\fR and \fIyref\fR. The edges of each subraster may be trimmed
before insertion into the output image by setting the \fItrimlimits\fR
parameter.

.ih
EXAMPLES

1. Align an 8 by 8 mosaic with respect to subraster 6, 5.

.nf
    pr> iralign mosaic mosaic.al mosaic.db coords nxrsub=6 \
	nyrsub=5
.fi

2. Align an 8 by 8 mosaic as in example 1 above but shift the position of the
reference subraster in the output image by 2 pixels in x and 3 pixels
in y.

.nf
    pr> iralign mosaic mosaic.al mosaic.db coords nxrsub=6 \
	nyrsub=5 xref=2 yref=3
.fi

3. Align an 8 by 8 mosaic as 1 above but trim 2 rows and columns off
of each input subraster before inserting it into the output image.

.nf
    pr> iralign mosaic mosaic.al mosaic.db coords nxrsub=6 \
	nyrsub=5 trimlimits="[2:2,2:2]"
.fi

4. Rerun the above example saving the verbose output in a file. Use the 
PROTO package FIELDS task to select the xshift, yshift and intensity
shift fields, edit the shifts manually and rerun IRALIGN with the
new shifts.

.nf
    pr> iralign mosaic mosaic.al mosaic.db coords nxrsub=6 \
	nyrsub=5 trimlimits="[2:2,2:2]" > shifts1

    pr> fields shifts1 3,4,6 > shifts2

    pr> edit shifts2

	... make whatever changes are desired

    pr> iralign mosaic mosaic.al.2 mosaic.db shifts2 align=file \
	nxrsub=6 nyrsub=5 trimlimits="[2:2,2:2]"
.fi

.ih
TIME REQUIREMENTS
.ih
BUGS
.ih
SEE ALSO
irmosaic, apphot.center, apphot.apselect, irmatch1d, irmatch2d
.endhelp
