r.proj(1grass)

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

💖 r.proj 💖

heyyy bestie, welcome to the GRASS User's Manual entry for r.proj 🌸 this one is long, so it's coming at you in two parts — this is part 1, and the rest is right behind it, don't wander off 😭

🎀 NAME 🎀

r.proj — Re-projects a raster map from given project to the current project. that's the whole job description, and she does it flawlessly 💅

🏷️ KEYWORDS 🏷️

raster, projection, transformation, import

✨ SYNOPSIS ✨

r.proj
r.proj --help
r.proj [-lnpg] project=name  [mapset=name]   [input=name]   [dbase=path]
[output=name]   [method=string]   [memory=memory in MB]
[resolution=float]  format=name  [pipeline=string]   [--overwrite]
[--help]  [--verbose]  [--quiet]  [--ui]

🚩 Flags 🚩

  • -l — List raster maps in input mapset and exit 🗒️
  • -n — Do not perform region cropping optimization. See Notes if working with a global latitude-longitude projection
  • -p — Print input map’s bounds in the current projection and exit 📐
  • -g — Print input map’s bounds in the current projection in shell script style [deprecated]
⚠️ This flag is deprecated and will be removed in a future release. Use format=shell instead. she's on her way out, bestie, plan accordingly 🙈
  • --overwrite — Allow output files to overwrite existing files
  • --help — Print usage summary
  • --verbose — Verbose module output
  • --quiet — Quiet module output
  • --ui — Force launching GUI dialog

🎛️ Parameters 🎛️

  • project=name [required] — Project (location) containing input raster map
    • Project name (not path to project) — name only, okay? not the path 🫶
  • mapset=name — Mapset containing input raster map
    • Default: name of current mapset
  • input=name — Name of input raster map to re-project
  • dbase=path — Path to GRASS database of input project
    • Default: path to the current GRASS database
  • output=name — Name for output raster map (default: same as 'input')
  • method=string — Interpolation method to use
    • Options: nearest, bilinear, bicubic, lanczos, bilinear_f, bicubic_f, lanczos_f
    • Default: nearest
    • nearest: nearest neighbor
    • bilinear: bilinear interpolation
    • bicubic: bicubic interpolation
    • lanczos: lanczos filter
    • bilinear_f: bilinear interpolation with fallback
    • bicubic_f: bicubic interpolation with fallback
    • lanczos_f: lanczos filter with fallback
  • memory=memory in MB — Maximum memory to be used (in MB)
    • Cache size for raster rows
    • Default: 300
  • resolution=float — Resolution of output raster map
  • format=name [required] — Output format
    • Options: plain, shell, json
    • Default: plain
    • plain: Human readable text output
    • shell: shell script style text output
    • json: JSON (JavaScript Object Notation)
  • pipeline=string — PROJ pipeline for coordinate transformation

🌍 DESCRIPTION 🌍

okay so r.proj is how you reproject a raster map from the coordinate reference system (CRS) of the input project into a CRS of a specified project (they used to call these locations, for the record 🫶). where does it get the CRS intel? from the current PROJ_INFO files — the exact ones you set and view with g.proj. no cap. ✨

💭 Introduction 💭

🗺️ Map projections 🗺️

so, the lore 📚: map projections are a method of representing information from a curved surface (usually a spheroid) in two dimensions — typically so you can index things through cartesian coordinates. and bestie there are a wide variety of projections out there. the common ones split into a few classes: cylindrical and pseudo-cylindrical, conic and pseudo-conic, and azimuthal methods — and each of those can be conformal, equal-area, or honestly neither 🙈

which projection you pick depends on the purpose of the project, plus the size, shape and location of the area of interest. for example, normal cylindrical projections are good for maps which are of greater extent east-west than north-south and in equatorial regions, while conic projections are better in mid-latitudes. transverse cylindrical projections get used for maps which are of greater extent north-south than east-west, and azimuthal projections are the move for polar regions. oblique versions of any of these may also be used, she contains multitudes. conformal projections preserve angular relationships and better preserve arc-length, while equal-area projections are more appropriate for statistical studies and work in which the amount of material is important.

projections are defined by precise mathematical relations, so the method of projecting coordinates from a geographic reference frame (latitude-longitude) into a projected cartesian reference frame (eg metres) is governed by those equations. inverse projections can also be achieved, btw, it goes both ways 🔄 the public-domain Unix software package PROJ [1] was designed to perform these transformations, and the user's manual contains a detailed description of over 100 useful projections 👑 it also includes a programmers library of the projection methods to support other software development.

so: converting a vector map — where objects are located with arbitrary spatial precision — from one projection into another is usually a simple two-step process. first, the location of all the points in the map are converted from the source through an inverse projection into latitude-longitude, and then through a forward projection into the target. (of course the procedure will be one-step if either the source or target is in geographic coordinates. slay.) 🦋

