From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001
From: Joseph Hunkeler <jhunkeler@gmail.com>
Date: Wed, 8 Jul 2015 20:46:52 -0400
Subject: Initial commit

---
 pkg/images/immatch/doc/geotran.hlp | 320 +++++++++++++++++++++++++++++++++++++
 1 file changed, 320 insertions(+)
 create mode 100644 pkg/images/immatch/doc/geotran.hlp

(limited to 'pkg/images/immatch/doc/geotran.hlp')

diff --git a/pkg/images/immatch/doc/geotran.hlp b/pkg/images/immatch/doc/geotran.hlp
new file mode 100644
index 00000000..e3ad15f7
--- /dev/null
+++ b/pkg/images/immatch/doc/geotran.hlp
@@ -0,0 +1,320 @@
+.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
-- 
cgit 

