path: root/pkg/images/immatch/doc/geotran.hlp

.help geotran Dec98 images.immatch
.ih
NAME
geotran -- geometrically transform a list of images
.ih
USAGE
geotran input output database transforms
.ih
PARAMETERS
.ls input
List of images to be transformed.
.le
.ls output
List of output images. If the output image name is the same as the input
image name the input image is overwritten. The output image may be a section
of an existing image. The number of output images must equal the number
of input images.
.le
.ls database
The name of the text file containing the coordinate transformation (generally
the database file produced by GEOMAP).
If database is the null string then GEOTRAN will perform a linear
transformation based the values of xin, yin, xout, yout, xshift, yshift,
xmag, ymag, xrotation and yrotation. If all these parameters have their
defaults values the transformation is a null transformation. If the geometric
transformation is linear xin, yin, xout, yout, xshift, yshift, xmag, ymag,
xrotation and yrotation can be used to override the values in the database
file.
.le
.ls transforms
The list of record name(s) in the file \fIdatabase\fR containing the
desired transformations.
This record name is usually the name of the text file input to geomap
listing the reference and input coordinates of the control points.
The number of records must be 1 or equal to the number of input images.
The record names may be listed in a text file 1 record per line.
The transforms parameter is only
requested if database is not equal to the null string.
.le
.ls geometry = "geometric"
The type of geometric transformation. The geometry parameter is
only requested if database is not equal to the null string. The options are:
.ls linear
Perform only the linear part of the geometric transformation.
.le
.ls geometric
Compute both the linear and distortion portions of the geometric correction.
.le
.le
.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF
The minimum and maximum x and y reference values of the output image.
If a database file has been defined xmin, xmax, ymin and ymax
efault to the minimum and maximum values set by
GEOMAP and may be less than but may not exceed those values.
.le
.ls xscale = 1.0, yscale = 1.0
The output picture x and y scales in units of
x and y reference units per output pixel,
e.g  arcsec / pixel or Angstroms / pixel if the reference coordinates
are arcsec or Angstroms. If the reference coordinates are in pixels
then xscale and yscale should be 1.0 to preserve the scale of the reference
image.
If xscale and yscale are undefined (INDEF), xscale and yscale default to the
range of the reference coordinates over the range in pixels.
Xscale and yscale override the values of ncols and nlines.
.le
.ls ncols = INDEF, nlines = INDEF
The number of columns and lines in the output image. Ncols and nlines default
to the size of the input image. If xscale or yscale are defined ncols or nlines
are overridden.
.le
.ls xsample = 1.0, ysample = 1.0
The coordinate surface subsampling factor. The coordinate surfaces are
evaluated at every xsample-th pixel in x and every ysample-th pixel in y.
Transformed coordinates  at intermediate pixel values are determined by
bilinear interpolation in the coordinate surfaces. If the coordinate
surface is of high order setting these numbers to some reasonably high
value is strongly recommended.
.le
.ls interpolant = "linear"
The interpolant used for rebinning the image.
The choices are the following.
.ls nearest
Nearest neighbor.
.le
.ls linear
Bilinear interpolation in x and y.
.le
.ls poly3
Third order polynomial in x and y.
.le
.ls poly5
Fifth order polynomial in x and y.
.le
.ls spline3
Bicubic spline.
.le
.ls sinc
2D sinc interpolation. Users can specify the sinc interpolant width by
appending a width value to the interpolant string, e.g. sinc51 specifies
a 51 by 51 pixel wide sinc interpolant. The sinc width will be rounded up to
the nearest odd number.  The default sinc width is 31 by 31.
.le
.ls lsinc
Look-up table sinc interpolation. Users can specify the look-up table sinc
interpolant width by appending a width value to the interpolant string, e.g.
lsinc51 specifies a 51 by 51 pixel wide look-up table sinc interpolant. The user
supplied sinc width will be rounded up to the nearest odd number. The default
sinc width is 31 by 31 pixels. Users can specify the resolution of the lookup
table sinc by appending the look-up table size in square brackets to the
interpolant string, e.g. lsinc51[20] specifies a 20 by 20 element sinc
look-up table interpolant with a pixel resolution of 0.05 pixels in x and y.
The default look-up table size and resolution are 20 by 20 and 0.05 pixels
in x and y respectively.
.le
.ls drizzle
2D drizzle resampling. Users can specify the drizzle pixel fraction in x and y
by appending a value between 0.0 and 1.0 in square brackets to the
interpolant string, e.g. drizzle[0.5]. The default value is 1.0.
The value 0.0 is increased internally to 0.001. Drizzle resampling
with a pixel fraction of 1.0 in x and y is equivalent to fractional pixel
rotated block summing (fluxconserve = yes) or averaging (flux_conserve = no)  if
xmag and ymag are > 1.0.
.le
.le
.ls boundary = "nearest"
The choices are:
.ls nearest
Use the value of the nearest boundary pixel.
.le
.ls constant
Use a user supplied constant value.
.le
.ls reflect
Generate a value by reflecting about the boundary of the image.
.le
.ls wrap
Generate a value by wrapping around to the opposite side of the image.
.le
.le
.ls constant = 0.0
The value of the constant for boundary extension.
.le
.ls fluxconserve = yes
Preserve the total image flux. The output pixel values are multiplied by
the Jacobian of the coordinate transformation.
.le
.ls xin = INDEF, yin = INDEF
The x and y coordinates in pixel units in the input image which will map to
xout, yout in the output image. If the database file is undefined these
numbers default to the center of the input image. 
.le
.ls xout = INDEF, yout = INDEF
The x and y reference coordinates in the output image which correspond
to xin, yin in the input image. If the database file is undefined, xout and
yout default to the center of the output image reference coordinates.
.le
.ls xshift = INDEF, yshift = INDEF
The shift of the input origin in pixels. If the database file is undefined
then xshift and yshift determine the shift of xin, yin.
.le
.ls xmag = INDEF, ymag = INDEF
The scale factors of the coordinate transformation in units of input pixels
per reference coordinate unit. If database is undefined xmag and ymag
default to 1.0; otherwise xmag and ymag default to the values found
by GEOMAP. If the database file is not null then xmag and ymag override
the values found by GEOMAP.
.le
.ls xrotation = INDEF, yrotation = INDEF
The rotation angles in degrees of the coordinate transformation.
Positive angles are measured counter-clockwise with respect to the x axis.
If database
is undefined then xrotation and yrotation default to 0.0; otherwise
xrotation and yrotation default to the values found by GEOMAP.
If database is not NULL then xrotation and yrotation override the values
found by GEOMAP.
.le
.ls nxblock = 512, nyblock = 512
If the size of the output image is less than nxblock by nyblock then
the entire image is transformed at once. Otherwise the output image
is computed in blocks of nxblock by nxblock pixels.
.le
.ls verbose = yes
Print messages about the progress of the task ?
.le
.ih
DESCRIPTION

