## NAME

i.points3 - An imagery function that enables the user to mark coordinate system points on an image to be rectified and then input the coordinates of each point for determination of transformation parameters. The transformation parameters are needed as input for the GRASS program i.rectify3.
(GRASS Image Processing Program)

## SYNOPSIS

i.points3

## DESCRIPTION

i.points3 is an imagery 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 parameters. i.points3 must be followed by use of the GRASS program i.rectify3, which rectifies the image using the transformation parameters calculated by i.points3.

Rectification 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. i.points3 enables the user to mark points on an image and input the standard coordinates for that point.

i.points3 allows the user to select either a polynomial, orthographic, or LANDSAT-Thematic Mapper transformation. Polynomial transformations are the most generic and can be of one, two, or three degrees of order. The orthographic transformation is used strictly for aerial photography, and can be used in combination with a Digital Elevation Model to remove relief displacement. The LANDSAT-TM transformation is strictly for LANDSAT Thematic Mapper imagery that was imported using the program i.tape.tm3. The LANDSAT-TM transformation can also be used with an elevation model to remove relief displacement.

During the process of marking points and entering map coordinates, the user can compute the RMS (root mean square) error for each point entered. i.points3 does this by calculating the transformation equation (polynomial, orthographic, or LANDSAT-TM), and then plugging these results into an equation for RMS error.

To run i.points3, a graphics monitor is required. i.target must be run before running i.points3 to enable the PLOT options to be used and to identify a target database LOCATIONNAME and MAPSET for the rectified image.

i.points3 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 (raster or vector) in the target data base.

The procedure for selecting a transformation, marking points, entering coordinates, and calculating RMS error is described below.

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

           Enter imagery group to be registerd
           Enter 'list' for a list of existing imagery groups
           Enter 'list -f' for a verbose listing
           Hit RETURN to cancel request
           >

Note that if i.target is not run before i.points3, the i.points3 program will display the following error message:

               ERROR: Target information for group [spot] missing
                      Please run i.target for group [spot]

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

                                Use mouse now...

The graphics monitor displays the following screen:

         +-----------------------------+--------------------------------+
         |imagery  filename  (mag)     | target  filename  (mag)        |
         +-----------------------------+--------------------------------+
         |                             |                                |
         |                             |                                |
         |                             |                                |
         |                             |                                |
         |                             |                                |
         |                             |                                |
         |                             |                                |
         +-----------------------------+--------------------------------+
         |                             |                                |
         |                             |                                |
         |                             |                                |
         |                             |                                |
         |                             |                                |
         |                             |                                |
         |                             |                                |
         +-----------------------------+--------------------------------+
         |QUIT <main> ZOOM  PLOT MARK  | ANALYZE OVERLAY TRANSFORM      |
         +-----------------------------+--------------------------------+

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

                       +---------------------------------+
                       |Double click on raster map layer |
                       |         to be plotted           |
                       |  Double click here to cancel    |
                       +---------------------------------+
                              +-------------------+
                              |   Mapset demo     |
                              +----------+--------+
                              |spotclass | spot.1 |
                              +----------+--------+
                              |composite | spot.2 |
                              +----------+--------+
                              |spot.3    |        |
                              +----------+--------+

Any single raster map layer in the imagery group may be used on which to mark points, and the user can mark points on more than one raster map layer in the imagery group to accumulate the suggested minimum number of points. Any raster map layer in the imagery group can be rectified (using i.rectify) based on the transformation parameters computed from these points.

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

### ZOOM

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:

                        +-------+--------+-----+-------+
                        |CANCEL | <zoom> | BOX | POINT |
                        +-------+--------+-----+-------+

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.

The user can return to the main menu by selecting the CANCEL option.

### PLOT

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

         +-------+--------+---------+--------+--------+---------+-------+
         |CANCEL | <plot> | IMAGERY | RASTER | VECTOR | REFRESH | CLEAR |
         +-------+--------+---------+--------+--------+---------+-------+

The IMAGERY option allows the user to select another imagery group file to be displayed (on the left hand side of the graphics monitor).

The RASTER option allows the user to select a raster map layer in the target LOCATIONNAME to be displayed on the right hand side of the graphics monitor.

The VECTOR option allows the user to select a vector map layer in the target LOCATIONNAME to be displayed on the right hand side of the graphics monitor. Vector layers will be overlaid on top of any previously displayed raster layers (on the right hand side of the graphics monitor).

The REFRESH option allows the user to refresh either the source imagery (left hand side) or the target location (right hand side) of the graphics monitor. The REFRESH option is usefull for removing the zoom box outines, and overlaid grids or vectors that are discussed in the "OVERLAY" function.

The CLEAR option allows the user to clear the target location (right hand side) of the graphics monitor. This will erase both the raster layers and the vector layers from the right hand side of the graphics monitor.

The user can return to the main menu by selecting the CANCEL option.

