Geografic-Information-System/imagery/i.vpoints/i.vpoints.html

<h2>DESCRIPTION</h2>

This program enables the user to identify coordinate pairs of points from a
vector map or keyboard entry and corresponding points in an image to be
rectified. The map coordinate values of each point are used to calculate a
transformation matrix.  The operator may then use the 
<em><a href="i.rectify.html">i.rectify</a></em> program to rectify the image using
the transformation matrix coefficients calculated from the control point
file created in <em>i.vpoints</em>.  The
<em> <a href="i.rectify.html">i.rectify</a></em> program performs a first, second or
third order transformation of the image.

<p>The first step is to display the unrectified image and
corresponding vector map data.  The operator would then
mark corresponding control point locations on the image and
map. To identify the precise location of a point to be
marked, <em>i.vpoints</em> has a zoom option.  In addition to
marking control points on an image to be rectified and
inputting their world coordinate values using the
keyboard,  <em>i.vpoints</em> has the option to simultaneously
display vector map data available in the targeted database,
and identify on the vector map the location of the
corresponding marked points.  When this option is chosen,
the coordinate values are input automatically.  Any GRASS
map layer or vector map in the targeted database LOCATION
can be displayed using <em>i.vpoints</em>.  The <em>i.vpoints</em> program
also has the capability of overlaying (i.e., warping) the
vector data onto the raster image to visually check the
accuracy of the registration based on the current set of
active control points.  During the process of marking
points and entering map coordinates, the user can compute
the RMS (root mean square) error for each point entered.
The <em>i.vpoints</em>  program does this by calculating a
transformation equation (the same one that is calculated in
the GRASS program

<a href="i.rectify.html">i.rectify</a>
2).  Coefficients are
computed for the equation.  The coefficients are then used in the
equation along with the x,y coordinates of the marked points.  The
results are plugged into an equation for RMS error.  The
interpretation of RMS error is described in the ANALYZE subsection.


<p>The procedures for marking control points (registration
points), displaying vector map layers,  overlaying vector maps onto
the raster image, and calculating RMS error are described in the
following sections .


<p>To enter the program (the <em>i.vpoints</em> program requires the use of a
graphics monitor) type <em>i.vpoints</em>:


<dl>
     <dd><b>i.vpoints</b>
</dl>

The first prompt in the program asks for the imagery group to
be registered . . .


<pre>
     Enter imagery group to be registered
     Enter 'list' for a list of existing imagery groups
     Enter 'list -f' for a verbose listing
     Hit RETURN to cancel request
     &gt;
</pre>

For example,   

<dl>
<dd>&gt;<b>list</b>     
</dl>

might produce the following response:

<pre>
     &lt;list&gt;
     Available groups
     - - - - - - - - - - - - - - - - - - - - - - - - - -
     test
     - - - - - - - - - - - - - - - - - - - - - - - - - -
     hit RETURN to continue --&gt;
</pre>
whereas,  
<dl>
<dd>&gt;<b>list -f</b>       
</dl>

might produce the following response

<pre>
     Available groups
     - - - - - - - - - - - - - - - - - - - - - - - - - -
     test
         photo in PERMANENT
         res2 in tifftest
     - - - - - - - - - - - - - - - - - - - - - - - - - -
     hit RETURN to continue --&gt;
</pre>

The imagery group entered above should contain the files
that you wish to rectify.  After entering the group to be
registered, the terminal screen displays the message:
<pre>
     &gt;test
     &lt;test&gt;
     Use mouse now . . .
</pre>
And the color graphics monitor displays the following
screen:

<p>     Any single file in the imagery group may be used to mark
points, and points can be marked on more than one file in the
imagery group to accumulate the suggested minimum number of points
(3 for a 1st order transformation, 6 for a 2nd order, and 10 for a
3rd order).  Any file in the imagery group can be subsequently
rectified (using <em><a href="i.rectify.html">i.rectify</a></em>)
based on the transformation matrix computed from these points.

<p>     The chosen file is displayed in the upper left quadrant of the
monitor at a default magnification based on the extent of the
current active window.

<p>
<b>RASTER IMAGE</b>

<p>     The raster image option on the menu at the bottom of the
window allows the user to display any single file in the imagery
group in the upper right quadrant of the window screen.  The option
provides the same file selection pick list as is presented when you
first enter the <em>i.vpoints</em> program.  When you select this option,
the program will erase the data contained in all of the four
quadrant windows and will reinitialize all program values.


<p>
<b>VECTOR MAPS</b>
<p>     The vector maps option on the menu at the bottom of the screen
allows the user to display vector map data in the upper right
quadrant of the screen.  After selecting the vector map layer to
display, a menu selection bar appears along the bottom on the
screen. This pick list is used to select the line color (blue,
gray, green, red, white, or yellow) for the selected vector data
layer.
<p><b>Refresh</b>
<p>     The refresh option on the main menu allows the user to
"refresh" or re-draw the displayed vector data. This function will
erase all outlines showing the limits of previously zoomed areas. 
A "yes/no" roompt will appear:
<pre>
     Refresh Map ?       NO   YES
</pre>
<p><b>Zoom</b>
<p>     To enlarge a raster or vector image, place the mouse cross
hairs on the word zoom on the main menu and press the left button. 
The following menu will be displayed at the bottom. of the screen:
<pre>
     CANCEL   BOX   POINT      Select type of zoom
</pre>
You have the option to identify the map extent of the zoom window
using either the mouse to define a box, or the mouse to mark a
center point from which to enlarge the image.  The box option first
prompts you to identify a starting corner for the zoom region and
then allows you to define the area to be zoomed using a rubber band
box.  The prompts appear as follows...
<pre>
     CANCEL    Mark the first corner of region

     CANCEL     Define the region