but converting a raster map, or image, between different projections involves additional considerations 😭 a raster may be considered to represent a sampling of a process at a regular, ordered set of locations. and here's the plot twist: the set of locations that lie at the intersections of a cartesian grid in one projection will not, in general, coincide with the sample points in another projection. so raster conversion involves an interpolation step, in which the values of points at intermediate locations relative to the source grid are estimated. yeah. that's the whole thing. 💀

🌐 Reprojecting vector maps within GRASS 🌐

GIS data capture, import and transfer often requires a reprojection step, since the source or client will frequently be in a different CRS to the working CRS. it's just how it is.

in some cases it's convenient to do the conversion outside the package, prior to import or after export, using software such as PROJ's cs2cs [1]. this is an easy method for converting an ASCII file containing a list of coordinate points, since there is no topology to be preserved and cs2cs can be used to process simple lists using a one-line command. and the m.proj module provides a handy front end to cs2cs. cute. 🎀

vector maps is generally more complex, as parts of the data stored in the files will describe topology, and not just coordinates. in GRASS the v.proj module is provided to reproject vector maps, transferring topology and attributes as well as node coordinates. this program uses the CRS definition and parameters which are stored in the PROJ_INFO and PROJ_UNITS files in the PERMANENT mapset directory for every GRASS project.

🧚 Design of r.proj 🧚

as discussed briefly above (and by briefly I mean a whole essay, stay with me), the fundamental step in reprojecting a raster is resampling the source grid at locations corresponding to the intersections of a grid in the target CRS. so the basic procedure for accomplishing this is as follows:

r.proj converts a map to a new CRS. It reads a map from a different project, reprojects it and writes it out to the current project. the reprojected data is resampled with one of four different methods: nearest neighbor, bilinear, bicubic interpolation or lanczos. ✨

  • method=nearest — performs a nearest neighbor assignment, and is the fastest of the three resampling methods. it's primarily used for categorical data such as a land use classification, since it will not change the values of the data cells. icon behavior, honestly.
  • method=bilinear — determines the new value of the cell based on a weighted distance average of the 4 surrounding cells in the input map.
  • method=bicubic — determines the new value of the cell based on a weighted distance average of the 16 surrounding cells in the input map.
  • method=lanczos — determines the new value of the cell based on a weighted distance average of the 25 surrounding cells in the input map. compared to bicubic, lanczos puts a higher weight on cells close to the center and a lower weight on cells away from the center, resulting in slightly better contrast. 👑

the bilinear, bicubic and lanczos interpolation methods are most appropriate for continuous data and cause some smoothing. the amount of smoothing decreases from bilinear to bicubic to lanczos. and bestie, these options should not be used with categorical data, since the cell values will be altered. that's not a vibe, that's data loss. 🙈

in the bilinear, bicubic and lanczos methods, if any of the surrounding cells used to interpolate the new cell value are NULL, the resulting cell will be NULL, even if the nearest cell is not NULL. this will cause some thinning along NULL borders, such as the coasts of land areas in a DEM. the bilinear_f, bicubic_f and lanczos_f interpolation methods can be used if thinning along NULL edges is not desired. these methods "fall back" to simpler interpolation methods along NULL borders. that is, from lanczos to bicubic to bilinear to nearest. 🪄

if nearest neighbor assignment is used, the output map has the same raster format as the input map. if any of the interpolations is used, the output map is written as floating point.

📌 note that, following normal GRASS conventions, the coverage and resolution of the resulting grid is set by the current region settings, which may be adjusted using g.region. the target raster will be relatively unbiased for all cases if its grid has a similar resolution to the source, so that the resampling/interpolation step is only a local operation. if the resolution is changed significantly, then the behaviour of the generalisation or refinement will depend on the model of the process being represented. this will be very different for categorical versus numerical data. note that three methods for the local interpolation step are provided.

r.proj supports general datum transformations, making use of the PROJ co-ordinate system translation library. 💫

okay that's the whole first half, bestie — stick around, because the rest of this page is coming up next 😌

📝 NOTES 📝

okay bestie, housekeeping time 💖 so here's the lil list of defaults that just happen:

  • If output isn't given, it gets set to be the same as the input map name. easy peasy.
  • If mapset isn't given, its name is assumed to be the same as your current mapset's name.
  • If dbase isn't given, it's assumed to be the current database. You only have to specify dbase if the source project lives in a whole separate GRASS database. iykyk 🗂️

Now, bestie, listen 🔥 reprojecting a map takes time, and you do NOT want it taking forever. So you really should set the region and resolution of the target project appropriately beforehand. Set the vibe before you do the thing. ✨

A simple way to do this: check the projected bounds of the input map in the current project's CRS using the -p flag. The -g flag reports the same thing, but in a form you can directly cut and paste into a g.region command. 🎀 After setting the region that way, you might check the cell resolution with g.region -p, then snap it to a regular grid with g.region's -a flag. Like: g.region -a res=5 -p. Note that this is just a rough guide. 💅

