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

<h2>DESCRIPTION</h2>

<em>i.points</em> is an
<a href="imagery.html">imagery</a> function that enables
the user to mark points on a (raster) image to be rectified
and then input the geographic coordinates of each point for
calculation of a coordinate transformation matrix.
<em>i.points</em> must be followed by use of the GRASS
program <em><a href="i.rectify.html">i.rectify</a></em>, which
rectifies the image using the transformation matrix
coefficients calculated by <em>i.points</em>.

<p>
<em>Rectification</em> is the mapping (transformation) of
an image from one coordinate system to another.  The
geometry of an image extracted into a GRASS LOCATION having
an x,y coordinate system is not planimetric.  To create a
planimetric image, that is, to convert the x,y coordinate
system into a standard coordinate system (for example, the
UTM coordinate system or the State Plane coordinate
system), points from a map having the standard coordinates
must be associated with the same points on the image to be
rectified.  <em>i.points</em> enables the user to mark
points on an image and input the standard coordinates for
that point.  <em>i.points</em> then calculates a least
squares regression using the two coordinate systems (x,y
and standard) for the marked points.  A matrix containing
transformation coefficients is the output file for
<em>i.points</em>.

<p>During the process of marking points and entering map
coordinates, the user can compute the RMS (root mean
square) error for each point entered.  <em>i.points</em>
does this by calculating the transformation equation (the
same one that is calculated in the GRASS program <em>
<a href="i.rectify.html">i.rectify</a></em>), and then
plugging these results into an equation for RMS error.

<p><em>i.points</em> offers a zoom option to locate precisely
the point to be marked on an image.  This program also
offers the user the option of acquiring standard
coordinates for a marked point from a map layer in the
target data base.

<p><em><a href="i.target.html">i.target</a></em> must be
run before running <em>i.points</em> to enable the PLOT
RASTER option to be used and to identify a target data base
LOCATION_NAME and MAPSET for the rectified image.  To run
<em>i.points</em>, a graphics monitor is required.

<p>The procedure for marking points, entering coordinates, and
calculating RMS error is described below.

<p>The first prompt in the program asks the user for the 
<a href="i.group.html">imagery group</a> to be
registered.  Note that if 
<em><a href="i.target.html">i.target</a></em> is not run
before <em>i.points</em>, the <em>i.points</em> program
will display the following error message:

<pre>
ERROR: Target information for group [spot] missing
       Please run i.target for group [spot]
</pre>

After entering the group to be registered the terminal screen
displays the message: 

<pre>
      Use mouse now...
</pre>

The graphics monitor displays the following screen:

<pre>
 ______________________________________________________________
| imagery  filename  (mag)        |  target  filename  (mag)  |
|_________________________________|___________________________|
|                                 |                           |
|                                 |                           |
|                                 |                           |
|                                 |                           |
|                                 |                           |
|                                 |                           |
|                                 |                           |
|_________________________________|___________________________|
|                                 |                           |
|                                 |                           |
|                                 |                           |
|                                 |                           |
|                                 |                           |
|                                 |                           |
|                                 |                           |
|_________________________________|___________________________|
| QUIT  ZOOM  PLOT RASTER  ANALYZE|                           |
|_________________________________|___________________________|
</pre>

A pop-down menu like that shown below will be superimposed on the
left half of the screen:


<pre>
        __________________________________
       | Double click on raster map layer|
       |          to be plotted          |
       |   Double click here to cancel   |
       |_________________________________|

               ____________________
              |    Mapset demo    |
              |___________________|
              | spotclass|  spot.1|
              |__________|________|
              | composite|  spot.2|
              |__________|________|
              | spot.3   |        |
              |__________|________|
</pre>

Any single raster map layer in the 

<a href="i.group.html">imagery group</a> may be used on

which to mark points, and the user can mark points on more
than one raster map layer in the 

<a href="i.group.html">imagery group</a> to accumulate the

