geoxytran: Transform coordinate lists using the geomap transforms

Package: immatch

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

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 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 = x0 - b * xref0 - c * yref0 = xshift
   d = y0 - 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 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 coordinates 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)
     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