A pop-down menu will be superimposed on the left half of the screen for the IMAGERY option, and on the right hand side for either the RASTER or VECTOR options: The pop-up menu will allow you to select either an raster or vector map layer to be displayed in the appropriate half of the graphics monitor.

                  +------------------------------------------+
                  |Double click on raster (vector) map layer |
                  |              to be plotted               |
                  |       Double click here to cancel        |
                  +------------------------------------------+
                       +--------------------------------+
                       |          Mapset demo           |
                       +--------------+-----------------+
                       |tm.rectified  |  spot.rect      |
                       +--------------+-----------------+
                       |tm.classified | spot.rect.class |
                       +--------------+-----------------+

### MARKING POINTS

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:

           +-------------------------------+--------------------------+
           |Point 1 marked on the image at |                          |
           |East: 1023.77                  |                          |
           |North: -164.41                 |                          |
           |                               |                          |
           |                               |                          |
           |                               |                          |
           |                               |                          |
           |                               |                          |
           +-------------------------------+--------------------------+
           |Enter coordinates as east north:                          |
           +----------------------------------------------------------+

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 and will NOT be used.

If a target raster or vector map layer is displayed (in the right hand side) the following message appears at the bottom of the graphics monitor:

                     +-----------------+----------+--------+
                     |input method --> | keyboard | screen |
                     +-----------------+----------+--------+

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.

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:

           +-------------------------------+--------------------------+
           |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...                                          |
           +----------------------------------------------------------+

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.

### ANALYZE

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:

     +---------------------------------------------------------------------+
     |         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                                   |
     +---------------------------------------------------------------------+

The following menu then appears at the bottom of the graphics monitor:

     +-----+-------+------+------------------------------------------------+
     |DONE | PRINT | FILE |  Double click on point to be included/excluded |
     +-----+-------+------+------------------------------------------------+

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).

The location of the point marked on the imagery group 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 i.points3 at any time by double clicking with the mouse as described above.

### OVERLAY

The OVERLAY option allows the user to visulaize the results of the RMS error analysis. The option allows the user to overlay either a grid some vector map layers to visually examine the results of the transformation. The following menu appears at the bottom of the graphics screen.

                      +-------+--------+------+-----------+
                      |CANCEL | VECTOR | GRID |  REFRESH  |
                      +-------+--------+------+-----------+

The VECTOR option allows the user to overlay all of the vector map layers that are currently displayed on the right hand side on top of the original source imagery (left hand side).

The GRID option allows the user to display a rectangular grid over the original source imagery and then overlay the grid on the target location imagery (left hand side).

The REFRESH option allows the user to refresh either the source imagery (left hand side) or the target location (right hand side) of the graphics monitor. The REFRESH option is useful for removing the overlaid grids or vectors.

The user can return to the main menu by selecting the CANCEL option.

### TRANSFORMATION

The transfromation option allows the user to select the type of transformation to be preformed, and to initialize any required information for the transformation. Currently only POLYNOMIAL, ORTHOGRAPHIC, and LANDSATTM transformations are supported.

The following menu appears at the bottom of the graphics monitor.

                +-------+------------+-------------+------------+
                |CANCEL | POLYNOMIAL | ORTHO_PHOTO | LANDSAT_TM |
                +-------+------------+-------------+------------+

### POLYNOMIAL

The POLYNOMIAL option allows the user to select the degree of the polynomial transformation (first, second, or third). The following menu appears at the bottom of the graphics monitor.

                        +-------+-------+-------+-------+
                        |CANCEL | POLY1 | POLY2 | POLY3 |
                        +-------+-------+-------+-------+

This menu allows the user to select the degree of the polynomial transformation (first, second, or third).

### ORTHOPHOTO

The ORTHOPHOTO transformation is strictly for aerial photography. The transformation is much more complicated than a polynomial transformation. The ORTHOPHOTO transformation requires the user to enter elevation data, camera data, and exposure data. The following menu appears at the bottom of the graphics monitor.

        +-------+-----------+--------+-----------+-----------+----------+
        |CANCEL | ELEVATION | CAMERA | MARK FID. | ANAL FID. | EXPOSURE |
        +-------+-----------+--------+-----------+-----------+----------+

The ORTHOPHOTO option allows the user to select a raster map layer in the target LOCATIONNAME to be displayed on the right hand side of the graphics monitor.

### LANDSAT THEMATIC MAPPER

The LANDSATTM transfromation is strictly for LANDSAT Thematic mapper imagery. This transfromation requires information extracted from the LANDSAT data tape as well as an elevation model. The following menu appears at the bottom of the graphics monitor.

                              +-------+-----------+
                              |CANCEL | ELEVATION |
                              +-------+-----------+

### QUIT

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

## NOTES

A good rule of thumb is to mark at least 12 to 15 points which are evenly distributed over the entire imagery group 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.

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.

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

This program is interactive and requires no command line arguments.

## SEE ALSO

GRASS Tutorial: Image Processing

i.group, i.points, i.rectify, i.rectify3, i.target, i.tape.tm3

## AUTHOR

Mike Baba, DBA Systems.

Michael Shapiro, U. S. Army Construction Engineering Research Laboratory wrote the original i.points program from which much of i.points3 is based.

William Enslin, Michigan State University, wrote i.vpoints, and i.rectify2 from which the polynomial transformations and vector display and overlay were obtained.

Last changed: $Date: 2002/01/25 05:45:33 $