GEOTRAN corrects an image for geometric distortion using the coordinate
transformation determined by GEOMAP. The transformation is stored as the
coefficients of a polynomial surface in record \fItransforms\fR,
in the text file \fIdatabase\fR.
The coordinate surface is sampled at every \fIxsample\fR and \fIysample\fR
pixel in x and y.
The transformed coordinates at intermediate pixel values are
determined by bilinear interpolation in the coordinate surface. If
\fIxsample\fR and \fIysample\fR = 1, the coordinate
surface is evaluated at every pixel. Use of \fIxsample\fR and \fIysample\fR
are strongly recommended for large images and high order coordinate
surfaces in order to reduce the execution time.

\fIXmin\fR, \fIxmax\fR, \fIymin\fR and \fIymax\fR define the range of
reference coordinates represented in the output picture. These numbers
default to the minimum and maximum x and y reference values used by GEOMAP,
and may not exceed those values.
The scale and size of the output picture is determined as follows.

.nf
	ncols = ncols (inimage)
	if (xscale == INDEF)
	    xscale = (xmax - xmin ) / (ncols - 1)
	else
	    ncols = (xmax - xmin) / xscale + 1

	nlines = nlines (inimage)
	if (yscale == INDEF)
	    yscale = (ymax - ymin ) / (nlines - 1)
	else
	    nlines = (ymax - ymin) / yscale + 1
