Ubuntu Manpage: i.rectify - Rectifies an image by computing a coordinate transformation for each pixel in the image

NAME

       i.rectify   -  Rectifies  an  image  by computing a coordinate transformation for each pixel in the image
       based on the control points.

KEYWORDS

       imagery, rectify

SYNOPSIS

       i.rectify
       i.rectify help
       i.rectify  [-ca]  group=name   [input=name[,name,...]]    extension=string   order=integer    [res=float]
       [memory=memory in MB]   [method=string]   [--verbose]  [--quiet]

   Flags:
       -c
           Use current region settings in target location (def.=calculate smallest area)

       -a
           Rectify all raster maps in group

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       group=name
           Name of input imagery group

       input=name[,name,...]
           Name of input raster map(s)

       extension=string
           Output raster map(s) suffix

       order=integer
           Rectification polynom order (1-3)

       res=float
           Target resolution (ignored if -c flag used)

       memory=memory in MB
           Amount of memory to use in MB
           Default: 300

       method=string
           Interpolation method to use
           Options: nearest,bilinear,cubic,bilinear_f,cubic_f
           Default: nearest

DESCRIPTION

       i.rectify  uses  the  control  points  identified  in i.points or i.vpoints to calculate a transformation
       matrix based on a first, second, or third order polynomial and then  converts  x,y  cell  coordinates  to
       standard  map  coordinates  for  each  pixel  in  the  image.  The  result  is a planimetric image with a
       transformed coordinate system (i.e., a different coordinate system than before it was rectified).

       i.points or i.vpoints must be run before i.rectify, and both programs are required to rectify  an  image.
       An  image  must  be  rectified  before  it can reside in a standard coordinate LOCATION, and therefore be
       analyzed with the other map layers in the standard coordinate LOCATION. Upon completion of i.rectify, the
       rectified image is deposited in the target standard coordinate LOCATION. This LOCATION is selected  using
       i.target.

Program Prompts

The first prompt in the program asks for the name of the group containing the files to be rectified.
Enter the group containing files to be rectified
Enter 'list' for a list of existing imagery groups
Enter 'list -f' for a verbose listing
Hit RETURN to cancel request
>
This is the same imagery group that was selected in i.points or i.vpoints and the group that contains
the raster maps with the marked points and their associated map coordinates. You are then asked to
select the raster map(s) within the group to be rectified:
Please select the file(s) to rectify by naming an output file
spot1.1 in mapsetname .............
spot1.2 in mapsetname .............
spot1.3 in mapsetname .............
spotclass1 in mapsetname spotrectify1.

spotreject1 in mapsetname .............
(enter list by any name to get a list of existing raster maps)
AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE
(OR<Ctrl-C> TO CANCEL)
More than one raster map may be rectified at a time. Each cell file should be given a unique output
file name.

Next, you are asked to select one of two windows regions:
Please select one of the following options
1. Use the current window in the target location
2. Determine the smallest window which covers the image
>
The i.rectify program will only rectify that portion of the image or raster map that occurs within the
chosen window region, and only that portion of the cell file will be relocated in the target database.
It is important therefore, to check the current mapset window in the target LOCATION if choice number one
is selected.

If you are rectifying a file with plans to patch it to another file using the GRASS program r.patch,
choose option number one, the current window in the target location. This window, however, must be the
default window for the target LOCATION. When a file being rectified is smaller than the default window
in which it is being rectified, zeros are added to the rectified file. Patching files of the same size
that contain 0/non-zero data, eliminates the possibility of a no-data line the patched result. This is
because, when the images are patched, the zeros in the image are "covered" with non-zero pixel values.
When rectifying files that are going to be patched, rectify all of the files using the same default
window.

Select the order of transformation desired with the order option:
1st Order 2nd Order 3rd Order
The program will immediately recalculate the RMSE and the number of points required.

Linear affine transformation (1st order transformation)
x' = ax + by +c
y' = Ax + Bt +C

The a,b,c,A,B,C 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 images, and (2) the terrain or camera distortion effect can be ignored.

Polynomial Transformation Matrix (2nd, 3d order transformation)
The ANALYZE function has been changed to support calculating the registration coefficients using a first,
second, or third order transformation matrix. The number of control points required for a selected order
of transformation (represented by n) is
((n + 1) * (n + 2) / 2)

or 3, 6, and 10 respectively. It is strongly recommended that one or more additional 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 RMS error values for all the included control points are
immediately recalculated when the user selects a different transformation order from the menu bar. The
polynomial equations are performed using a modified Gaussian elimination method.

Resampling method
The rectified data is resampled with one of five different methods: nearest, bilinear, cubic, bilinear_f
or cubic_f.

The method=nearest method, which performs a nearest neighbor assignment, is the fastest of the three
resampling methods. It is primarily used for categorical data such as a land use classification, since it
will not change the values of the data cells. The method=bilinear method determines the new value of the
cell based on a weighted distance average of the 4 surrounding cells in the input map. The method=cubic
method determines the new value of the cell based on a weighted distance average of the 16 surrounding
cells in the input map. The method=lanczos method determines the new value of the cell based on a
weighted distance average of the 25 surrounding cells in the input map.

The bilinear, cubic and lanczos interpolation methods are most appropriate for continuous data and cause
some smoothing. These options should not be used with categorical data, since the cell values will be
altered.

In the bilinear, cubic and lanczos methods, if any of the surrounding cells used to interpolate the new
cell value are NULL, the resulting cell will be NULL, even if the nearest cell is not NULL. This will
cause some thinning along NULL borders, such as the coasts of land areas in a DEM. The bilinear_f,
cubic_f and lanczos_f interpolation methods can be used if thinning along NULL edges is not desired.
These methods "fall back" to simpler interpolation methods along NULL borders. That is, from lanczos to
cubic to bilinear to nearest.

If nearest neighbor assignment is used, the output map has the same raster format as the input map. If
any of the other interpolations is used, the output map is written as floating point.

Program Execution
Note: The rectified image or rectified raster maps will be located in the target LOCATION when the
program is completed. The original unrectified files are not modified or removed.

NOTES

       i.rectify uses nearest neighbor resampling during the transformation choosing the actual pixel  that  has
       its  centre  nearest  to  the  point  location  in  the image. Advantage of this method is that the pixel
       brightness of the image is kept as i.rectify rearranges the geometry of the image pixels.

       If i.rectify starts normally but after some time the following text is seen:
       GIS ERROR: error while writing to temp file
       the user may try the flag -c (or the module needs more free space on the hard drive).

AUTHORS

       William R. Enslin, Michigan State University, Center for Remote Sensing

       Modified for GRASS 5.0 by:
       Luca Palmeri (palmeri@ux1.unipd.it)
       Bill Hughes
       Pierre de Mouveaux (pmx@audiovu.com)
       CMD mode by Bob Covill

       Last changed: $Date: 2011-11-08 03:29:50 -0800 (Tue, 08 Nov 2011) $

       Full index

       © 2003-2013 GRASS Development Team

GRASS 6.4.3                                                                                    i.rectify(1grass)