.help irmatch1d Jan90 noao.nproto
.ih
NAME
irmatch1d -- align and match the elements of the mosaiced image
.ih
USAGE
irmatch1d input output database coords
.ih
PARAMETERS
.ls input
The mosaiced image to be aligned. This image must have been produced by
the IRMOSAIC task and have an accompanying database file specified by
\fIdatabase\fR.
.le
.ls output
The aligned image produced by IRMATCH1D.
.le
.ls database
The database file from the IRMOSAIC task.
.le
.ls coords
If \fIalignment\fR = "coords", then \fBcoords\fR is
a text file listing the coordinates of objects in the input
image one object per line in the following
format: 1) the x and y coordinates of the object in the first subraster
2) the x and y coordinates of the same object in the second subraster
3) the x and y coordinates of the next object in the first subraster
etc.
If \fIalignment\fR = "file", then \fBcoords\fR is a text file listing
the x, y and intensity shifts in columns 1, 2 and 3 respectively,
of each input subraster relative to the reference subraster. The
most common use of this option is to make fine adjustments by hand
to the output of IRMATCH1D by editing the computed shifts slightly and
rerunning IRMATCH1D with the new shifts.
.le
.ls xshift
The x shift in pixel units if \fIalignment\fR = "shifts".
.le
.ls yshift
The y shift in pixel units if \fIalignment\fR = "shifts".
.le
.ls alignment = "coords"
The method of aligning the subraster.
.ls coords
The x and y positions of the marker points are listed in a file in the
format specified by the \fIcoords\fR parameter.
.le
.ls shifts
The x and y shifts of a subraster with respect to its neighbour are
set to \fIxshift\fR and \fIyshift\fR.
.le
.ls file
The x,  y  and intensity shifts of each input subraster with respect to the
reference subraster image.
.le
.le
.ls match = "*"
Match intensities using the overlap region between adjacent subrasters. The
median intensity is computed in the overlap region
and the intensity scale of the current subraster is scaled to that of
the previous subraster. Intensities are matched in one dimension in the order
in which they
are placed in the output image. The default is match everything.
Those subrasters to be matched must be listed by number. For example to
match intensities for subrasters 1 to 5 and 10 to 20 set match = "1-5,10-20".
To match all the subrasters set match = "1-999" or match="*".
.le
.ls nxrsub = INDEF, ls nyrsub = INDEF
The column and line index of the reference subraster.
This will default to the central subraster.
.le
.ls xref = 0, yref = 0
The x and y offset of the position of the reference subraster in the
output image. The default action is to place the reference subraster
in the same position in the output image as it has in the input image.
.le
.ls trimlimits = "[1:1,1:1]"
The number of columns and rows to be trimmed off each edge of the
input subraster before it is inserted in the output image in section
notation. The default is to trim 1 column or row in each direction.
.le
.ls nimcols = INDEF, ls nimlines = INDEF
The number of columns and rows in the output image. The default is the
number of columns and rows in the input image.
.le
.ls oval = INDEF
The value of undefined pixels in the output image. The default is the value
in the database file from 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 = no
Print messages on the terminal describing the progress of the task.
.le
.ih
DESCRIPTION
IRMATCH1D takes the mosaiced image \fIinput\fR, the database file \fIdatabase\fR
generated by IRMOSAIC and a list of coordinates \fIcoords\fR and computes
an output image \fIoutput\fR in which all the individual subrasters are aligned.
If \fIalignment\fR = "coords", IRMATCH1D accumulates the relative shifts
between adjacent subrasters
into a total shift with respect to the reference subraster. Shifts which
do not correspond to adjacent subrasters are ignored.
For subrasters which have no direct shift information, IRMATCH1D makes a best
guess at the x and y shift based on the shifts of nearby subrasters which
do have direct shift information.
If the x and y shifts are sufficiently uniform over the whole input image
the user may set \fIalignment\fR
= shifts and input values of \fIxshift\fR and \fIyshift\fR.
Alternatively the shifts may be read from the file \fIcoords\fR if
\fIalignment\fR = "file".

Coordinate lists may be generated interactively on the Sun workstations
using the IRAF imtool facility and centered using the APPHOT CENTER
and APSELECT tasks.

The subrasters are inserted into the output image
using the interpolation scheme defined by
\fIinterpolant\fR and is made with reference to the subraster defined
by \fInxrsub\fR and \fInyrsub\fR, using the shifts defined by
the coordinates in the file \fIcoords\fR or defined by \fIxshift\fR and
\fIyshift\fR. Subrasters are placed in the output image in the order
they were inserted into the original mosaic with pixels in the most
recently placed subrasters replacing those placed earlier in the overlap
regions. Undefined pixels in the output image
are given the value \fIoval\fR. The position of the reference image in the
output image can be adjusted by setting the 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.

Intensities of adjacent subrasters can be matched using the \fImatch\fR
parameters. At present matching is done by computing the median in the
overlap region between adjacent subrasters and applying difference in
these two numbers to the subraster in question. Intensity matching is
done in one dimension  only with the direction of matching following
the order that the individual subrasters were inserted into the mosaic.
For example if IRMOSAIC was run with \fIcorner\fR = "ll", \fIdirection\fR
="row" and \fIraster\fR = "no", then the matching would start in the
lower-left corner, proceed along the first row, move to the star of the
second row and so on.

.ih
EXAMPLES

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

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

2. Align an 8 by 8 mosaic as 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> irmatch1d 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 image before inserting into the output image.

.nf
    pr> irmatch1d 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 slightly and rerun irmatch1d with the
new shifts.

.nf
    pr> irmatch1d 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> irmatch1d mosaic mosaic.al mosaic.db shifts2 align=file \
	nxrsub=6 nyrsub=5 trimlimits="[2:2,2:2]"
.fi

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