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 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_._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
       marking	control points on an image to be rectified and inputting their
       world coordinate values using the keyboard,  _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	corre-
       sponding  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_._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 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_._v_p_o_i_n_t_s	program does this by calculating a transforma-
       tion equation (the same one that is calculated  in  the	GRASS  program
       i.rectify 2).  Coefficients are computed for the equation.  The coeffi-
       cients 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), dis-
       playing vector map layers,  overlaying  vector  maps  onto  the	raster
       image,  and  calculating  RMS error are described in the following sec-
       tions .


       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 regis-
       tered . . .

	    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 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_._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 windows 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 selec-
       tion 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 function will erase all outlines
       showing the limits of previously 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 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 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 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 3,0  pro-
       gram  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 dis-
       play 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 col-
       umn "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  dis-
       played  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  num-
       ber  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_._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	  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  ref-
       erence 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 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 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 (includ-
       ing 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)
