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

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

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