Provided by: grass-doc_6.4.3-3_all bug

NAME

       m.proj  - Convert coordinates from one projection to another (cs2cs frontend).

KEYWORDS

       miscellaneous, projection

SYNOPSIS

       m.proj
       m.proj help
       m.proj  [-iodgv]  [input=filename]   [output=filename]   [fs=character]   [proj_in=string]
       [proj_out=string]   [--verbose]  [--quiet]

   Flags:
       -i
           Use LL WGS84 as input and current location as output projection

       -o
           Use current location as input and LL WGS84 as output projection

       -d
           Output long/lat in decimal degrees, or other projections with many decimal places

       -g
           Script style output in CSV format respecting the field separator settings

       -v
           Verbose mode (print projection parameters and filenames to stderr)

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       input=filename
           Input coordinate file (omit to read from stdin)

       output=filename
           Output coordinate file (omit to send to stdout)

       fs=character
           Field separator
           Default: |

       proj_in=string
           Input projection parameters (PROJ.4 style)

       proj_out=string
           Output projection parameters (PROJ.4 style)

DESCRIPTION

       This program allows a  user  to  convert  coordinates  from  one  projection  to  another.
       Coordinates  can  be  read  from one file, converted, and results written to another file.
       Alternatively, if the input and/or output options are omitted, eastings and northings  may
       be  passed to the program directly from stdin and results sent directly to stdout. In this
       way m.proj can be used as a simple frontend to the PROJ.4 cs2cs  utility.  The  -i  or  -o
       flags  make  the  task  especially  easy  for  the common problem of converting to or from
       lat/long WGS84.

       Note: This program does not  transform  GRASS  maps,  it  is  designed  to  determine  the
       equivalent coordinate values of an individual position or list of positions. Use v.proj or
       r.proj to reproject GRASS maps.

NOTES

       cs2cs expects input data to formatted as "x y", so if working with latitude-longitude data
       be  sure  to  send  the  x  value  first,  i.e., "longitude latitude". Output data will be
       exported using the same convention.

       cs2cs will treat a third data column as a z value (elevation) and will  modify  the  value
       accordingly. This usually translates into small but real differences in that data column.

       cs2cs  does  not expect the input stream to contain column headings, only numbers. If your
       data file has lines you wish to have passed through without  being  processed,  they  must
       start with the '#' character.

       If  sending  m.proj data from stdin, be aware that the data is first stored to a temporary
       file before being processed with cs2cs.  It is therefore not advisable to send m.proj data
       from an open data stream. The module will stop listening for incoming data after 2 seconds
       of inactivity. You may use the projection parameters gleaned from  m.proj's  verbose  mode
       (-v) with cs2cs directly in this case.

       Custom  projection  parameters  can  be  used  via  the proj_in and proj_out options. Full
       documentation of the projection parameter format may be found on the PROJ.4 website. Using
       these options will fully override the default parameters the module would normally use.

       By  using the -v verbose flag, the user can see exactly what projection parameters will be
       used in the conversion as well as some other informative messages.

       If output is to lat/long, it will be formatted using PROJ.4's  Degree:Minute:Second  (DMS)
       convention  of  DDDdMM'SSS.SS"H. This can be handy if you wish to quickly convert lat/long
       decimal degree data into its DMS equivalent.
       Alternatively, to have m.proj output data in decimal degrees, use the -d flag.  This  flag
       can  also  be  used with non-lat/long data to force a higher number of decimal places (the
       cs2cs default is 2).

       Lat/long output can be converted to GRASS's DMS convention (DDD:MM:SSS.SSSH) by piping the
       results of m.proj through the sed stream editor as follows.
       m.proj -o | sed -e 's/d/:/g' -e "s/'/:/g"  -e 's/"//g'

       The  m.proj  module  is  designed to work seamlessly with point data exported from the GIS
       with v.out.ascii, as the following example shows.
       v.out.ascii bugsites | m.proj -o

