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



NNAAMMEE
       ii..ppooiinnttss   -  An imagery function that enables the user to mark coordi-
       nate system points on an image to be rectified and then input the coor-
       dinates	of  each  point  for  creation	of a coordinate transformation
       matrix.	The transformation matrix is needed as	input  for  the  GRASS
       program _i_._r_e_c_t_i_f_y.
       _(_G_R_A_S_S _I_m_a_g_e _P_r_o_c_e_s_s_i_n_g _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       ii..ppooiinnttss

DDEESSCCRRIIPPTTIIOONN
       _i_._p_o_i_n_t_s is an imagery function that enables the user to mark points on
       a (raster) image to be rectified and then input the geographic  coordi-
       nates  of  each	point  for  calculation of a coordinate transformation
       matrix.	_i_._p_o_i_n_t_s must be followed by use of the GRASS  program	_i_._r_e_c_-
       _t_i_f_y, which rectifies the image using the transformation matrix coeffi-
       cients calculated by _i_._p_o_i_n_t_s.


       _R_e_c_t_i_f_i_c_a_t_i_o_n 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  coordi-
       nate  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_._p_o_i_n_t_s enables the user to mark points
       on an  image  and  input  the  standard	coordinates  for  that	point.
       _i_._p_o_i_n_t_s then calculates a least squares regression using the two coor-
       dinate systems (x,y and standard) for the marked points.  A matrix con-
       taining transformation coefficients is the output file for _i_._p_o_i_n_t_s.


       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_._p_o_i_n_t_s does this by calculating the transformation equation
       (the same one that is calculated in the GRASS program  _i_._r_e_c_t_i_f_y),  and
       then plugging these results into an equation for RMS error.


       _i_._p_o_i_n_t_s  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.


       _i_._t_a_r_g_e_t must be run before running _i_._p_o_i_n_t_s 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 _i_._p_o_i_n_t_s, a graphics monitor is
       required.


       The procedure for 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.	 Note that if _i_._t_a_r_g_e_t is not run before _i_._p_o_i_n_t_s, the
       _i_._p_o_i_n_t_s program will display the following error message:

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

       After entering the 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  ZOOM  PLOT RASTER  ANALYZE|			     |
       |_________________________________|___________________________|

       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 num-
       ber  of	12  points.   Any raster map layer in the imagery group can be
       rectified (using _i_._r_e_c_t_i_f_y) based on the transformation matrix computed
       from these points.


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

ZZOOOOMM
       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|  Box|  Point|  Select type of ZOOM|
	 |_______|_____|_______|_____________________|

       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.

MMAARRKKIINNGG PPOOIINNTTSS
       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.

PPLLOOTT RRAASSTTEERR
       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:

	      ________________________________________________
	     | Cancel|	Indicate which side should be plotted|
	     |_______|_______________________________________|

       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:

	   _________________________________________
	  | 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        |	      |
		|______________|______________|

       After  the  raster map layer is displayed 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  com-
       parative  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 corre-
       sponding points on the target data base map  layer.   In  this  option,
       when  the  user	marks a point on the image, the following menu is dis-
       played 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  dis-
       played image from the target data base.	The coordinates for the target
       data base map layer are automatically saved as the  coordinates	corre-
       sponding to the marked point on the image.

AANNAALLYYZZEE
       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 plac-
       ing  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  pre-
       sented  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 (repre-
       sented 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  head-
       ing "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_._p_o_i_n_t_s at any time by double clicking with  the  mouse  as  described
       above.

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

NNOOTTEESS
       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_._p_o_i_n_t_s,  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.

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_._r_e_c_t_i_f_y

       _i_._t_a_r_g_e_t

AAUUTTHHOORR
       Michael Shapiro, U.S.Army Construction Engineering Research Laboratory

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_3 _$



GRASS 5.0							   i.points(1)
