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



NNAAMMEE
       ii..ppooiinnttss33  -  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 determi-
       nation 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 coordinates of each point for  calcu-
       lation	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 transfor-
       mation parameters 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  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_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  photography,
       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 equation (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 program will display the  following  error  mes-
       sage:

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

       After entering the imagery group to be registered the ter-
       minal 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 number	of  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  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 CAN-
       CEL 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 vector 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 graphics 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 previously 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 graphics 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 loca-
       tion (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 CAN-
       CEL 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  sim-
       ply  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 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
       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	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_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  transformation.   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  layers  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 location 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 graphics monitor.  The REFRESH
       option is useful for removing the overlaid grids  or  vec-
       tors.


       The user can return to the main menu by selecting the CAN-
       CEL option.

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


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


		   +-------+------------+-------------+------------+
		   |CANCEL | POLYNOMIAL  |  ORTHO_PHOTO  |  LAND-
       SAT_TM |
		   +-------+------------+-------------+------------+



   PPOOLLYYNNOOMMIIAALL
       The POLYNOMIAL option allows the user to select the degree
       of   the  polynomial  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 transformation (first, second, or third).

   OORRTTHHOOPPHHOOTTOO
       The ORTHOPHOTO transformation is strictly for aerial  pho-
       tography.   The	transformation	is  much more complicated
       than a polynomial transformation.  The  ORTHOPHOTO  trans-
       formation  requires the user to enter elevation data, cam-
       era 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  The-
       matic mapper imagery.  This transfromation requires infor-
       mation 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 coordi-
       nates) 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_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  Laboratory  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 trans-
       formations 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)
