From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- pkg/images/immatch/doc/geoxytran.hlp | 408 +++++++++++++++++++++++++++++++++++ 1 file changed, 408 insertions(+) create mode 100644 pkg/images/immatch/doc/geoxytran.hlp (limited to 'pkg/images/immatch/doc/geoxytran.hlp') 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 -- cgit