i.vpoints(1)	       Grass User's Manual	     i.vpoints(1)



NNAAMMEE
       ii..vvppooiinnttss   - Identifies coordinate pairs of points from a
       vector map or keyboard entry and corresponding  points  in
       an image.
       _(_G_R_A_S_S _I_m_a_g_e_r_y _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       ii..vvppooiinnttss

DDEESSCCRRIIPPTTIIOONN
       This program enables the user to identify coordinate pairs
       of points from a vector map or keyboard entry  and  corre-
       sponding points in an image to be rectified. The map coor-
       dinate values of each point are used to calculate a trans-
       formation  matrix.   The operator may then use the  _i_._r_e_c_-
       _t_i_f_y program to rectify the image using the transformation
       matrix coefficients calculated from the control point file
       created in _i_._v_p_o_i_n_t_s.  The  _i_._r_e_c_t_i_f_y 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_._v_p_o_i_n_t_s has a zoom option.  In addition to mark-
       ing  control  points  on  an  image  to	be  rectified and
       inputting their world coordinate  values  using	the  key-
       board,  _i_._v_p_o_i_n_t_s has the option to simultaneously display
       vector map data available in the  targeted  database,  and
       identify on the vector map the location of the correspond-
       ing marked points.  When this option is chosen, the  coor-
       dinate  values  are  input  automatically.   Any GRASS map
       layer or vector map in the targeted database LOCATION  can
       be  displayed using _i_._v_p_o_i_n_t_s.  The _i_._v_p_o_i_n_t_s program also
       has the capability of overlaying (i.e., warping) the  vec-
       tor data onto the raster image to visually check the accu-
       racy 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_._v_p_o_i_n_t_s  program does this by calculating	a  trans-
       formation 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 equa-
       tion 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  ANA-
       LYZE 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_._v_p_o_i_n_t_s program  requires  the
       use of a graphics monitor) type _i_._v_p_o_i_n_t_s: ii..vvppooiinnttss

       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, >lliisstt

       might produce the following response:

	    <list>
	    Available groups
	    - - - - - - - - - - - - - - - - - - - - - - - - - -
	    test
	    - - - - - - - - - - - - - - - - - - - - - - - - - -
	    hit RETURN to continue

       whereas, >lliisstt --ff

       might produce the following response

	    Available groups
	    - - - - - - - - - - - - - - - - - - - - - - - - - -
	    test
		photo in PERMANENT
		res2 in tifftest
	    - - - - - - - - - - - - - - - - - - - - - - - - - -
	    hit RETURN to continue

       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:

	    >test
	    <test>
	    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 num-
       ber 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_._r_e_c_-
       _t_i_f_y)  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.


       RRAASSTTEERR IIMMAAGGEE


       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_._v_p_o_i_n_t_s
       program.   When	you  select this option, the program will
       erase the data contained in all of the four quadrant  win-
       dows and will reinitialize all program values.


       VVEECCTTOORR MMAAPPSS


       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.


       RReeffrreesshh


       The  refresh  option  on  the main menu allows the user to
       "refresh" or re-draw the displayed vector data. This func-
       tion  will erase all outlines showing the limits of previ-
       ously zoomed areas.  A "yes/no" roompt will appear:

	    Refresh Map ?	NO   YES



       ZZoooomm


       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  bot-
       tom. 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 follows...

	    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 fac-
       tor, 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  cor-
       rosponding  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  3,0  program	digit/1/.   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:

       AAnnaallyyzzee


       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:


	  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 gener-
       ate 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 coordi-
       nate 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 dis-
       played) 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_._v_p_o_i_n_t_s 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	   Trans-
       formation -
       ->   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.


       OOvveerrllaayy


       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 file 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  transforma-
       tion (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 desired:

	    Select order of transformation  1st Order  2nd  Order
       3rd Order

       The  program will immediately recalculate the RMSE and the
       number of points required.


       QQuuiitt


       To exit the _i_._v_p_o_i_n_t_s 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.



SSEEEE AALLSSOO
       _G_R_A_S_S _T_u_t_o_r_i_a_l_: _I_m_a_g_e _P_r_o_c_e_s_s_i_n_g



       _g_._m_a_p_s_e_t_s



       _i_._g_r_o_u_p



       _i_._p_o_i_n_t_s



       _i_._r_e_c_t_i_f_y



       _i_._r_e_c_t_i_f_y



       _i_._t_a_r_g_e_t


AAUUTTHHOORR
       William R. Enslin, Michigan State  University  Center  for
       Remote Sensing

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_3_/_0_1 _0_0_:_0_8_:_3_1 _$



GRASS 5.0					     i.vpoints(1)