.fi

The output image gray levels are determined by interpolating in the input
image at the positions of the transformed output pixels. If the
\fIfluxconserve\fR switch is set the output pixel values are multiplied by
the Jacobian of the transformation.
GEOTRAN uses the routines in the 2-D interpolation package.

The linear portion of the transformation may be altered after the fact
by setting some or all of the parameters \fIxin\fR, \fIyin\fR, \fIxout\fR,
\fIyout\fR, \fIxshift\fR, \fIyshift\fR, \fIxmag\fR, \fIymag\fR, \fIxrotation\fR,
\fIyrotation\fR.
Xin, yin, xshift, yshift, xout and yout can be used to redefine the shift.
Xmag, and ymag can be used to reset the x and y scale of the transformation.
Xrotation and yrotation can be used to reset the orientation of the
transformation.

The output image is computed in \fInxblock\fR by \fInyblock\fR pixel sections.
If possible users should set these numbers to values larger than the dimensions
of the output image to minimize the number of disk reads and writes required
to compute the output image.  If this is not feasible and the image rotation is
small, users should set nxblock to be greater than the number of columns in
the output image, and nyblock to be as large as machine memory will permit.

If the CL environment variable \fInomwcs\fR is "no" then the world
coordinate system of the input image will be modified in the output image
to reflect the effects of the \fIlinear\fR portion of the geometric
transformation operation.
Support does not yet exist in the IRAF world coordinate system interface
for the higher order distortion corrections that GEOTRAN is capable of
performing.

.ih
TIMINGS
It requires approximately 70 and 290 cpu seconds to correct a 512 by 512
square image for geometric distortion using a low order coordinate surface
and bilinear and biquintic interpolation respectively (Vax 11/750 fpa).

.ih
EXAMPLES

1. Register two images by transforming the coordinate system of the input
image to the coordinate system of the reference image. The size of the
reference image is 512 by 512.  The output image scale will be 1.0 and
its size will be determined by the xmin, xmax, ymin, ymax parameters set
in the task GEOMAP. The file "database" containing the record "m51.coo"
was produced by GEOMAP.

.nf
   cl> geomap m51.coo database 1.0 512.0 1.0 512.0
   cl> geotran m51 m51.tran database m51.coo
.fi

2. Repeat the above command but set the output image scale to 2.0 reference
images pixels per output image pixel.

.nf
   cl> geomap m51.coo database 1.0 512.0 1.0 512.0
   cl> geotran m51 m51.tran database m51.coo xscale=2.0 yscale=2.0
.fi

3. Repeat the previous command using an output scale of
2 reference units per pixel and bicubic spline interpolation with no
flux correction. 

.nf
   cl> geomap m51.coo database 1.0 512.0 1.0 512.0
   cl> geotran m51 m51.tran database m51.coo xscale=2. yscale=2. \
   >>> inter=spline3 flux-
.fi

4. Register a list of 512 by 512 pixel square images using the set of
transforms computed by GEOMAP. The input images, output images, and coordinate
lists / transforms are listed in the files inlist, outlist and reclist
respectively.

.nf
   cl> geomap @reclist database 1. 512. 1. 512.
   cl> geotran @inlist @outlist database @reclist
.fi

5. Mosaic 3 512 square images into a larger 512 by 1536 square images after
applying a shift to each input image.

.nf
    cl> geotran image1 outimage[1:512,1:512] "" ncols=512 nlines=1536 \
	xshift=5.0 yshift=5.0
    cl> geotran image2 outimage[1:512,513:1024] "" xshift=10.0 yshift=10.0
    cl> geotran image3 outimage[1:512,1025:1536] "" xshift=15.0 yshift=15.0
.fi

.ih
BUGS
Support does not yet exist in the IRAF world coordinate system interface
for the higher order distortion corrections that GEOTRAN is capable of
performing.

.ih
SEE ALSO
imshift, magnify, rotate, imlintran, geomap, geoxytran, gregister
.endhelp