v.transform(1)	       Grass User's Manual	   v.transform(1)



NNAAMMEE
       vv..ttrraannssffoorrmm   - Transforms an binary vector map layer from
       one coordinate system into another coordinate system.
       _(_G_R_A_S_S _V_e_c_t_o_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       vv..ttrraannssffoorrmm
       vv..ttrraannssffoorrmm hheellpp
       vv..ttrraannssffoorrmm [--yy] iinnppuutt==_n_a_m_e oouuttppuutt==_n_a_m_e [ppooiinnttssffiillee==_n_a_m_e]

DDEESSCCRRIIPPTTIIOONN
       This program has been used to  import  vector  files  that
       were  in  scanner  or  digitizer  (x,y) coordinates and to
       transform these into UTM coordinates.

OOPPTTIIOONNSS
   FFllaagg::
       --yy     Suppress the printing of residuals or other  infor-
	      mation to standard output.


   PPaarraammeetteerrss::
       iinnppuutt==_n_a_m_e
	      Name  of	the  binary vector map layer to be trans-
	      formed.

       oouuttppuutt==_n_a_m_e
	      Name to be assigned to the resultant  (transformed)
	      binary vector map layer.

       ppooiinnttssffiillee==_n_a_m_e
	      Name  of	a  file containing transformation points,
	      whose format is given below.  Give a full path name
	      for  this  file or it will be assumed to be located
	      in the user's current directory.

       The user can run this program non-interactively by  speci-
       fying  parameter values (and optionally, the flag setting)
       on the command line.


       If the user runs vv..ttrraannssffoorrmm  without  specifying  program
       arguments on the command line, the program will prompt the
       user for inputs.  When the program prompts  the	user  for
       two sets of transformation points, the first set of points
       entered by the user should be in the coordinate system  of
       the  input map, and the second set of points should repre-
       sent the corresponding geographic points in the coordinate
       system  into  which the map will transformed.  A user must
       enter 4 to 10 of each set of points for the transformation
       to work correctly.


       After  the  user has entered both sets of points, the pro-
       gram will show the amount of  error  associated	with  the
       transformation  of  the	given points as the _r_e_s_i_d_u_a_l _m_e_a_n
       _a_v_e_r_a_g_e (RMS).  (An acceptable RMS for a 1:24,000 UTM  map
       would  be  1.2  to  2.4 (meters).) It will then ask if the
       transformation RMS value is acceptable.	After an  RMS  is
       accepted  by  the  user,  _v_._t_r_a_n_s_f_o_r_m  will  transform the
       binary vector  (_d_i_g)  map  and  its  associated	attribute
       (_d_i_g___a_t_t) file into the requested coordinate system.


       Remember to run _v_._s_u_p_p_o_r_t on the output map.

NNOOTTEESS
       When  rectifying  a map to another coordinate system using
       _v_._t_r_a_n_s_f_o_r_m, the user should specify  the  coordinates  of
       between	4 to 10 points, and state these both in the coor-
       dinate systems of the input and output maps.  The two sets
       of  coordinates can be input to _v_._t_r_a_n_s_f_o_r_m interactively,
       or from a file specified on  the  command  line	with  the
       _p_o_i_n_t_s_f_i_l_e  option.   The  _p_o_i_n_t_s_f_i_l_e option is especially
       useful when several  maps  in  the  same  geographic  area
       require transformation, as it eliminates the necessity for
       the user to repeatedly type  in	the  same  transformation
       coordinates.


       A _p_o_i_n_t_s_f_i_l_e file will contain between 4 to 10 lines; each
       line will contain the  set  of  coordinate  transformation
       points  for  the  input	map  and the corresponding set of
       coordinates for the output  map.  The  minimum  number  of
       lines for the transformation to take place is four.


       The format of the _p_o_i_n_t_s_f_i_l_e file is shown below:

	Input Map   Output Map

	x	y   x	     y
	x	y   x	     y
	x	y   x	     y
	x	y   x	     y

       In  the	format shown above the _x's and _y's can be thought
       of as eastings and northings, depending on what coordinate
       systems you are transforming to and from.


       An example of the _p_o_i_n_t_s_f_i_l_e file:

	1	1	589000	 4913000
	1	17000	589000	 4930000
	17000	17000	610000	 4930000
	17000	1	610000	 4913000

       Within  the  _p_o_i_n_t_s_f_i_l_e	file,  numbers	on a line must be
       spaced apart with tabs or blanks.  The example shown above
       was  used to convert a map in digitizer coordinates (range
       of 1-18000) to UTM coordinates within the UTM zone for the
       Spearfish sample data base location.


       Because	this _p_o_i_n_t_s_f_i_l_e file is not your usual GRASS data
       file, the user will have to keep track of where it  is  on
       the  system.   When  the  _p_o_i_n_t_s_f_i_l_e option is used on the
       command line to input the transformation points, the  pro-
       gram  does not ask whether or not everything is acceptable
       before converting the vector file and the attribute  file.


       The user is advised to run this program interactively with
       a specific set of transformation coordinates and to  exam-
       ine the resulting residuals, to determine how accurate the
       transformation will be (i.e., pick points with known  val-
       ues  in both coordinate systems).  After the residuals are
       acceptable, those transformation coordinates can  be  used
       with  the program run non-interactively to transform other
       maps in the same geographic area.

WWAARRNNIINNGG
       This is a general purpose program and can be  fooled  into
       giving  low  residuals.	It is strongly suggested that any
       transformed map be  checked  for  accuracy.   The  program
       assumes	that  the  coordinate systems will be planimetric
       and has never been tested with negative values.


       If this program is being used to transform maps from State
       Plane  to UTM coordinates, and vice versa, users should be
       aware of the following points.	This  program  will  work
       better with State Plane zones that use the Transverse Mer-
       cator projection. Those are states that have  their  state
       zones splitting the state vertically, like Illinois.  This
       program will not work as well with  states  that  use  the
       Lambert	Conformal Conic projection. Those are states that
       have their state zones splitting the  state  horizontally,
       like  Wisconsin.  It  is  also best to keep the area being
       transformed relatively small.

SSEEEE AALLSSOO
       _v_._d_i_g_i_t

       _v_._s_u_p_p_o_r_t

AAUUTTHHOORR
       Michael	Higgins,  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_4_/_0_3 _0_9_:_1_9_:_4_0 _$



GRASS 5.0					   v.transform(1)