EXAMPLES

       To convert a WGS84 long/lat coordinate to the current map projection using the -i flag  to
       set projection parameters automaticlly:
       GRASS> echo "170.510125 -45.868537" | m.proj -i
       2316541.70      5479193.51 1.23

       The  same, but load points from a file named "waypoints.txt" and continue on to import the
       results into a GRASS vector points map in the current map projection:
       m.proj -i in=waypoints.txt | cut -f1 -d' ' | v.in.ascii out=test_pt fs=tab
        Here the standard UNIX cut tool is used to discard the z residual.

       To convert all coordinates from a vector points map in the  current  projection  to  WGS84
       long/lat, with output in decimal form:
       v.out.ascii bugsites | m.proj -od

       To transform points from a UTM projection into the Gauss-Krüger Grid System, importing and
       exporting to files:
       m.proj proj_in="+proj=utm +name=utm +a=6378137.0 +es=0.006694380 \
           +zone=32 +unfact=1.0" proj_out="+proj=tmerc +name=tmerc \
           +a=6377397.155 +es=0.0066743720 +lat_0=0.0 +lon_0=9.0 +k=1.0 \
           +x_0=3500000.0" input=utm.coord.txt output=new.gk.coord.txt

       Projection parameters provided in the  above  case:  "+proj"  (projection  type),  "+name"
       (projection  name),  "+a"  (ellipsoid:  equatorial radius), "+es" (ellipsoid: eccentricity
       squared), "+zone" (zone for the area), "+unfact" (conversion factor from meters  to  other
       units,  e.g. feet), "+lat_0" (standard parallel), "+lon_0" (central meridian), "+k" (scale
       factor) and "+x_0" (false easting). Sometimes false northing is needed which is  coded  as
       "+y_0".   Internally,  the  underlying  PROJ.4  projection  library  performs  an  inverse
       projection to latitude-longitude and then projects  the  coordinate  list  to  the  target
       projection.

       Datum  conversions are automatically handled by the PROJ.4 library if "+datum" setings are
       specified on both the input and output projections on the  command  line.  The  "+towgs84"
       parameter  can  be  used  to  define  either  3  or  7  term datum transform coefficients,
       satisfying this requirement.

       If a datum is specified there is no need  for  the  '+ellps='  or  underlying  parameters,
       '+a=', '+es=', etc.

   Another custom parameter usage example:

       m.proj proj_in="+proj=tmerc +datum=ire65 +lat_0=53.5 +lon_0=-8 +x_0=200000 \
           +y_0=250000 +k=1.000035" proj_out="+proj=ll +datum=wgs84" input=wpt.txt
        or without datum transformation:
       m.proj proj_in="+proj=tmerc +ellps=modif_airy +lat_0=53.5 +lon_0=-8 +x_0=200000 \
           +y_0=250000 +k=1.000035" proj_out="+proj=ll +datum=wgs84" input=wpt.txt

       In  this  example no datum transformation will take place as a datum was not specified for
       the input projection. The datum specified for the output projection will thus be  silently
       ignored  and  may  be left out; all that is achieved a simple conversion from projected to
       geodetic co-ordinates, keeping the same datum (and thus also the same ellipsoid).

       For more usage examples, see the documentation for the PROJ.4 cs2cs program.

REFERENCES

       [1] Evenden, G.I.  (1990) Cartographic projection procedures for the UNIX environment -  a
       user's manual.  USGS Open-File Report 90-284 (OF90-284.pdf) See also there: Interim Report
       and 2nd Interim Report on Release 4, Evenden 1994).

       [2] PROJ.4 Cartographic Projection Library

SEE ALSO

        v.proj, r.proj, g.proj, g.setproj, i.rectify, v.in.ascii, v.out.ascii

AUTHOR

       M. Hamish Bowman, Dept. Marine Science, Otago University, New Zealand
       Functionality inspired by the m.proj and m.proj2 modules for GRASS GIS 5.

       Last changed: $Date: 2011-11-08 03:29:50 -0800 (Tue, 08 Nov 2011) $

       Full index

       © 2003-2013 GRASS Development Team