suggested minimum number of 12 points.  Any raster map
layer in the <a href="i.group.html">imagery group</a>
can be rectified (using 

<em><a href="i.rectify.html">i.rectify</a></em>) based on the
transformation matrix computed from these points.


<p>
The imagery file chosen by
the user is displayed in the upper left quadrant of the
screen.

<h3>ZOOM</h3>

To magnify the displayed file, the user must
place the mouse cross hairs on the word ZOOM.  The following menu
will then be displayed at the bottom of the screen:

<pre>
   ____________________________________________
  | Cancel|  Box|  Point|  Select type of ZOOM|
  |_______|_____|_______|_____________________|
</pre>
 

The user has the option of identifying the zoom region
either by using the mouse to make a box, or by using the
mouse to mark the two diagonal points of the desired
region.  The terminal screen will display a mouse button
menu to guide the user in identifying the corner points of
the region.

<h3>MARKING POINTS</h3>

To mark the points on the image that correspond to the
points on a standard coordinate system map, the user must
place the mouse cross hairs on the corresponding location
on the image to be marked and press the left hand button on
the mouse.  A diamond shaped symbol will be marked on the
image.  The user's terminal will display the following
menu:


<pre>
 ___________________________________________________________
| Point 1 marked on the image at|                          |
| East: 1023.77                 |                          |
| North: -164.41                |                          |
|                               |                          |
|                               |                          |
|                               |                          |
|                               |                          |
|                               |                          |
|__________________________________________________________|
| Enter coordinates as east north:                         |
|__________________________________________________________|
</pre>

The user then enters the easting and northing (separated by
a space) for the point marked on the image.  If the user
wishes not to enter a coordinate, he or she may simply hit
RETURN to return control to the mouse;  the marked point
then disappears.

<h3>PLOT RASTER</h3>

In addition to acquiring reference points from a standard
map, the user has the option of acquiring the reference
points from a raster map layer in the target data base
LOCATION_NAME.  The data base raster map layer is displayed
by placing the mouse cross hairs on the words PLOT RASTER.
The following line is then displayed at the bottom of the
graphics monitor:


<pre>
       ________________________________________________
      | Cancel|  Indicate which side should be plotted|
      |_______|_______________________________________|
</pre>

Which side of the graphics monitor is to be plotted
is indicated by placing the mouse cross hairs on the 
half of the graphics monitor screen that the user would like to use,
and pressing the left mouse button.  The following pop-down
menu will be superimposed on the half of the screen that was chosen:


<pre>
    _________________________________________
   | Double click on raster (cell) map layer|
   |              to be plotted             |
   |       Double click here to cancel      |
   |________________________________________|

          ______________________________
         |         Mapset demo         |
         |_____________________________|
         | tm.rectified |              |
         |______________|______________|
         | tm.classified|              |
         |_____________________________|
         |       Mapset PERMANENT      |
         |_____________________________|
         | elevation    |  geology     |
         |______________|______________|
         | slope        |  soils       |
         |______________|______________|
         | aspect       |              |
         |______________|______________|
         | roads        |              |
         |______________|______________|
</pre>

After the raster map layer is displayed the following message appears
at the bottom of the graphics monitor:


<pre>
     ______________________________________
     | input method --&gt;|  keyboard|  screen|
     |_________________|__________|________|
</pre>

If the user wishes to use the plotted raster map layer only
as a comparative reference, then the keyboard can be chosen
as the means to input coordinates corresponding to the
marked points on the image.  This is done by placing the
mouse cross hairs on the word KEYBOARD and pressing the
left button on the mouse.


<p>
If the user selects the SCREEN option, then points marked
on the image will automatically be associated with the
coordinates from the corresponding points on the target
data base map layer.  In this option, when the user marks a
point on the image, the following menu is displayed at the
terminal:


