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



NNAAMMEE
       vv..ttrraannssffoorrmm   -	Transforms an binary vector map layer from one coordi-
       nate 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 coordi-
       nates.

OOPPTTIIOONNSS
   FFllaagg::
       --yy     Suppress the printing of residuals or other information to stan-
	      dard output.


   PPaarraammeetteerrss::
       iinnppuutt==_n_a_m_e
	      Name of the binary vector map layer to be transformed.

       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 specifying 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 represent
       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 program  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  coordinate 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 interac-
       tively,	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 elimi-
       nates the necessity for the user to repeatedly type in the same	trans-
       formation 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 mini-
       mum 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  east-
       ings and northings, depending on what coordinate systems you are trans-
       forming 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 transforma-
       tion points, the program 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 examine the resulting  residu-
       als,  to  determine how accurate the transformation will be (i.e., pick
       points with known values in both coordinate systems).  After the resid-
       uals  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	Mercator  projection. Those are states that have their
       state zones splitting the state vertically, like Illinois.   This  pro-
       gram  will  not work as well with states that use the Lambert Conformal
       Conic projection. Those are states that have their state  zones	split-
       ting  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)
