Provided by: grass-doc_6.4.3-3_all bug


       i.vpoints   -  Set  registration points for an imagery group from a vector map or keyboard


       imagery, geometry


       i.vpoints help
       i.vpoints group=string  [--verbose]  [--quiet]

           Name of imagery group to be registered


       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  i.rectify  program  to  rectify  the  image  using  the  transformation  matrix
       coefficients calculated from the control point file created in i.vpoints.  The
        i.rectify program performs a first, second or third order transformation of the image.

       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, i.vpoints 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,  i.vpoints 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 i.vpoints.  The i.vpoints 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 i.vpoints  program does this
       by  calculating  a  transformation  equation (the same one that is calculated in the GRASS
       program i.rectify 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.

       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 .

       To  enter  the program (the i.vpoints program requires the use of a graphics monitor) type

       The first prompt in the program asks for the imagery group to be registered . . .
            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
        For example,

       might produce the following response:
            Available groups
            - - - - - - - - - - - - - - - - - - - - - - - - - -
            - - - - - - - - - - - - - - - - - - - - - - - - - -
       >list -f

       might produce the following response
            Available groups
            - - - - - - - - - - - - - - - - - - - - - - - - - -
                photo in PERMANENT
                res2 in tifftest
            - - - - - - - - - - - - - - - - - - - - - - - - - -
        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:
            Use mouse now . . .
        And the color graphics monitor displays the following screen:

       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  i.rectify)  based  on  the
       transformation matrix computed from these points.

       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.


       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  i.vpoints  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.


       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.


       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:
            Refresh Map ?       NO   YES


       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:
            CANCEL   BOX   POINT      Select type of zoom
        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
            CANCEL    Mark the first corner of region
            CANCEL     Define the region
        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.

       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.

       You may zoom either the raster or the vector display.

       Upon accepting the new region limits, the raster or vector data are redisplayed in  either
       the lower left (raster) or lower right (vector) windows.

       The extent of the zoomed area is outlined on the unzoomed image in the main window area.

       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 GRASS v.digit.  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.

       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:
                 Point 1 marked on the image at
                 East:  1023.77
                 North:  -164.41
                 Enter coordinates as east north:

       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
          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
         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 i.vpoints at any time by double clicking with the
       mouse as described above.

       The following menu appears at the bottom of the monitor:
          DONE   PRINT   FILE   OVERLAY   DELETE ON       Transformation -
       ->   1st ORDER   Double click on point to be DELETED
        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.


       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).
            Overlay vectors on raster image   NO   YES
        By selecting the 1st ORDER option, the  user  may  select  the  order  of  transformation
        1st Order 2nd Order 3rd Order
        The program will immediately recalculate the RMSE and the number of points required.


       To  exit the i.vpoints 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.


       The GRASS 4 Image Processing manual

        g.mapsets,, i.points, i.rectify,
       gis.m: GEORECTIFY TOOL and wxGUI: Manage Ground Control Points


       William R. Enslin, Michigan State University Center for Remote Sensing
       Radim Blazek (update to GRASS 5.7)
       Hamish Bowman (finish GRASS 6 porting)

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

       Full index

       © 2003-2013 GRASS Development Team