.TH i.rectify 1grass "" "GRASS 6.4.4" "Grass User's Manual"
.SH NAME
\fI\fBi.rectify\fR\fR  - Rectifies an image by computing a coordinate transformation for each pixel in the image based on the control points.
.SH KEYWORDS
imagery, rectify
.SH SYNOPSIS
\fBi.rectify\fR
.br
\fBi.rectify help\fR
.br
\fBi.rectify\fR [\-\fBca\fR] \fBgroup\fR=\fIname\fR  [\fBinput\fR=\fIname\fR[,\fIname\fR,...]]  \fBextension\fR=\fIstring\fR \fBorder\fR=\fIinteger\fR  [\fBres\fR=\fIfloat\fR]   [\fBmemory\fR=\fImemory in MB\fR]   [\fBmethod\fR=\fIstring\fR]   [\-\-\fBverbose\fR]  [\-\-\fBquiet\fR] 
.SS Flags:
.IP "\fB\-c\fR" 4m
.br
Use current region settings in target location (def.=calculate smallest area)
.IP "\fB\-a\fR" 4m
.br
Rectify all raster maps in group
.IP "\fB\-\-verbose\fR" 4m
.br
Verbose module output
.IP "\fB\-\-quiet\fR" 4m
.br
Quiet module output
.PP
.SS Parameters:
.IP "\fBgroup\fR=\fIname\fR" 4m
.br
Name of input imagery group
.IP "\fBinput\fR=\fIname[,\fIname\fR,...]\fR" 4m
.br
Name of input raster map(s)
.IP "\fBextension\fR=\fIstring\fR" 4m
.br
Output raster map(s) suffix
.IP "\fBorder\fR=\fIinteger\fR" 4m
.br
Rectification polynom order (1-3)
.IP "\fBres\fR=\fIfloat\fR" 4m
.br
Target resolution (ignored if \-c flag used)
.IP "\fBmemory\fR=\fImemory in MB\fR" 4m
.br
Amount of memory to use in MB
.br
Default: \fI300\fR
.IP "\fBmethod\fR=\fIstring\fR" 4m
.br
Interpolation method to use
.br
Options: \fInearest,bilinear,cubic,bilinear_f,cubic_f\fR
.br
Default: \fInearest\fR
.PP
.SH DESCRIPTION
\fIi.rectify\fR uses the control
points identified in 
\fIi.points\fR
or
\fIi.vpoints\fR
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).
.PP
\fIi.points\fR
or
\fIi.vpoints\fR
must be run before \fIi.rectify\fR, 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 \fIi.rectify\fR, the rectified image is
deposited in the target standard coordinate LOCATION. This
LOCATION is selected using
\fIi.target\fR.
.SH Program Prompts
The first prompt in the program asks for the name of
the group containing the files to be rectified.
\fC
.DS
.br
     Enter the group containing files to be rectified
.br
     Enter 'list' for a list of existing imagery groups
.br
     Enter 'list \-f' for a verbose listing
.br
     Hit RETURN to cancel request
.br
     >
.br
.DE
\fR
This is the same imagery group that was selected in 
\fIi.points\fR
or
\fIi.vpoints\fR
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:
\fC
.DS
.br
Please select the file(s) to rectify by naming an output file
.br
.br
       spot1.1 in mapsetname      .............
.br
       spot1.2 in mapsetname      .............
.br
       spot1.3 in mapsetname      .............
.br
       spotclass1 in mapsetname   spotrectify1.
.br
    
.br
       spotreject1 in mapsetname  .............
.br
.br
(enter list by any name to get a list of existing raster maps)
.br
.br
AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE
.br
           (OR<Ctrl-C> TO CANCEL)
.br
.DE
\fR
More than one raster map may be rectified at a time.  Each
cell file should be given a unique output file name.
.PP
Next, you are asked to select one of two windows regions:
\fC
.DS
.br
  Please select one of the following options
.br
  1.  Use the current window in the target location
.br
  2.  Determine the smallest window which covers the image
.br
  >
.br
.DE
\fR
The \fIi.rectify\fR 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.
.PP
If you are rectifying a file with plans to patch it to
another file using the GRASS program \fIr.patch\fR,
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.
.PP
Select the order of transformation desired with the \fBorder\fR option:
\fC
.DS
.br
   1st Order   2nd Order  3rd Order
.br
.DE
\fR
The program will immediately recalculate the RMSE and the
number of points required.
.SS Linear affine transformation (1st order transformation)
.br
 x' = ax + by +c
.br
 y' = Ax + Bt +C
.PP
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.
.SS 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
.br
((n + 1) * (n + 2) / 2) 
.PP
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.
.SS Resampling method
.PP
The rectified data is resampled with one of five different methods: 
\fInearest\fR, \fIbilinear\fR, \fIcubic\fR, \fIbilinear_f\fR
or \fIcubic_f\fR.
.PP
The \fImethod=nearest\fR 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 \fImethod=bilinear\fR method determines the new
value of the cell based on a weighted distance average of the 4 surrounding
cells in the input map. The \fImethod=cubic\fR method determines the new value of
the cell based on a weighted distance average of the 16 surrounding cells in
the input map. The \fImethod=lanczos\fR method determines the new value of
the cell based on a weighted distance average of the 25 surrounding cells in
the input map.
.PP
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.
.PP
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.
.PP
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.
.SS 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.
.PP
.SH NOTES
\fIi.rectify\fR 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 \fIi.rectify\fR rearranges the
geometry of the image pixels.
.PP
If \fIi.rectify\fR starts normally but after some time the following text is seen:
.br
GIS ERROR: error while writing to temp file
.br
the user may try the flag \fI-c\fR (or the module needs more free space
on the hard drive).
.SH SEE ALSO
The GRASS 4 \fI
Image
Processing manual\fR
.PP
\fI
g.transform,
r.proj,
v.proj,
i.group,
i.points,
i.vpoints,
i.target
\fR
.br
\fIgis.m: GEORECTIFY TOOL\fR and
\fIwxGUI: Manage Ground Control Points\fR
.SH AUTHORS
William R. Enslin, 
Michigan State University,
Center for Remote Sensing
.PP
Modified for GRASS 5.0 by:
.br
Luca Palmeri (palmeri@ux1.unipd.it)
.br
Bill Hughes
.br
Pierre de Mouveaux (pmx@audiovu.com)
.br
CMD mode by Bob Covill
.PP
\fILast changed: $Date: 2011-11-08 12:29:50 +0100 (Tue, 08 Nov 2011) $\fR
.PP
Full index
.PP
© 2003-2014 GRASS Development Team