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



NNAAMMEE
       ii..ppooiinnttss33  -  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 determination of transformation parameters.
       The transformation parameters are needed as input for the GRASS program
       _i_._r_e_c_t_i_f_y_3.

       _(_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..ppooiinnttss33

DDEESSCCRRIIPPTTIIOONN
       _i_._p_o_i_n_t_s_3  is  an imagery function that enables the user to mark points
       on a (raster) image to be rectified and then input the geographic coor-
       dinates	of  each  point for calculation of a coordinate transformation
       parameters.  _i_._p_o_i_n_t_s_3 must be followed by use  of  the	GRASS  program
       _i_._r_e_c_t_i_f_y_3,  which rectifies the image using the transformation parame-
       ters calculated by _i_._p_o_i_n_t_s_3.


       Rectification 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_3 enables the user to mark
       points on an image and input the standard coordinates for that point.


       _i_._p_o_i_n_t_s_3 allows the user to select either a polynomial,  orthographic,
       or  LANDSAT-Thematic Mapper transformation.  Polynomial transformations
       are the most generic and can be of one, two, or three degrees of order.
       The  orthographic  transformation is used strictly for aerial photogra-
       phy, and can be used in combination with a Digital Elevation  Model  to
       remove  relief displacement.  The LANDSAT-TM transformation is strictly
       for LANDSAT Thematic Mapper imagery that was imported using the program
       _i_._t_a_p_e_._t_m_3.   The  LANDSAT-TM  transformation  can also be used with an
       elevation model to remove relief displacement.


       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_3 does this by calculating the  transformation  equa-
       tion (polynomial, orthographic, or LANDSAT-TM), and then plugging these
       results into an equation for RMS error.


       To run _i_._p_o_i_n_t_s_3, a graphics monitor is required.  _i_._t_a_r_g_e_t must be run
       before  running	_i_._p_o_i_n_t_s_3 to enable the PLOT options to be used and to
       identify a target database LOCATIONNAME and MAPSET  for	the  rectified
       image.


       _i_._p_o_i_n_t_s_3  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
       (raster or vector) in the target data base.


       The procedure for selecting a transformation, 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.



	      Enter imagery group to be registerd
	      Enter 'list' for a list of existing imagery groups
	      Enter 'list -f' for a verbose listing
	      Hit RETURN to cancel request
	      >



       Note that if _i_._t_a_r_g_e_t is not run before _i_._p_o_i_n_t_s_3, the  _i_._p_o_i_n_t_s_3  pro-
       gram will display the following error message:

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

       After  entering	the imagery 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 <main> ZOOM  PLOT MARK  | ANALYZE OVERLAY TRANSFORM	   |
	    +-----------------------------+--------------------------------+


       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 points.  Any raster map layer in the imagery group can be recti-
       fied  (using _i_._r_e_c_t_i_f_y) based on the transformation parameters 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 | <zoom> | BOX | POINT |
			   +-------+--------+-----+-------+


       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.


       The user can return to the main menu by selecting the CANCEL option.

   PPLLOOTT
       In addition to acquiring reference points from a standard map, the user
       has the option of acquiring the reference points from a raster or  vec-
       tor  map layer in the target data base LOCATIONNAME.  A target location
       map layer is displayed by placing the mouse cross hairs	on  the  words
       PLOT.  The following line is then displayed at the bottom of the graph-
       ics monitor:


	    +-------+--------+---------+--------+--------+---------+-------+
	    |CANCEL | <plot> | IMAGERY | RASTER | VECTOR | REFRESH | CLEAR |
	    +-------+--------+---------+--------+--------+---------+-------+


       The IMAGERY option allows the user to select another imagery group file
       to be displayed (on the left hand side of the graphics monitor).


       The  RASTER  option allows the user to select a raster map layer in the
       target LOCATIONNAME to be displayed on  the  right  hand  side  of  the
       graphics monitor.


       The  VECTOR  option allows the user to select a vector map layer in the
       target LOCATIONNAME to be displayed on  the  right  hand  side  of  the
       graphics  monitor.  Vector layers will be overlaid on top of any previ-
       ously displayed raster layers (on the right hand side of  the  graphics
       monitor).


       The REFRESH option allows the user to refresh either the source imagery
       (left hand side) or the target location (right hand side) of the graph-
       ics  monitor.   The REFRESH option is usefull for removing the zoom box
       outines, and overlaid grids or vectors that are discussed in the "OVER-
       LAY" function.


       The  CLEAR  option  allows the user to clear the target location (right
       hand side) of the graphics monitor.  This will erase  both  the	raster
       layers  and  the vector layers from the right hand side of the graphics
       monitor.


       The user can return to the main menu by selecting the CANCEL option.


       A pop-down menu will be superimposed on the left half of the screen for
       the IMAGERY option, and on the right hand side for either the RASTER or
       VECTOR options:	The pop-up menu will allow you	to  select  either  an
       raster  or  vector map layer to be displayed in the appropriate half of
       the graphics monitor.


		     +------------------------------------------+
		     |Double click on raster (vector) map layer |
		     |		    to be plotted		|
		     |	     Double click here to cancel	|
		     +------------------------------------------+
			  +--------------------------------+
			  |	     Mapset demo	   |
			  +--------------+-----------------+
			  |tm.rectified  |  spot.rect	   |
			  +--------------+-----------------+
			  |tm.classified | spot.rect.class |
			  +--------------+-----------------+



   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 and will NOT be used.


       If a target raster or vector map layer is displayed (in the right  hand
       side) the following message appears at the bottom of the graphics moni-
       tor:


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

   OOVVEERRLLAAYY
       The OVERLAY option allows the user to visulaize the results of the  RMS
       error  analysis.   The  option allows the user to overlay either a grid
       some vector map layers to visually examine the results of the transfor-
       mation.	 The  following  menu  appears	at  the bottom of the graphics
       screen.


			 +-------+--------+------+-----------+
			 |CANCEL | VECTOR | GRID |  REFRESH  |
			 +-------+--------+------+-----------+

       The VECTOR option allows the user to overlay all of the vector map lay-
       ers  that  are currently displayed on the right hand side on top of the
       original source imagery (left hand side).


       The GRID option allows the user to display a rectangular grid over  the
       original  source  imagery and then overlay the grid on the target loca-
       tion imagery (left hand side).


       The REFRESH option allows the user to refresh either the source imagery
       (left hand side) or the target location (right hand side) of the graph-
       ics monitor.  The REFRESH option is useful for  removing  the  overlaid
       grids or vectors.


       The user can return to the main menu by selecting the CANCEL option.

   TTRRAANNSSFFOORRMMAATTIIOONN
       The  transfromation option allows the user to select the type of trans-
       formation to be preformed, and to initialize any  required  information
       for  the  transformation.  Currently only POLYNOMIAL, ORTHOGRAPHIC, and
       LANDSATTM transformations are supported.


       The following menu appears at the bottom of the graphics monitor.


		   +-------+------------+-------------+------------+
		   |CANCEL | POLYNOMIAL | ORTHO_PHOTO | LANDSAT_TM |
		   +-------+------------+-------------+------------+



   PPOOLLYYNNOOMMIIAALL
       The POLYNOMIAL option allows the user to select the degree of the poly-
       nomial  transformation  (first,	second, or third).  The following menu
       appears at the bottom of the graphics monitor.


			   +-------+-------+-------+-------+
			   |CANCEL | POLY1 | POLY2 | POLY3 |
			   +-------+-------+-------+-------+


       This menu allows the user to select the degree of the polynomial trans-
       formation (first, second, or third).

   OORRTTHHOOPPHHOOTTOO
       The  ORTHOPHOTO transformation is strictly for aerial photography.  The
       transformation is much more complicated than a  polynomial  transforma-
       tion.   The ORTHOPHOTO transformation requires the user to enter eleva-
       tion data, camera data, and exposure data.  The following menu  appears
       at the bottom of the graphics monitor.


	   +-------+-----------+--------+-----------+-----------+----------+
	   |CANCEL | ELEVATION | CAMERA | MARK FID. | ANAL FID. | EXPOSURE |
	   +-------+-----------+--------+-----------+-----------+----------+


       The  ORTHOPHOTO	option allows the user to select a raster map layer in
       the target LOCATIONNAME to be displayed on the right hand side  of  the
       graphics monitor.

   LLAANNDDSSAATT TTHHEEMMAATTIICC MMAAPPPPEERR
       The  LANDSATTM  transfromation  is strictly for LANDSAT Thematic mapper
       imagery.  This transfromation requires information extracted  from  the
       LANDSAT	data  tape  as well as an elevation model.  The following menu
       appears at the bottom of the graphics monitor.


				 +-------+-----------+
				 |CANCEL | ELEVATION |
				 +-------+-----------+



   QQUUIITT
       To end the _i_._p_o_i_n_t_s_3 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_3, 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
       GRASS Tutorial: Image Processing


       _i_._t_a_p_e_._t_m_3

AAUUTTHHOORR
       Mike Baba, DBA Systems.


       Michael	Shapiro,  U. S. Army Construction Engineering Research Labora-
       tory wrote the original _i_._p_o_i_n_t_s program from which much  of  _i_._p_o_i_n_t_s_3
       is based.


       William	Enslin, Michigan State University, wrote _i_._v_p_o_i_n_t_s, and _i_._r_e_c_-
       _t_i_f_y_2 from which the polynomial transformations and vector display  and
       overlay were obtained.

       _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.points3(1)