</pre>
After marking the first corner of the region to be enlarged, hold
down the left button and move the mouse to change the size and
shape of the rubber band box.  After defining the area to be
enlarged, press the right button  to accept it.


<p>
The point method for enlarging an image will display a mouse menu
to guide you in selecting the appropriate enlargement.  To enlarge
or reduce the magnification factor, place the cursor on the "+" or
"-" box and press the left button on the mouse.
<p><p>You may zoom either the raster or the vector display.
<p>Upon accepting the new region limits, the raster or vector data are
redisplayed in either the lower left (raster) or lower right
(vector) windows.
<p>The extent of the zoomed area is outlined on the unzoomed image in
the main window area.
<p>     While the main menu is displayed,  you can mark
corrosponding control points on the raster and vector
images or enter map coordinates from the keyboard.  If you
are using coordinates taken from a reference map, circle
these points and then use whatever means you have available
to identify as precisely as possible the coordinate values
for these points.  Digitizing software is recommended,
especially <a href="wxGUI.vdigit.html">wxGUI vector digitizer</a>. Once you have
determined the standard coordinates (for example, UTM's) of
each circled point, you are ready to mark the points on the
displayed image.
<p>     To mark the points on the image, that correspond to the points
on the standard coordinate map, place the mouse cross hairs on the
point on the image to be marked (you will probably have to ZOOM to
find the exact spot) and press the left hand button on the mouse. 
A diamond shaped symbol will be marked on the image.  The text
monitor will display the following screen:
<pre>
          Point 1 marked on the image at
          East:  1023.77
          North:  -164.41

          Enter coordinates as east north:
</pre>
<b>Analyze</b>
<p>
     After a number of points have been marked (a minimum of 4 for
a 1st order transformation, 7 for a 2nd order, and 11 for a 3rd
order), the RMS error of the points marked on the image can be
checked.  This is done by placing the cross hairs on the word
ANALYZE on the main menu at the bottom of the monitor.  The
following error report is superimposed on the monitor:
<pre>

   error                      image                target
  #    col  row target   east      north       east      north 
     
  1   -0.9  0.0  1.0   1048.5     -144.8   679132.5  4351080.6
  2    1.0  0.4  1.3   2153.1     -567.2   684314.7  4399001.4
  .
  .
  .
          Overall rms error  76.85
</pre>

     The RMS error for the image being rectified is recorded under
the column "error" and subTITLEd "row' and "col".  In the above
report, the marked point number 1 is 0.0 rows and -0.9 columns from
the predicted location calculated by the transformation equation.
     The RMS error for the target database map is recorded under
the heading "error"  and the subheading "target".  This is the RMS
error for the east and the north coordinate values of the target
map, but it is represented in the table using one general value.
     The overall RMS error for the image is displayed at the bottom
of the screen in meters.  Points that generate a high RMS error are
displayed in red on the monitor.
     The x,y coordinate values of the point marked on the image
being rectified are recorded under the heading "image" and the
subheadings "east" and "north".
     The standard coordinate values of the point in the target
database are recorded under the heading "target" and the
subheadings "east" and "north".
     If the user would like to exclude or include a point, this can
be accomplished by placing the mouse cross hairs on the point
number to be included (if the point is absent) or excluded (if the
point is displayed) and then pressing the left button on the mouse
twice.  When a point is excluded, it is not included in the
calculation of the RMS error, or included in the final
transformation matrix.  However, it can be retrieved within
<em>i.vpoints</em> at any time by double clicking with the mouse as
described above.
<p>The following menu appears at the bottom of the monitor:
<pre>
   DONE   PRINT   FILE   OVERLAY   DELETE ON       Transformation -
-&gt;   1st ORDER   Double click on point to be DELETED
</pre>
Selecting DELETE ON will toggle the option to DELETE OFF, the
toggle option is used to allow the user to physically remove a
control point from the POINTS file instead of just flagging it as
an non-active reference point.
<p><b>Overlay</b>
<p>Overlay allows the user to overlay the vector map(s) onto the
raster image.  Overlay can be used to warp (register) and display
the selected vector map data on top of the raster image contained
in the upper left window of the color screen.  An inverse
coordinate transformation is performed using the currently active
order of transformation (i.e., first, second, or third).
<pre>
     Overlay vectors on raster image   NO   YES
</pre>
By selecting the 1st ORDER option, the user may select the order of
transformation desired:
<pre>
     Select order of transformation --&gt; 1st Order 2nd Order 3rd Order
</pre>
The program will immediately recalculate the RMSE and the number of
points required.
<p><b>Quit</b>
<p>     To exit the <em>i.vpoints</em> program, place the mouse cross hairs on
the word QUIT at the bottom of the monitor and all of the marked
points (including coordinates) will be saved.

<h2>SEE ALSO</h2>

The GRASS 4 <em>
<a href="http://grass.itc.it/gdp/imagery/grass4_image_processing.pdf">Image
Processing manual</a></em>

<p><em>
<a href="g.mapsets.html">g.mapsets</a><br>
<a href="i.group.html">i.group</a><br>
<a href="i.points.html">i.points</a><br>
<a href="i.rectify.html">i.rectify</a><br>
<a href="i.target.html">i.target</a>
</em><br>
<em><a href="gm_georect.html">gis.m: GEORECTIFY TOOL</a></em>


<h2>AUTHOR</h2>

William R. Enslin, Michigan State University Center for Remote Sensing<br>
Radim Blazek (update to GRASS 5.7)<br>
Hamish Bowman (finish GRASS 6 porting)
<p><i>Last changed: $Date$</i>