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



NNAAMMEE
       ii..ppooiinnttss   -  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 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 coordinates of each point for  calcu-
       lation  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
       coefficients 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  coor-
       dinate 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 associ-
       ated 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
       coordinate systems  (x,y  and  standard)  for  the  marked
       points.	 A  matrix containing 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 number 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  com-
       puted 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 sim-
       ply 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  dis-
       played  by placing the mouse cross hairs on the words PLOT
       RASTER.	The following line is then displayed at the  bot-
       tom 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 mes-
       sage 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  auto-
       matically  saved  as  the coordinates corresponding 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 placing the mouse cross	hairs  on
       the  word  ANALYZE  at the bottom of the graphics monitor.
       An error report resembling that shown  below  is  superim-
       posed on the graphics monitor:

       ______________________________________________________________________
       |	 error		       image		     tar-
       get	   |
       |#      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 transfor-
       mation 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 gen-
       eral 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 tar-
       get 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  after-
       wards  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  equa-
       tion  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 recti-
       fied 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)
