m.proj(1grass)

📦
version 8.5.0 · 10 versions
, in alpine 3.24, ubuntu stonking

💅 m.proj — the GRASS manual, but make it cute

okay bestie, welcome to m.proj from the GRASS User's Manual 💖 this is the one that converts coordinates from one projection to another — it's literally a cs2cs frontend, no cap. She's little, she's powerful, she's giving main character energy ✨

KEYWORDS: miscellaneous, projection, transformation 🦋

✨ SYNOPSIS ✨

m.proj
m.proj --help
m.proj [-iodec]  [coordinates=east,north]   [input=name]   [output=name]
[separator=character]   [proj_in=string]   [proj_out=string]
[--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

🎀 FLAGS (the little switches, she's obsessed) 🎀

  • -i — use LL WGS84 as the input and your current location as the output projection. it's giving "i have lat/long, pls make it map-shaped" 🫶
  • -o — the other way around: use your current location as input and LL WGS84 as output 🌸
  • -d — output long/lat in decimal degrees, or use it for other projections when you want many decimal places 🔥
  • -e — include the input coordinates in the output file 🍓
  • -c — include column names in the output file ⭐
  • --overwrite — allow output files to overwrite existing files (chaotic, but permitted) 💀
  • --help — print usage summary 🙈
  • --verbose — verbose module output (she tells you EVERYTHING) 👑
  • --quiet — quiet module output 🤫
  • --ui — force launching the GUI dialog ✨

🦋 PARAMETERS 🦋

  • coordinates=east,north — the input coordinates you want reprojected 📍
  • input=name — name of the input coordinate file. use '-' for standard input 💫
  • output=name — name for the output coordinate file (just omit it and she sends everything to <cyan>stdout</cyan>) 🌈
  • separator=character — field separator, formatted as input[,output]. special characters you can use: pipe, comma, space, tab, newline. Default: pipe 🧚
  • proj_in=string — input projection parameters, PROJ.4 style 💜
  • proj_out=string — output projection parameters, PROJ.4 style 💜

💖 DESCRIPTION 💖

okay so here's the whole vibe: this program lets you convert coordinates from one projection to another. you can read coordinates from one file, convert them, and write the results to another file. OR, if you set input=-, you can pass eastings and northings straight to the program from standard input 🫶. and if you just... don't give an output option? she sends the results directly to standard output. so in that way, m.proj is basically a simple frontend to the PROJ cs2cs utility ⭐. the -i or -o flags make it especially easy for the super common problem of converting to or from lat/long WGS84 ✨

Note: this program does NOT transform GRASS maps, bestie. she's designed to determine the equivalent coordinate values of an individual position or a list of positions. use v.proj to reproject vector maps, or r.proj for raster maps 🗺️

for an introduction to map projections (with PROJ), see the manual page of r.proj 📚

🌸 NOTES (the fine print, but make it fashion) 🌸

cs2cs expects input data to be formatted as x y, so if you're 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, periodt 💅

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. so if your data file has lines you wish to have passed through without being processed, they must start with the '#' character 🎀

if you're sending m.proj data from standard input, be aware of this: the data is first stored to a temporary file before being processed with cs2cs. so 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. in that case, you may use the projection parameters gleaned from m.proj's verbose mode (--verbose) with cs2cs directly 👑

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 website. using these options will fully override the default parameters the module would normally use 😮

by using the --verbose verbose flag, you can see exactly what projection parameters will be used in the conversion, plus some other informative messages 🔍

if output is to lat/long, it will be formatted using PROJ'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) 🔢

note that 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’

🔥 EXAMPLES 🔥

the examples are suitable for the North Carolina sample dataset if not stated otherwise 🌲

🌈 Reproject vector point coordinate pairs to Long/Lat WGS84

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 💫

# 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=-

💜 Reproject Long/Lat WGS84 coordinate pair to current map projection

to convert a Long/Lat WGS84 coordinate pair to the current map CRS using the -i flag — which sets the target projection parameters automatically from the current project definition 📍:

echo "-78.61168178 33.92225767" | m.proj -i input=-
645513.47|19180.31|0.00

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 🫶:

# 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

🎀 Custom projection parameter usage

to transform points from a UTM projection (here specified with a detailed projection definition rather than using an EPSG code) into the Gauss-Krüger Grid System, importing from 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, decoded for you bestie 📖:

  • +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
  • +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 🌀

datum conversions are automatically handled by the PROJ library if +datum settings 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 is 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 cs2cs program 📚

⭐ REFERENCES ⭐

  • 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).
  • PROJ Cartographic Projection Library

👀 SEE ALSO 👀

g.proj, r.proj, v.proj, 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 ✨

🫶 SOURCE CODE 🫶

Available at: m.proj source code (history)

Latest change: Tuesday Oct 21 09:57:14 2025 in commit: fb0165c2d021b7700528aca09c224847be871729

Main index | Miscellaneous index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual

and that's the whole page bestie 🥹💖 m.proj(1grass) from the GRASS 8.5.0 manual, latest change Tuesday Oct 21 09:57:14 2025, © 2003-2026 GRASS Development Team. go reproject something slay 💅✨

📦 where this page comes from