FORMATS · EXAMPLES · BUGS · SEE_ALSO

## NAME

geoxytran -- geometrically transform a list of coordinates

## USAGE

`geoxytran input output database transforms`

## PARAMETERS

- input
- The list of input coordinate files to be transformed.

- output
- The list of output transformed coordinate files. The number of output files must be one or equal to the number of input files.

- 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.

- 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.

- geometry = "geometric" (linear|geometric)
- The type of geometric transformation. The geometry parameter is
only requested if database is defined. The options are:
- linear
- Perform only the linear part of the spatial transformation.

- geometric
- Compute both the linear and distortion portions of the spatial transformation.

- direction = "forward" (forward|backwards)
- The transformation direction may be "forward" or "backward". The forward direction directly evaluates the database solution. The backward direction iteratively dtermines the coordinate which evaluates to the specified coordinate.

- 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.

- 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.

- 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].

- 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.

- 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.

- xcolumn = 1, ycolumn = 2
- The columns in the input coordinate file containing the x and y coordinates.

- 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.

- 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 the precision of the input coordinates, and the value of the min_sigdigits parameter.

- min_sigdigits = 7
- The minimum precision of the output x and y coordinates.

## DESCRIPTION

GEOXYTRAN applies a coordinate transformation to a list of reference
coordinates in the text file *input*
and writes the transformed
coordinates to the text file *output*
. The input coordinates
are read from, and the output coordinates written to, columns
*xcolumn*
and *ycolumn*
in the input and output
files. The format of the output coordinates can be specified using the
*xformat*
and *yformat*
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 *min_sigdigits*
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 *transforms*
in the database file *database*
computed by GEOMAP, or specified
by the user via the *xref*
, *yref*
, *xmag*
, *ymag*
,
*xrotation*
, *yrotation*
, *xout*
, *yout*
, *xshift*
,
and *yshift*
parameters.

The transformation computed by GEOMAP has the following form.

xout = f (xref, yref) yout = g (xref, yref)

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.

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

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 *xref*
, *yref*
, *xout*
,
*yout*
, *xshift*
, *yshift*
, *xmag*
, *ymag*
, *xrotation*
,
and *yrotation*
. 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.

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)

If the GEOMAP database is undefined then GEOXYTRAN performs a linear
transformation on the input coordinates using the the parameters
*xref*
, *yref*
, *xmag*
, *ymag*
, *xrotation*
,
*yrotation*
, *xout*
, *yout*
, *xshift*
, and
*yshift*
as shown below. Note that in this case xrotation and
yrotation are interpreted as the rotation of the coordinates
themselves not the coordinate axes.

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

## Forward vs. Backward Transformations

The transformation direction is specified by the *direction*
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 **geotran**
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 **geomap**
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 coodinates from the reference image being matched then you
would use the "forward" transformation. If you are not sure then you can
use **tvmark**
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 **geomap**
with the reference and target coordinates reversed.

## 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:

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

## EXAMPLES

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

## BUGS