A more involved, but more accurate, way to do this is to generate a vector "box" map of the region in the source project using v.in.region -d. That "box" map then gets reprojected into the target project with v.proj. Next, the region in the target project is set to the extent of the new vector map using g.region, along with the desired raster resolution (g.region -m can be used in Latitude/Longitude projects to measure the geodetic length of a pixel, iconic 🌈). Then r.proj is run for the raster map you want to reproject. In this case, a little preparation goes a long way. no cap.

⚠️ When reprojecting whole-world maps, you should disable map-trimming with the -n flag. Trimming is not useful here because the module has the whole map in memory anyway. Besides that, world "edges" are hard (or, like, impossible 😭) to find in CRSs other than latitude-longitude, so results may be odd with trimming. Consider yourself warned bestie.

💫 EXAMPLES 💫

🌸 Inline method 🌸

With GRASS running in the destination project, use the -g flag to show the input map's bounds once reprojected into the current working CRS, then use that to set the region bounds before performing the reprojection. here we go:

# calculate where output map will be
r.proj input=elevation project=ll_wgs84 mapset=user1 -p
Source cols: 8162
Source rows: 12277
Local north: -4265502.30382993
Local south: -4473453.15255565
Local west: 14271663.19157564
Local east: 14409956.2693866
# same calculation, but in a form which can be cut and pasted into a g.region call
r.proj input=elevation project=ll_wgs84 mapset=user1 -g
n=-4265502.30382993 s=-4473453.15255565 w=14271663.19157564 e=14409956.2693866 rows=12277 cols=8162
g.region n=-4265502.30382993 s=-4473453.15255565 \
  w=14271663.19157564 e=14409956.2693866 rows=12277 cols=8162 -p
projection: 99 (Mercator)
zone:       0
datum:      wgs84
ellipsoid:  wgs84
north:      -4265502.30382993
south:      -4473453.15255565
west:       14271663.19157564
east:       14409956.2693866
nsres:      16.93824621
ewres:      16.94352828
rows:       12277
cols:       8162
cells:      100204874
# round resolution to something cleaner
g.region res=17 -a -p
projection: 99 (Mercator)
zone:       0
datum:      wgs84
ellipsoid:  wgs84
north:      -4265487
south:      -4473465
west:       14271653
east:       14409965
nsres:      17
ewres:      17
rows:       12234
cols:       8136
cells:      99535824
# finally, perform the reprojection
r.proj input=elevation project=ll_wgs84 mapset=user1 memory=800

🦋 v.in.region method 🦋

# In the source project, use v.in.region to generate a bounding box around the
# region of interest:
v.in.region -d output=bounds type=area
# Now switch to the target project and import the vector bounding box
# (you can run v.proj -l to get a list of vector maps in the source project):
v.proj input=bounds project=source_project_name output=bounds_reprojected
# Set the region in the target project with that of the newly-imported vector
# bounds map, and align the resolution to the desired cell resolution of the
# final, reprojected raster map:
g.region vector=bounds_reprojected res=5 -a
# Now reproject the raster into the target project
r.proj input=elevation.dem output=elevation.dem.reproj \
  project=source_project_name mapset=PERMANENT res=5 method=bicubic

📚 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. Richards, John A. (1993), Remote Sensing Digital Image Analysis, Springer-Verlag, Berlin, 2nd edition.

PROJ: Projection/datum support library

Further reading 👀

  • ASPRS Grids and Datum
  • Projections Transform List (PROJ)
  • Coordinate operations by PROJ (projections, conversions, transformations, pipeline operator)
  • MapRef - The Collection of Map Projections and Reference Systems for Europe
  • Information and Service System for European Coordinate Reference Systems - CRS

👀 SEE ALSO 👀

g.region, g.proj, i.rectify, m.proj, r.support, r.stats, v.proj, v.in.region

The 'gdalwarp' and 'gdal_translate' utilities are available from the GDAL project. 🛠️

💖 AUTHORS 💖

  • Martin Schroeder, University of Heidelberg, Germany
  • Man page text from S.J.D. Cox, AGCRC, CSIRO Exploration & Mining, Nedlands, WA
  • Updated by Morten Hulden
  • Datum transformation support and cleanup by Paul Kelly
  • Support of PROJ5+ by Markus Metz, mundialis

🌟 SOURCE CODE 🌟

Available at: r.proj source code (history)

Latest change: Monday Dec 08 21:47:55 2025 in commit: d3c6479bef77a58e3b5d85259303dbfb9c1babe8

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

okay that's the whole page bestie, you're officially a reprojection girlie now 💅✨ this was GRASS 8.5.0, r.proj(1grass), and the copyright is © 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual. go reproject something, slay 🫶🌈💖

📦 where this page comes from