photo.2image(1) 	      Grass User's Manual	       photo.2image(1)



_T_h_i_s _i_s _n_o_t _a _c_o_m_m_a_n_d _i_n _i_t_s_e_l_f_, _b_u_t _a_n _o_p_t_i_o_n _o_f _t_h_e _c_o_m_m_a_n_d _i_._o_r_t_h_o_._p_h_o_t_o_.

NNAAMMEE
       pphhoottoo..22iimmaaggee  - An imagery function that enables you to mark known ref-
       erence points (fiducial marks, reseau marks,  etc.)  on	imagery  group
       files, and compute the image-to-photo coordinate transformation parame-
       ters.  The transformation parameters are required for the  GRASS  Image
       Processing Program _i_._o_r_t_h_o_._p_h_o_t_o.
       _(_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
       SSeelleecctteedd ffrroomm ii..oorrtthhoo..pphhoottoo

DDEESSCCRRIIPPTTIIOONN
       _p_h_o_t_o_._2_i_m_a_g_e  is  an imagery function that enables you to mark fiducial
       or reseau points on an image to be ortho-rectified  and	then  computes
       the  image-to-photo  coordinate transformation parameters.  The coordi-
       nates of the fiducials or reseau marks can be choosen for a camera ref-
       erence file.


       During the process of marking reference points with known photo coordi-
       nates, you may compute the RMS (root mean square) error for each refer-
       ence  point  entered.  _p_h_o_t_o_._2_i_m_a_g_e does this by calculating the trans-
       formation equation (the same one that is calculated by _i_._p_o_i_n_t_s ),  and
       then plugging these results into an equation for RMS error.


       _p_h_o_t_o_._2_i_m_a_g_e  offers  a zoom option to locate precisely the fiducial or
       reseau point to be marked on an image.


       To run _p_h_o_t_o_._2_i_m_a_g_e, a graphics monitor is required.


       The procedure for marking fiducial or reseau   points,  entering  known
       photo-coordinates, and analyzing the RMS error is described below.


       The terminal screen displays this message:


       uussee mmoouussee nnooww......


       The graphics monitor displays the following screen:

	   +---------------------------+---------------------------------+
	   |imagery		       |				 |
	   +---------------------------+---------------------------------+
	   |			       |				 |
	   |			       |				 |
	   |			       |				 |
	   |			       |				 |
	   |			       |				 |
	   |			       |				 |
	   |			       |				 |
	   +---------------------------+---------------------------------+
	   |			       |				 |
	   |			       |				 |
	   |			       |				 |
	   |			       |				 |
	   |			       |				 |
	   |			       |				 |
	   |			       |				 |
	   +---------------------------+---------------------------------+
	   |			       |				 |
	   +---------------------------+---------------------------------+



       A  pop-down menu like that shown below will be superimposed on the left
       half of the screen:



		     +----------------------------------------+
		     |Double click on cell file to be plotted |
		     | Double click here to cancel	 |
		     +----------------------------------------+
				 +----------------+
				 |Mapset imagery  |
				 +-------+--------+
				 |gs13.1 | gs21.1 |
				 +-------+--------+
				 |gs14.1 | gs22.2 |
				 +-------+--------+

       Any single file in the imagery group may  be  used  on  which  to  mark
       points,	and  you  may mark points on more than one file in the imagery
       group to accumulate the suggested minimum number  of  4-8  fiducial  or
       ressue  points.	 The  imagery  file selected is displayed in the upper
       left quadrant of the screen.



CCAAMMEERRAA FFIILLEE
       The camera reference file may be viewed	by  placing  the  mouse  cross
       hairs on the words CAMERA.  The camera reference file will be displayed
       in the lower left quadrant of the display:




       |---------------------------------------------------------------|
       |Camera Reference File					       |
       |---------------------------------------------------------------|
       |  CAMERA NAME :        camera name			       |
       |  CAMERA ID   :        L1234				       |
       |  CAMERA CFL  :        153.021 mm.			       |
       |  CAMERA XP   :        0.050 mm.			       |
       |  CAMERA XP   :        0.056 mm.			       |
       |  number of fid.       4				       |
       |---------------------------------------------------------------|
       |							       |
       |ID	  (X PHOTO) mm. 		(Y PHOTO) mm.	       |
       |_______________________________________________________________|
       |1	  -105.023			  110.123	       |
       |2	   107.987			  109.834	       |
       |3	   110.965			 -104.329	       |
       |4	  -103.932			 -110.352	       |
       |_______________________________________________________________|



       The following menu is displayed at the bottom of the graphics display:




       ++----------++------------++----------------------++----------------++------------------++--------------------------------------++--------------------------++
       ||QQuuiitt  || ZZoooomm || PPlloott CCeellll || CCaammeerraa || AAnnaallyyzzee ||	IInnppuutt-->>KKEEYYBBOOAARRDD || CCAAMM--
       EERRAA FFIILLEE ||
       ++----------++------------++----------------------++----------------++------------------++--------------------------------------++--------------------------++





ZZOOOOMM
       To  magnify the displayed file, you must place the mouse cross hairs on
       the word ZOOM. The following menu will then be displayed at the	bottom
       of the screen:




       ++--------------++----------++--------------++++----------------------------------------++
       ||CCaanncceell || BBooxx || PPooiinntt ||||SSeelleecctt ttyyppee ooff ZZOOOOMM ||
       ++--------------++----------++--------------++++----------------------------------------++




       You  have the option of identifying the zoom window either by using the
       mouse to make a box, or by using the mouse to mark the  center  of  the
       desired	window,  and adjusting the magnification factor.  The terminal
       screen will display a mouse button menu to guide you in identifying the
       window.	 The  section of the image within the zoom window will be dis-
       played in the upper right hand quadrant.



MMAARRKKIINNGG RREEFFEERREENNCCEE PPOOIINNTTSS
       To mark the known reference points (fiducial marks, reseau marks, etc.)
       on the image, you 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.


       If  you	wish  to  use the  camera reference file only as a comparative
       reference,  then the keyboard can be chosen as the means to input photo
       coordinates  corresponding to the marked reference 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.


       The following menu is displayed on the graphics terminal:



       +------------------------------------+--------------------------+
       |Point 1 marked at IMAGE COORDINATES |			       |
       |east:  1023.77			    |			       |
       |north:	506.56			    |			       |
       |				    |			       |
       |				    |			       |
       |				    |			       |
       |				    |			       |
       |				    |			       |
       +------------------------------------+--------------------------+
       |Enter PHOTO COORDINATES as x and y:			       |
       +---------------------------------------------------------------+




       You  then enter the known (x,y) photo coordinates, relative to the per-
       spective center, for the  reference point marked on the image.  If  you
       do  not	wish to enter a coordinate, simply hit RETURN to continue; the
       marked reference point will disappear.


       If you select the CAMERA FILE option, then reference points  marked  on
       the  image  will be associated with selected photo coordinates from the
       displayed camera reference file.  In this option, when you mark a point
       on the image, the following menu is displayed on the graphics terminal:


       -------------------------------------------------------------	CANCEL
       Double	 click	  on	the    fiducial    mark   to   be   referenced
       -------------------------------------------------------------


       If you would like to select the photo coordinates of a displayed refer-
       ence mark, this can be accomplished by placing the mouse cross hairs on
       the reference point to be selected and pressing the left button on  the
       mouse twice.  After a reference point is selected from the display, you
       are prompted with "Look ok? (Y/N)".  If you respond with no, the refer-
       ence  point is ignored.	If you respond with yes, the following is dis-
       played on the terminal:





       +----------------------------------------+--------------------------+
       |Point 1 marked at IMAGE COORDINATES	|			   |
       |east: 1023.77				|			   |
       |north: 1065.41				|			   |
       |					|			   |
       |					|			   |
       |Point 1 referenced at PHOTO COORDINATES |			   |
       |X: -105.023				|			   |
       |Y:  110.122				|			   |
       |					|			   |
       |					|			   |
       |					|			   |
       |					|			   |
       |					|			   |
       +----------------------------------------+--------------------------+
       | use mouse now...						   |
       +----------------------------------------+--------------------------+




       The photo coordinates and the corresponding image coordinates are auto-
       matically  saved  in  the photo_points file associated with the imagery
       group.





AANNAALLYYZZEE
       After a number of points have been marked (4 to 8), you 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 monitor.
       An  error  report resembling the one shown below is superimposed on the
       monitor:



       +--------------------------------------------------------------------+
       |       error	       image	       photo			    |
       |								    |
       |#     row      col   photo    east    north   x 	      y     |
       |1     0.0     -0.9    1.0     1048.5  -144.8  -105.023	  110.122   |
       |2     0.4      1.0    1.3     2153.1  -567.2   107.987	  109.834   |
       |3    -1.2     -0.5    0.6     1452.8  -476.5   110.965	 -104.329   |
       |4     1.1      0.5    1.3     1034.0  -109.2  -103.932	 -110.352   |
       |								    |
       +--------------------------------------------------------------------+
       |    overall   rms    error:   4.46				    |
       +--------------------------------------------------------------------+



       The following menu then appears at the bottom of the 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 photo coordinates
       is listed under the heading "photo".  This is the RMS error for	the  x
       and  y  coordinates of the photo coordinates but it is presented in the
       table using one general value.  The overall RMS error is  displayed  at
       the  bottom  of	the screen in milimeters.  Points that create high RMS
       error are displayed in red on the monitor (represented  here  in  ital-
       ics).


       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 photo coordinates is given under the head-
       ing "photo" and the subheadings "x" and "y".   If  you  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
       _p_h_o_t_o_._2_i_m_a_g_e at any time by double clicking with the mouse as described
       above.



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



NNOOTTEESS
       A good rule of thumb is to mark at least 4 to 8 points which are evenly
       distributed  over  the  perimeter of the 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)	for  the image being rectified is generally considered accept-
       able.

SSEEEE AALLSSOO
       _i_._o_r_t_h_o_._p_h_o_t_o

       _p_h_o_t_o_._c_a_m_e_r_a

       _p_h_o_t_o_._2_t_a_r_g_e_t

       _p_h_o_t_o_._i_n_i_t

       _p_h_o_t_o_._r_e_c_t_i_f_y



AAUUTTHHOORR
       Mike Baba,  DBA Systems, Inc.

       _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_4 _$



GRASS 5.0						       photo.2image(1)
