m.proj.html 8.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227
  1. <h2>DESCRIPTION</h2>
  2. This program allows a user to convert coordinates from one projection
  3. to another. Coordinates can be read from one file, converted, and
  4. results written to another file. Alternatively, if the <b>input=-</b>,
  5. eastings and northings may be passed to the program directly from
  6. standard input. If the <b>output</b> option is omitted, the results
  7. are sent directly to standard output. In this way <em>m.proj</em> can
  8. be used as a simple frontend to
  9. the <a href="https://proj.org/apps/cs2cs.html">PROJ</a>
  10. <em>cs2cs</em> utility. The <b>-i</b> or <b>-o</b> flags make the task
  11. especially easy for the common problem of converting to or from lat/long
  12. WGS84.
  13. <p>
  14. <i>Note</i>: This program does not transform GRASS maps, it is
  15. designed to determine the equivalent coordinate values of an
  16. individual position or list of
  17. positions. Use <em><a href="v.proj.html">v.proj</a></em> to reproject
  18. vector maps or <em><a href="r.proj.html">r.proj</a></em> for raster maps.
  19. <p>
  20. For an introduction to map projections (with PROJ),see the manual page of
  21. <a href="r.proj.html">r.proj</a>.
  22. <h2>NOTES</h2>
  23. <em>cs2cs</em> expects input data to formatted as <tt>x y</tt>, so if
  24. working with latitude-longitude data be sure to send the <tt>x</tt>
  25. value first, i.e., <tt>longitude&nbsp;latitude</tt>. Output data will
  26. be exported using the same convention.
  27. <p>
  28. <em>cs2cs</em> will treat a third data column as a <tt>z</tt> value
  29. (elevation) and will modify the value accordingly. This usually
  30. translates into small but real differences in that data column.
  31. <p>
  32. <em>cs2cs</em> does not expect the input stream to contain column
  33. headings, only numbers. If your data file has lines you wish to have
  34. passed through without being processed, they must start with the
  35. '<tt>#</tt>' character.
  36. <p>
  37. If sending <em>m.proj</em> data from standard input, be aware that the
  38. data is first stored to a temporary file before being processed
  39. with <em>cs2cs</em>. It is therefore not advisable to
  40. send <em>m.proj</em> data from an open data stream. The module will
  41. stop listening for incoming data after 2 seconds of inactivity. You
  42. may use the projection parameters gleaned from <em>m.proj</em>'s
  43. verbose mode (<b>--verbose</b>) with <em>cs2cs</em> directly in this case.
  44. <p>
  45. Custom projection parameters can be used via the <b>proj_in</b> and
  46. <b>proj_out</b> options. Full documentation of the projection
  47. parameter format may be found on
  48. the <a href="https://proj.org">PROJ</a> website. Using
  49. these options will fully override the default parameters the module
  50. would normally use.
  51. <p>
  52. By using the <b>--verbose</b> verbose flag, the user can see exactly
  53. what projection parameters will be used in the conversion as well as
  54. some other informative messages.
  55. <p>
  56. If output is to lat/long, it will be formatted using PROJ's
  57. Degree:Minute:Second (DMS) convention
  58. of <tt>DDDdMM'SSS.SS"H</tt>. This can be handy if you wish to quickly
  59. convert lat/long decimal degree data into its DMS equivalent.<br>
  60. Alternatively, to have <em>m.proj</em> output data in decimal degrees,
  61. use the <b>-d</b> flag. This flag can also be used with non-lat/long
  62. data to force a higher number of decimal places (the <em>cs2cs</em>
  63. default is 2).
  64. <p>
  65. Note that Lat/long output can be converted to GRASS's DMS convention
  66. (<tt>DDD:MM:SSS.SSSH</tt>) by piping the results of <em>m.proj</em>
  67. through the <em>sed</em> stream editor as follows.
  68. <div class="code"><pre>
  69. m.proj -o ... | sed -e 's/d/:/g' -e "s/'/:/g" -e 's/"//g'
  70. </pre></div>
  71. <h2>EXAMPLES</h2>
  72. The examples are suitable for the North Carolina sample dataset if not
  73. stated otherwise:
  74. <h3>Reproject vector point coordinate pairs to Long/Lat WGS84</h3>
  75. <p>
  76. The <em>m.proj</em> module is designed to work seamlessly with point
  77. data exported from the GIS
  78. with <em><a href="v.out.ascii.html">v.out.ascii</a></em>, as the
  79. following example shows.
  80. <div class="code"><pre>
  81. # Long/Lat WGS84 output in DMS
  82. v.out.ascii bridges | m.proj -o input=-
  83. # Long/Lat WGS84 output in decimal degree
  84. v.out.ascii bridges | m.proj -o -d input=-
  85. </pre></div>
  86. <h3>Reproject Long/Lat WGS84 coordinate pair to current map projection</h3>
  87. To convert a Long/Lat WGS84 coordinate pair to the current map projection
  88. using the <b>-i</b> flag which sets the target projection parameters
  89. automatically from the current location definition:
  90. <div class="code"><pre>
  91. echo "-78.61168178 33.92225767" | m.proj -i input=-
  92. 645513.47|19180.31|0.00
  93. </pre></div>
  94. <p>
  95. The same, but load points from a file named <tt>waypoints.txt</tt> and
  96. continue on to import the results into a GRASS vector points map in
  97. the current map projection:
  98. <div class="code"><pre>
  99. # check file content
  100. cat waypoints.txt
  101. -78.43977824 33.89587173
  102. -78.54944691 33.88964566
  103. -78.51078074 33.88141495
  104. -77.14037951 35.60543020
  105. # reproject points and generate vector map on the fly
  106. m.proj -i input=waypoints.txt | v.in.ascii input=- output=test_pnts
  107. # verify result
  108. v.db.select test_pnts cat|dbl_1|dbl_2|dbl_3
  109. 1|661427.74|16329.14|0
  110. 2|651285.43|15586.79|0
  111. 3|654867.21|14690.64|0
  112. 4|778074.58|207402.6|0
  113. </pre></div>
  114. <h3>Custom projection parameter usage</h3>
  115. To transform points from a UTM projection (here specified with detailed
  116. projection definition rather than using an EPSG code) into the
  117. Gauss-Kr&uuml;ger Grid System, importing from and exporting to files:
  118. <div class="code"><pre>
  119. m.proj proj_in="+proj=utm +name=utm +a=6378137.0 +es=0.006694380 \
  120. +zone=32 +unfact=1.0" proj_out="+proj=tmerc +name=tmerc \
  121. +a=6377397.155 +es=0.0066743720 +lat_0=0.0 +lon_0=9.0 +k=1.0 \
  122. +x_0=3500000.0" input=utm.coord.txt output=new.gk.coord.txt
  123. </pre></div>
  124. <p>
  125. Projection parameters provided in the above case: <tt>+proj</tt>
  126. (projection type), <tt>+name</tt> (projection name), <tt>+a</tt>
  127. (ellipsoid: equatorial radius), <tt>+es</tt> (ellipsoid:
  128. eccentricity squared), <tt>+zone</tt> (zone for the area),
  129. <tt>+unfact</tt> (conversion factor from meters to other units,
  130. e.g. feet), <tt>+lat_0</tt> (standard parallel), <tt>+lon_0</tt>
  131. (central meridian), <tt>+k</tt> (scale factor) and <tt>+x_0</tt>
  132. (false easting). Sometimes false northing is needed which is coded as
  133. <tt>+y_0</tt>. Internally, the underlying
  134. <a href="https://proj.org">PROJ</a> projection library
  135. performs an inverse projection to latitude-longitude and then projects
  136. the coordinate list to the target projection.
  137. <p>
  138. Datum conversions are automatically handled by the PROJ library if
  139. <tt>+datum</tt> setings are specified on <b>both</b> the input <b>and</b> output
  140. projections on the command line. The <tt>+towgs84</tt> parameter can be used to
  141. define either 3 or 7 term datum transform coefficients, satisfying this requirement.
  142. <p>If a datum is specified there is no need for the <tt>+ellps=</tt> or underlying
  143. parameters, <tt>+a=</tt>, <tt>+es=</tt>, etc.
  144. <p>
  145. Another custom parameter usage example:
  146. <div class="code"><pre>
  147. m.proj proj_in="+proj=tmerc +datum=ire65 +lat_0=53.5 +lon_0=-8 +x_0=200000 \
  148. +y_0=250000 +k=1.000035" proj_out="+proj=ll +datum=wgs84" input=wpt.txt
  149. </pre></div>
  150. or without datum transformation:
  151. <div class="code"><pre>
  152. m.proj proj_in="+proj=tmerc +ellps=modif_airy +lat_0=53.5 +lon_0=-8 +x_0=200000 \
  153. +y_0=250000 +k=1.000035" proj_out="+proj=ll +datum=wgs84" input=wpt.txt
  154. </pre></div>
  155. <p>
  156. In this example no datum transformation will take place as a datum was
  157. not specified for the input projection. The datum specified for the
  158. output projection will thus be silently ignored and may be left out;
  159. all that is achieved a simple conversion from projected to geodetic
  160. co-ordinates, keeping the same datum (and thus also the same
  161. ellipsoid).
  162. <p>
  163. For more usage examples, see the documentation for the
  164. <a href="https://proj.org">PROJ</a> <em>cs2cs</em> program.
  165. <h2>REFERENCES</h2>
  166. <ul>
  167. <li>Evenden, G.I.
  168. (1990) <a href="https://pubs.usgs.gov/of/1990/of90-284/ofr90-284.pdf">Cartographic
  169. projection procedures for the UNIX environment - a user's
  170. manual</a>. USGS Open-File Report 90-284 (OF90-284.pdf) See
  171. also there: Interim Report and 2nd Interim Report on Release 4,
  172. Evenden 1994).</li>
  173. <li><a href="https://proj.org">PROJ</a> Cartographic Projection Library</li>
  174. </ul>
  175. <h2>SEE ALSO</h2>
  176. <em>
  177. <a href="g.proj.html">g.proj</a>,
  178. <a href="r.proj.html">r.proj</a>,
  179. <a href="v.proj.html">v.proj</a>,
  180. <a href="i.rectify.html">i.rectify</a>,
  181. <a href="v.in.ascii.html">v.in.ascii</a>,
  182. <a href="v.out.ascii.html">v.out.ascii</a>
  183. </em>
  184. <h2>AUTHOR</h2>
  185. M. Hamish Bowman, Dept. Marine Science, Otago University, New Zealand<br>
  186. Functionality inspired by the <em>m.proj</em> and <em>m.proj2</em> modules for
  187. GRASS GIS 5.
  188. <!--
  189. <p>
  190. <i>Last changed: $Date$</i>
  191. -->