Ubuntu Manpage: v.rectify - Rectifies a vector by computing a coordinate transformation for each object

NAME

       v.rectify   -  Rectifies a vector by computing a coordinate transformation for each object
       in the vector based on the control points.

KEYWORDS

       vector, rectify, level1, geometry

SYNOPSIS

       v.rectify
       v.rectify --help
       v.rectify [-3orb] input=name output=name   [group=name]    [points=name]    [rmsfile=name]
       [order=integer]    [separator=character]   [--overwrite]  [--help]  [--verbose]  [--quiet]
       [--ui]

   Flags:
       -3
           Perform 3D transformation

       -o
           Perform orthogonal 3D transformation

       -r
           Print RMS errors
           Print RMS errors and exit without rectifying the input map

       -b
           Do not build topology
           Advantageous when handling a large number of points

       --overwrite
           Allow output files to overwrite existing files

       --help
           Print usage summary

       --verbose
           Verbose module output

       --quiet
           Quiet module output

       --ui
           Force launching GUI dialog

   Parameters:
       input=name [required]
           Name of input vector map
           Or data source for direct OGR access

       output=name [required]
           Name for output vector map

       group=name
           Name of input imagery group

       points=name
           Name of input file with control points

       rmsfile=name
           Name of output file with RMS errors (if omitted or ’-’ output to stdout

       order=integer
           Rectification polynomial order (1-3)
           Options: 1-3
           Default: 1

       separator=character
           Field separator for RMS report
           Special characters: pipe, comma, space, tab, newline
           Default: pipe

DESCRIPTION

v.rectify uses control points to calculate a 2D or 3D transformation matrix based on a
first, second, or third order polynomial and then converts x,y(, z) coordinates to
standard map coordinates for each object in the vector map. The result is a vector map
with a transformed coordinate system (i.e., a different coordinate system than before it
was rectified).

The -o flag enforces orthogonal rotation (currently for 3D only) where the axes remain
orthogonal to each other, e.g. a cube with right angles remains a cube with right angles
after transformation. This is not guaranteed even with affine (1st order) 3D
transformation.

Great care should be taken with the placement of Ground Control Points. For 2D
transformation, the control points must not lie on a line, instead 3 of the control points
must form a triangle. For 3D transformation, the control points must not lie on a plane,
instead 4 of the control points must form a triangular pyramid. It is recommended to
investigate RMS errors and deviations of the Ground Control Points prior to
transformation.

2D Ground Control Points can be identified in g.gui.gcp.

3D Ground Control Points must be provided in a text file with the points option. The 3D
format is equivalent to the format for 2D ground control points with an additional third
coordinate:
x y z east north height status
where x, y, z are source coordinates, east, north, height are target coordinates and
status (0 or 1) indicates whether a given point should be used. Numbers must be separated
by space and must use a point (.) as decimal separator.

If no group is given, the rectified vector will be written to the current mapset. If a
group is given and a target has been set for this group with i.target, the rectified
vector will be written to the target location and mapset.

Coordinate transformation and RMSE
The desired order of transformation (1, 2, or 3) is selected with the order option.
v.rectify will calculate the RMSE if the -r flag is given and print out statistcs in
tabular format. The last row gives a summary with the first column holding the number of
active points, followed by average deviations for each dimension and both forward and
backward transformation and finally forward and backward overall RMSE.

2D linear affine transformation (1st order transformation)
x’ = a1 + b1 * x + c1 * y
y’ = a2 + b2 * x + c2 * y

3D linear affine transformation (1st order transformation)
x’ = a1 + b1 * x + c1 * y + d1 * z
y’ = a2 + b2 * x + c2 * y + d2 * z
z’ = a3 + b3 * x + c3 * y + d3 * z The a,b,c,d coefficients are determined by least
squares regression based on the control points entered. This transformation applies
scaling, translation and rotation. It is NOT a general purpose rubber-sheeting, nor is it
ortho-photo rectification using a DEM, not second order polynomial, etc. It can be used if
(1) you have geometrically correct data, and (2) the terrain or camera distortion effect
can be ignored.

Polynomial Transformation Matrix (2nd, 3d order transformation)
v.rectify uses a first, second, or third order transformation matrix to calculate the
registration coefficients. The minimum number of control points required for a 2D
transformation of the selected order (represented by n) is
((n + 1) * (n + 2) / 2) or 3, 6, and 10 respectively. For a 3D transformation of first,
second, or third order, the minimum number of required control points is 4, 10, and 20,
respectively. It is strongly recommended that more than the minimum number of points be
identified to allow for an overly-determined transformation calculation which will
generate the Root Mean Square (RMS) error values for each included point. The polynomial
equations are determined using a modified Gaussian elimination method.

AUTHOR

       Markus Metz

       based on i.rectify

SOURCE CODE