<pre>
___________________________________________________________
| Point 5 marked on the image at|                          |
| East: 1023.77                 |                          |
| North: -164.41                |                          |
|                               |                          |
|                               |                          |
| Point located at              |                          |
| East: 679132.57               |                          |
| North: 4351080.67             |                          |
|                               |                          |
|                               |                          |
|                               |                          |
|                               |                          |
|                               |                          |
|__________________________________________________________|
| use mouse now...                                         |
|__________________________________________________________|
</pre>


The user then uses the mouse to mark a corresponding point
on the displayed image from the target data base.  The
coordinates for the target data base map layer are
automatically saved as the coordinates corresponding to the
marked point on the image.

<h3>ANALYZE</h3>

After a number of points have been marked (4 to 7), the
user can check the RMS error of the points marked on the
image.  This is done by placing the mouse cross hairs on
the word ANALYZE at the bottom of the graphics monitor.  An
error report resembling that shown below is superimposed on
the graphics monitor:


<pre>
______________________________________________________________________
|         error                 image                 target         |
|#     row     col    target    east    north      east       north  |
|____________________________________________________________________|
|1     0.0     -0.9    1.0     1048.5   -144.8   679132.5   4351080.6|
|2     0.4     1.0     1.3     2153.1   -567.2   684314.7   4399001.4|
|3    -1.2     -0.5     .6     1452.8   -476.5   567841.4   3457682.8|
|4     1.1     0.5     1.3     1034.0   -109.2   677573.8   4352626.4|
|5    -2.7     14.0    14.2    1048.6   -144.9   679132.6   4351080.7|
|                                                                    |
|____________________________________________________________________|
|    overall   rms    error:   4.46                                  |
|____________________________________________________________________|
</pre>
 
The following menu then appears at the bottom of the graphics monitor:

<pre>
 ____________________________________________________________________
| DONE|  PRINT FILE|   Double click on point to be included/excluded|
|_____|____________|________________________________________________|
</pre>

The RMS error for the image is given under the column
TITLEd "error" and subTITLEd "row" and "col".  In the above
report, point number 1 is 0.0 rows and -0.9 columns from
the predicted location calculated from the transformation
equation.  The RMS error for the target raster map layer is
listed under the heading "target".  This is the RMS error
for the east and north coordinates of the target map layer,
but it is presented in the table using one general value.
The overall RMS error is displayed at the bottom of the
screen in meters.  Points that create high RMS error are
displayed in red on the graphics monitor (represented here
in italics).

<p>The location of the point marked on the 
<a href="i.group.html">imagery group</a> file is given
under the heading "image" and the subheadings "east" and
"north".  The location of the point in the target data base
is given 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 pressing the left button on the mouse
twice.  When a point is excluded, it is not afterwards
included in the calculation of the RMS error, or included
in the final transformation matrix.  However, it can be
retrieved within <em>i.points</em> at any time by double
clicking with the mouse as described above.

<h3>QUIT</h3>

To end the <em>i.points</em> program place the mouse cross
hairs on the word QUIT;  the marked points (including
coordinates) will be saved.


<h2>NOTES</h2>

A good rule of thumb is to mark at least 12 to 15 points
which are evenly distributed over the entire 
<a href="i.group.html">imagery group</a> file in order to
obtain an accurate transformation equation for the
rectification process.  The RMS error may increase with
more points added, but the transformation equation will be
more accurate.

<p>An RMS error of less than or equal to approximately one
resolution unit (pixel or cell) for the image being
rectified is generally considered acceptable.

<p>In order to use a digitizer with <em>i.points</em>, at
least one digitizer driver besides "none" (the on-screen
digitizer) must be available in the digitcap file.

<p>This program is interactive.


<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.rectify.html">i.rectify</a><br>
<a href="i.target.html">i.target</a><br>
<a href="i.vpoints.html">i.vpoints</a>
</em><br>
<em><a href="gm_georect.html">gis.m: GEORECTIFY TOOL</a></em>


<h2>AUTHOR</h2>

Michael Shapiro,
U.S.Army Construction Engineering Research Laboratory
<p><i>Last changed: $Date$</i>