.TH m.proj 1grass "" "GRASS 7.8.5" "GRASS GIS User's Manual"
.SH NAME
\fI\fBm.proj\fR\fR  \- Converts coordinates from one projection to another (cs2cs frontend).
.SH KEYWORDS
miscellaneous, projection, transformation
.SH SYNOPSIS
\fBm.proj\fR
.br
\fBm.proj \-\-help\fR
.br
\fBm.proj\fR [\-\fBiodec\fR]  [\fBcoordinates\fR=\fIeast,north\fR]   [\fBinput\fR=\fIname\fR]   [\fBoutput\fR=\fIname\fR]   [\fBseparator\fR=\fIcharacter\fR]   [\fBproj_in\fR=\fIstring\fR]   [\fBproj_out\fR=\fIstring\fR]   [\-\-\fBoverwrite\fR]  [\-\-\fBhelp\fR]  [\-\-\fBverbose\fR]  [\-\-\fBquiet\fR]  [\-\-\fBui\fR]
.SS Flags:
.IP "\fB\-i\fR" 4m
.br
Use LL WGS84 as input and current location as output projection
.IP "\fB\-o\fR" 4m
.br
Use current location as input and LL WGS84 as output projection
.IP "\fB\-d\fR" 4m
.br
Output long/lat in decimal degrees, or other projections with many decimal places
.IP "\fB\-e\fR" 4m
.br
Include input coordinates in output file
.IP "\fB\-c\fR" 4m
.br
Include column names in output file
.IP "\fB\-\-overwrite\fR" 4m
.br
Allow output files to overwrite existing files
.IP "\fB\-\-help\fR" 4m
.br
Print usage summary
.IP "\fB\-\-verbose\fR" 4m
.br
Verbose module output
.IP "\fB\-\-quiet\fR" 4m
.br
Quiet module output
.IP "\fB\-\-ui\fR" 4m
.br
Force launching GUI dialog
.SS Parameters:
.IP "\fBcoordinates\fR=\fIeast,north\fR" 4m
.br
Input coordinates to reproject
.IP "\fBinput\fR=\fIname\fR" 4m
.br
Name of input coordinate file
.br
\(cq\-\(cq for standard input
.IP "\fBoutput\fR=\fIname\fR" 4m
.br
Name for output coordinate file (omit to send to stdout)
.IP "\fBseparator\fR=\fIcharacter\fR" 4m
.br
Field separator (format: input[,output])
.br
Special characters: pipe, comma, space, tab, newline
.br
Default: \fIpipe\fR
.IP "\fBproj_in\fR=\fIstring\fR" 4m
.br
Input projection parameters (PROJ.4 style)
.IP "\fBproj_out\fR=\fIstring\fR" 4m
.br
Output projection parameters (PROJ.4 style)
.SH 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 \fBinput=\-\fR,
eastings and northings may be passed to the program directly from
standard input. If the \fBoutput\fR option is omitted, the results
are sent directly to standard output. In this way \fIm.proj\fR can
be used as a simple frontend to
the PROJ
\fIcs2cs\fR utility. The \fB\-i\fR or \fB\-o\fR flags make the task
especially easy for the common problem of converting to or from lat/long
WGS84.
.PP
\fINote\fR: 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 \fIv.proj\fR to reproject
vector maps or \fIr.proj\fR for raster maps.
.SH NOTES
\fIcs2cs\fR 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.
.PP
\fIcs2cs\fR 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.
.PP
\fIcs2cs\fR 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
\(cq#\(cq character.
.PP
If sending \fIm.proj\fR data from standard input, be aware that the
data is first stored to a temporary file before being processed
with \fIcs2cs\fR.  It is therefore not advisable to
send \fIm.proj\fR 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 \fIm.proj\fR\(cqs
verbose mode (\fB\-\-verbose\fR) with \fIcs2cs\fR directly in this case.
.PP
Custom projection parameters can be used via the \fBproj_in\fR and
\fBproj_out\fR options. Full documentation of the projection
parameter format may be found on
the PROJ website. Using
these options will fully override the default parameters the module
would normally use.
.PP
By using the \fB\-\-verbose\fR verbose flag, the user can see exactly
what projection parameters will be used in the conversion as well as
some other informative messages.
.PP
If output is to lat/long, it will be formatted using PROJ\(cqs
Degree:Minute:Second (DMS) convention
of DDDdMM\(cqSSS.SS\(dqH. This can be handy if you wish to quickly
convert lat/long decimal degree data into its DMS equivalent.
.br
Alternatively, to have \fIm.proj\fR output data in decimal degrees,
use the \fB\-d\fR flag. This flag can also be used with non\-lat/long
data to force a higher number of decimal places (the \fIcs2cs\fR
default is 2).
.PP
Note that Lat/long output can be converted to GRASS\(cqs DMS convention
(DDD:MM:SSS.SSSH) by piping the results of \fIm.proj\fR
through the \fIsed\fR stream editor as follows.
.br
.nf
\fC
m.proj \-o ... | sed \-e \(cqs/d/:/g\(cq \-e \(dqs/\(cq/:/g\(dq  \-e \(cqs/\(dq//g\(cq
\fR
.fi
.SH EXAMPLES
The examples are suitable for the North Carolina sample dataset if not
stated otherwise:
.SS Reproject vector point coordinate pairs to Long/Lat WGS84
.PP
The \fIm.proj\fR module is designed to work seamlessly with point
data exported from the GIS
with \fIv.out.ascii\fR, as the
following example shows.
.br
.nf
\fC
# Long/Lat WGS84 output in DMS
v.out.ascii bridges | m.proj \-o input=\-
# Long/Lat WGS84 output in decimal degree
v.out.ascii bridges | m.proj \-o \-d input=\-
\fR
.fi
.SS Reproject Long/Lat WGS84 coordinate pair to current map projection
To convert a Long/Lat WGS84 coordinate pair to the current map projection
using the \fB\-i\fR flag which sets the target projection parameters
automatically from the current location definition:
.br
.nf
\fC
echo \(dq\-78.61168178 33.92225767\(dq | m.proj \-i input=\-
645513.47|19180.31|0.00
\fR
.fi
.PP
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:
.br
.nf
\fC
# check file content
cat waypoints.txt
\-78.43977824 33.89587173
\-78.54944691 33.88964566
\-78.51078074 33.88141495
\-77.14037951 35.60543020
# reproject points and generate vector map on the fly
m.proj \-i input=waypoints.txt | v.in.ascii input=\- output=test_pnts
# verify result
v.db.select test_pnts cat|dbl_1|dbl_2|dbl_3
1|661427.74|16329.14|0
2|651285.43|15586.79|0
3|654867.21|14690.64|0
4|778074.58|207402.6|0
\fR
.fi
.SS Custom projection parameter usage
To transform points from a UTM projection (here specified with detailed
projection definition rather than using an EPSG code) into the
Gauss\-Krüger Grid System, importing from and exporting to files:
.br
.nf
\fC
m.proj proj_in=\(dq+proj=utm +name=utm +a=6378137.0 +es=0.006694380 \(rs
    +zone=32 +unfact=1.0\(dq proj_out=\(dq+proj=tmerc +name=tmerc \(rs
    +a=6377397.155 +es=0.0066743720 +lat_0=0.0 +lon_0=9.0 +k=1.0 \(rs
    +x_0=3500000.0\(dq input=utm.coord.txt output=new.gk.coord.txt
\fR
.fi
.PP
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 projection library
performs an inverse projection to latitude\-longitude and then projects
the coordinate list to the target projection.
.PP
Datum conversions are automatically handled by the PROJ library if
+datum setings are specified on \fBboth\fR the input \fBand\fR 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.
.PP
If a datum is specified there is no need for the +ellps= or underlying
parameters, +a=, +es=, etc.
.PP
Another custom parameter usage example:
.br
.nf
\fC
m.proj proj_in=\(dq+proj=tmerc +datum=ire65 +lat_0=53.5 +lon_0=\-8 +x_0=200000 \(rs
    +y_0=250000 +k=1.000035\(dq proj_out=\(dq+proj=ll +datum=wgs84\(dq input=wpt.txt
\fR
.fi
or without datum transformation:
.br
.nf
\fC
m.proj proj_in=\(dq+proj=tmerc +ellps=modif_airy +lat_0=53.5 +lon_0=\-8 +x_0=200000 \(rs
    +y_0=250000 +k=1.000035\(dq proj_out=\(dq+proj=ll +datum=wgs84\(dq input=wpt.txt
\fR
.fi
.PP
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).
.PP
For more usage examples, see the documentation for the
PROJ \fIcs2cs\fR program.
.SH REFERENCES
.RS 4n
.IP \(bu 4n
Evenden, G.I.
(1990) Cartographic
projection procedures for the UNIX environment \- a user\(cqs
manual.  USGS Open\-File Report 90\-284 (OF90\-284.pdf) See
also there: Interim Report and 2nd Interim Report on Release 4,
Evenden 1994).
.IP \(bu 4n
PROJ Cartographic Projection Library
.RE
.SH SEE ALSO
\fI
g.proj,
r.proj,
v.proj,
i.rectify,
v.in.ascii,
v.out.ascii
\fR
.SH AUTHOR
M. Hamish Bowman, Dept. Marine Science, Otago University, New Zealand
.br
Functionality inspired by the \fIm.proj\fR and \fIm.proj2\fR modules for
GRASS GIS 5.
.SH SOURCE CODE
.PP
Available at: m.proj source code (history)
.PP
Main index |
Miscellaneous index |
Topics index |
Keywords index |
Graphical index |
Full index
.PP
© 2003\-2020
GRASS Development Team,
GRASS GIS 7.8.5 Reference Manual