Repatch (from linux) of OSX IRAF

1 files changed, 408 insertions, 0 deletions

diff --git a/pkg/images/immatch/doc/geoxytran.hlp b/pkg/images/immatch/doc/geoxytran.hlp
new file mode 100644
index 00000000..69e8565c
--- /dev/null
+++ b/pkg/images/immatch/doc/geoxytran.hlp
@@ -0,0 +1,408 @@
+.help geoxytran Apr95 images.immatch
+.ih
+NAME
+geoxytran -- geometrically transform a list of coordinates
+.ih
+USAGE
+geoxytran input output database transforms
+.ih
+PARAMETERS
+.ls input
+The list of input coordinate files to be transformed.
+.le
+.ls output
+The list of output transformed coordinate files. The number of output files must
+be one or equal to the number of input files.
+.le
+.ls database
+The name of the text database file written by the geomap task which
+contains the desired spatial transformation.
+If database is undefined geoxytran computes
+a linear transformation using the current
+values of the xref, yref, xout, yout, xshift, yshift, xmag, ymag, xrotation,
+and yrotation parameters.
+.le
+.ls transforms
+The database record containing the desired spatial transformation. 
+The number of records must be one or equal to the number of input coordinate
+files. Transforms is usually the name of the coordinate file that the
+geomap task used to compute the spatial transformation.
+If defined the values of xref, yref, xout, yout, xshift, yshift, xmag, ymag,
+xrotation, and yrotation will supersede the computed values in the
+database file.
+.le
+.ls geometry = "geometric" (linear|geometric)
+The type of geometric transformation. The geometry parameter is
+only requested if database is defined. The options are:
+.ls linear
+Perform only the linear part of the spatial transformation.
+.le
+.ls geometric
+Compute both the linear and distortion portions of the spatial transformation.
+.le
+.le
+.ls direction = "forward" (forward|backward)
+The transformation direction may be "forward" or "backward".  The forward
+direction directly evaluates the database solution.  The backward
+direction iteratively determines the coordinate which evaluates to the
+specified coordinate.
+.le
+.ls xref = INDEF, yref = INDEF
+The x and y coordinates of the reference origin.
+If the database file is undefined xref and
+yref  default to [0.0,0.0]. Otherwise xref and yref
+default to the mean of minimum and maximum x and y values
+[(xmin + xmax) / 2.0, (ymin + ymax) / 2.0] computed by geomap.
+.le
+.ls xmag = INDEF, ymag = INDEF
+The x and y scale factors in input units
+per reference unit. If database is undefined xmag and ymag
+default to [1.0, 1.0]. Otherwise xmag and ymag default to the values computed
+by geomap. 
+.le
+.ls xrotation = INDEF, yrotation = INDEF
+The x and y rotation angles in degrees measured counter-clockwise with
+respect to the x and y axes. If database
+is undefined then xrotation and yrotation are interpreted as the
+rotation of the coordinates with respect to the x and y axes and
+default to [0.0, 0.0]. For example xrotation and yrotation values of
+[30.0, 30.0] will rotate a point 30 counter-clockwise with respect
+to the x and y axes.  Otherwise xrotation and yrotation default to the
+values computed by geomap. Geomap computes the x and y rotation angles
+of the x and y axes, not the rotation angle of the coordinates. An output
+coordinate system rotated 30 degrees counter-clockwise with respect
+to the reference coordinate system will produce xrotation and yrotation
+values of [330.0,330.0] or equivalently [-30.0,-30.0] in the database file
+not [30.0,30.0].
+.le
+.ls xout = INDEF, yout = INDEF
+The x and y coordinates of the output origin.
+If the database file is undefined xout and
+yout  default to [0.0,0.0].
+If database is defined xout and yout
+default to the position that the reference origin [xref,yref]
+occupies in the transformed system.
+.le
+.ls xshift = INDEF, yshift = INDEF
+The x and y shift of the reference origin in output units.
+If the database file is undefined xshift and yshift default to [0.0,0.0].
+If the database file is defined xshift and yshift default to the
+values computed by geomap. If defined xshift and yshift take precedence over
+the x and y shifts determined from xref, yref, xout and yout.
+.le
+.ls xcolumn = 1, ycolumn = 2
+The columns in the input coordinate file containing the x and y coordinates.
+.le
+.ls calctype = "real"
+The precision of the coordinate transformation calculations. The options
+are "real" and "double".  Note that this only applies to a "forward"
+transformation.  The "backward" transformation is done iteratively and
+is always calculated in double precision to get the best convergence.
+.le
+.ls xformat = "", yformat = ""
+The default output format for the computed x and y coordinates. If
+xformat and yformat are undefined geoxytran outputs the coordinates
+using the maximum of the precision of the input coordinates
+and the value of the \fImin_sigdigits\fR parameter.
+.le
+.ls min_sigdigits = 7
+The minimum precision of the output x and y coordinates.
+.le
+
+.ih
+DESCRIPTION
+
+GEOXYTRAN applies  a coordinate transformation to a list of reference
+coordinates in the text file \fIinput\fR and writes the transformed
+coordinates to the text file \fIoutput\fR. The input  coordinates
+are read from, and the output coordinates written to, columns
+\fIxcolumn\fR and \fIycolumn\fR in the input and output
+files. The format of the output coordinates can be specified using the
+\fIxformat\fR and \fIyformat\fR parameters. If the output formats
+are unspecified the coordinates are written out with a precision
+which is the maximum of the precision of the input coordinates
+and the value of the \fImin_sigdigits\fR parameter. All remaining fields in
+the input file are copied to the output file without modification.
+Blank lines and comment lines are also passed to the output file
+unaltered.
+
+The coordinate transformation either be read from record \fItransforms\fR
+in the database file \fIdatabase\fR computed by GEOMAP, or specified
+by the user via the \fIxref\fR, \fIyref\fR, \fIxmag\fR, \fIymag\fR,
+\fIxrotation\fR, \fIyrotation\fR, \fIxout\fR, \fIyout\fR, \fIxshift\fR,
+and \fIyshift\fR parameters.
+
+The transformation computed by GEOMAP has the following form.
+
+.nf
+	xout = f (xref, yref)
+	yout = g (xref, yref)
+.fi
+
+The functions f and g are either a power series polynomial or a Legendre
+or Chebyshev polynomial surface whose order and region of validity were
+set by the user when GEOMAP was run. The computed transformation is
+arbitrary and does not correspond to any physically meaningful model.
+However the first order terms can be given the simple geometrical
+interpretation shown below.
+
+.nf
+	xout = a + b * xref + c * yref
+	yout = d + e * xref + f * yref
+	   b = xmag * cos (xrotation)
+	   c = ymag * sin (yrotation)
+	   e = -xmag * sin (xrotation)
+	   f = ymag * cos (yrotation)
+	   a = x0 - b * xref0 - c * yref0 = xshift
+	   d = y0 - e * xref0 - f * yref0 = xshift
+.fi
+
+Xref0, yref0, x0, and
+y0 are the origins of the reference and output coordinate systems
+respectively. xmag and ymag are the x and y scale factors in output units
+per reference unit and xrotation and yrotation are the rotation angles measured
+counter-clockwise of the x and y axes.
+
+The linear portion of the GEOMAP transformation may be altered after the fact
+by setting some or all of the parameters \fIxref\fR, \fIyref\fR, \fIxout\fR,
+\fIyout\fR, \fIxshift\fR, \fIyshift\fR, \fIxmag\fR, \fIymag\fR, \fIxrotation\fR,
+and \fIyrotation\fR. If defined these parameters will replace the corresponding
+values in the GEOMAP database file.
+Xref, yref, xshift, yshift, xout and yout can be used to redefine the shift
+where xshift and yshift take precedence over xref, yref, xout and yout.
+Xmag, and ymag can be used to reset the scale of the transformation.
+Xrotation and yrotation can be used to redefine the orientation of the
+transformation. Note that xrotation and yrotation are interpreted as
+the rotation of the coordinate axes not the coordinates.
+The default values of these parameters are.
+
+.nf
+	  xref = (xmin + xmax) / 2.0
+	  yref = (ymin + ymax) / 2.0
+	  xout = f (xref,yref)
+	  yout = g (xref,yref)
+	xshift = xshift (database) = xout - f(xref,yref)
+	yshift = yshift (database) = yout - g(xref,yref)
+	  xmag = xmag (database)
+	  ymag = ymag (database)
+     xrotation = xrotation (database)
+     yrotation = yrotation (database)
+.fi
+
+If the GEOMAP database is undefined then GEOXYTRAN performs a linear
+transformation on the input coordinates using the parameters
+\fIxref\fR, \fIyref\fR, \fIxmag\fR, \fIymag\fR, \fIxrotation\fR,
+\fIyrotation\fR, \fIxout\fR, \fIyout\fR, \fIxshift\fR, and
+\fIyshift\fR as shown below. Note that in this case xrotation and
+yrotation are interpreted as the rotation of the coordinates
+themselves not the coordinate axes.
+
+.nf
+	xout = a + b * xref + c * yref
+	yout = d + e * xref + f * yref
+	   b = xmag * cos (xrotation)
+	   c = -ymag * sin (yrotation)
+	   e = xmag * sin (xrotation)
+	   f = ymag * cos (yrotation)
+	   a = xo - b * xref0 - c * yref0 = xshift
+	   d = yo - e * xref0 - f * yref0 = xshift
+.fi
+
+
+.ih
+Forward vs. Backward Transformations
+
+The transformation direction is specified by the \fIdirection\fR parameter
+which may take the values "forward" or "backward".  The forward transformation
+is a direct evaluation of the database solution.  The backward
+transformation is an iterative evaluation to obtain the coordinate which
+evaluates to the desired coordinate.
+
+When the same solution is used with \fBgeotran\fR to transform an image
+to another image matching the "reference" image is needed to obtain
+coordinates in the transformed image.  This is because the transformation
+is produced with \fBgeomap\fR to map "reference" coordinates to the
+image which is subsequently transformed.  Therefore, if you have coordinates
+in the image which has been transformed then you should use the "backward"
+transformation to get coordinates for the transformed image.  But if you
+have standard coordinates from the reference image being matched then you
+would use the "forward" transformation.  If you are not sure then you can
+use \fBtvmark\fR to overlay the results to find which direction produces
+the desired coordinates.
+
+Because the backward transformation is performed iteratively it can be
+slow.  If higher speeds are desired, such as when evaluating a very
+large number of coordinates, one might create a transformation solution
+that can be evaluated in the forward direction.  This is done by
+using \fBgeomap\fR with the reference and target coordinates reversed.
+
+.ih
+FORMATS
+
+A  format  specification has the form "%w.dCn", where w is the field
+width, d is the number of decimal places or the number of digits  of
+precision,  C  is  the  format  code,  and  n is radix character for
+format code "r" only.  The w and d fields are optional.  The  format
+codes C are as follows:
+   
+.nf
+b       boolean (YES or NO)
+c       single character (c or '\c' or '\0nnn')
+d       decimal integer
+e       exponential format (D specifies the precision)
+f       fixed format (D specifies the number of decimal places)
+g       general format (D specifies the precision)
+h       hms format (hh:mm:ss.ss, D = no. decimal places)
+m       minutes, seconds (or hours, minutes) (mm:ss.ss)
+o       octal integer
+rN      convert integer in any radix N
+s       string (D field specifies max chars to print)
+t       advance To column given as field W
+u       unsigned decimal integer
+w       output the number of spaces given by field W
+x       hexadecimal integer
+z       complex format (r,r) (D = precision)
+   
+   
+Conventions for w (field width) specification:
+   
+    W =  n      right justify in field of N characters, blank fill
+        -n      left justify in field of N characters, blank fill
+        0n      zero fill at left (only if right justified)
+absent, 0       use as much space as needed (D field sets precision)
+   
+Escape sequences (e.g. "\n" for newline):
+   
+\b      backspace   (not implemented)
+\f      formfeed
+\n      newline (crlf)
+\r      carriage return
+\t      tab
+\"      string delimiter character
+\'      character constant delimiter character
+\\      backslash character
+\nnn    octal value of character
+   
+Examples
+   
+%s          format a string using as much space as required
+%-10s       left justify a string in a field of 10 characters
+%-10.10s    left justify and truncate a string in a field of 10 characters
+%10s        right justify a string in a field of 10 characters
+%10.10s     right justify and truncate a string in a field of 10 characters
+   
+%7.3f       print a real number right justified in floating point format
+%-7.3f      same as above but left justified
+%15.7e      print a real number right justified in exponential format
+%-15.7e     same as above but left justified
+%12.5g      print a real number right justified in general format
+%-12.5g     same as above but left justified
+
+%h          format as nn:nn:nn.n
+%15h        right justify nn:nn:nn.n in field of 15 characters
+%-15h       left justify nn:nn:nn.n in a field of 15 characters
+%12.2h      right justify nn:nn:nn.nn
+%-12.2h     left justify nn:nn:nn.nn
+   
+%H          / by 15 and format as nn:nn:nn.n
+%15H        / by 15 and right justify nn:nn:nn.n in field of 15 characters
+%-15H       / by 15 and left justify nn:nn:nn.n in field of 15 characters
+%12.2H      / by 15 and right justify nn:nn:nn.nn
+%-12.2H     / by 15 and left justify nn:nn:nn.nn
+
+\n          insert a newline
+.fi
+
+.ih
+EXAMPLES
+
+.nf
+1. Compute the transformation from the reference system to the output
+system and then evaluate the transformation for both the input list and
+the list of unknowns.
+
+   cl> type rtran
+
+	1.0000  1.0000 184.1445 -153.0376
+	512.0000 1.0000 684.0376 184.1445
+	512.0000 512.0000 346.8555 684.0376
+	1.0000 512.0000 -153.0380 346.8555
+
+    cl> geomap rtran rtran.db 1.0 512.0 1.0 512.0 intera-
+
+    cl> type rtran.db
+
+	# Tue 14:53:36 18-Apr-95
+	begin	rtran
+		output		rtran.db
+		xrefmean	256.5
+		yrefmean	256.5
+		xmean		265.4999
+		ymean		265.5
+		xshift		183.826
+		yshift		-154.6757
+		xmag		1.180001
+		ymag		1.179999
+		xrotation	326.
+		yrotation	326.
+		surface1	11
+				3.	3.
+				2.	2.
+				2.	2.
+				0.	0.
+				1.	1.
+				512.	512.
+				1.	1.
+				512.	512.
+				183.826	-154.6757
+				0.9782647	0.6598474
+				-0.6598479	0.9782643
+	    	surface2	0
+
+    cl> geoxytran rtran STDOUT rtran.db rtran
+
+	184.1444 -153.038 184.1445 -153.0376
+	684.0377 184.1444 684.0376 184.1445
+	346.8554 684.0375 346.8555 684.0376
+	-153.038 346.8555 -153.038 346.8555
+
+    cl> geoxytran unknowns unknowns.tran rtran.db rtran
+
+
+2.  Evaluate the backward transformation to take coordinates from the
+output system to the reference system.  In this example we use the
+output of the first example to illustrate getting back the coordinates
+used in the original geomap input.
+
+    cl> geoxytran rtran STDOUT rtran.db rtran dir=forward |\
+    >>> geoxytran STDIN STDOUT rtran.db rtran dir=backward
+    0.999798 0.9997257 184.1445 -153.0376
+        512. 0.9999674 684.0376 184.1445
+	512.     512. 346.8555 684.0376
+    0.999918 512.0001 -153.0380 346.8555
+
+
+3. Evaluate the transform computed in example 1 for the same list of
+unknowns but modify the transformation slightly by setting xmag
+and ymag to 1.18 and 1.18 exactly.
+
+    cl> geoxytran unknowns unknowns.tran rtran.db rtran xmag=1.18 \
+	ymag=1.18
+
+
+4. Evaluate the same transformation for the same unknowns as before
+using the linear transformation parameters not the transform computed
+by geomap. Note that the angle is the negative of the one defined
+in the database file.
+
+    cl> geoxytran unknowns unknowns.tran "" xmag=1.18 ymag=1.18 \
+        xrot=34 yrot=34 xshift=183.826 yshift=-154.6757
+.fi
+
+.ih
+BUGS
+
+.ih
+SEE ALSO
+geomap, lists.lintran, geotran, gregister
+.endhelp