r.distance(1)

✨ r.distance ✨

okay bestie, gather round, because this is the GRASS GIS User's Manual page for r.distance, and it is genuinely one of the most useful little tools in the whole raster toolbox, no cap 💖

🎀 NAME 🎀

r.distance — finds the closest points between objects living in two raster maps. like, it's giving matchmaker but for grid cells 💅

🔑 KEYWORDS 🔑

raster, distance

---

🦋 SYNOPSIS 🦋

r.distance
r.distance --help
r.distance [-lon] map=name1,name2[,name1,name2,...]
[separator=character]   [sort=string]   [--help]  [--verbose]  [--quiet]
[--ui]

🚩 Flags

• -l — bestie, include those category labels in the output, they matter 💖
• -o — if the rasters are overlapping, just report zero distance. overlapping? zero. periodt.
• -n — report null objects as *. yes, the literal asterisk. iconic.
• --help — prints the usage summary, for when you're lost (we've all been there 🙈)
• --verbose — verbose module output, aka it tells you EVERYTHING
• --quiet — quiet module output, aka it tells you nothing, main character silence ✨
• --ui — force launches the GUI dialog. fancy. slay.

🌸 Parameters

• map=name1,name2[,name1,name2,...] — required, bestie, you literally cannot skip this one. name of the two input raster maps you want inter-class distances for.
• separator=character — the field separator. special characters you can use: pipe, comma, space, tab, newline. Default: :
• sort=string — sorts the output by distance. Default: sorted by categories. Options: asc, desc
  • asc: sort by distance in ascending order (smallest first, lil baby distances 🥺)
  • desc: sort by distance in descending order (biggest first, dramatic distances 💀)

---

💜 DESCRIPTION 💜

so r.distance locates the closest points between "objects" in two raster maps. and what even is an "object", you ask? an "object" is defined as all the grid cells that have the same category number, and "closest" means having the shortest "straight-line" distance. the cell centers are what we're measuring from — so two adjacent grid cells have the distance between their cell centers. not the edges. the centers. important. 🫶

the output is an ascii list, one line per pair of objects, looking exactly like this:

cat1:cat2:distance:east1:north1:east2:north2

and here's the breakdown, no gatekeeping:

• cat1 — category number from map1
• cat2 — category number from map2
• distance — the distance in meters between cat1 and cat2
• east1,north1 — the coordinates of the grid cell cat1 which is closest to cat2
• east2,north2 — the coordinates of the grid cell cat2 which is closest to cat1

✨ Flags ✨

• -l — the -l flag outputs the category labels of the matched raster objects at the beginning of the line, if they exist. if they don't exist... they just don't show up. vibe check failed, moving on.
• -o — the -o flag reports zero distance if the input rasters are overlapping.

---

🌈 NOTES 🌈

the output format lends itself to filtering, which is lowkey the best part. for example, to "see" lines connecting each of the category pairs in two maps, you filter the output using awk and then pipe it into d.graph:

r.distance map=map1,map2 | \
  awk -F: ’{print "move",$4,$5,"\ndraw",$6,$7}’ | d.graph -m

and to create a vector map of all the map1 coordinates, you filter the output into awk and then into v.in.ascii:

r.distance map=map1,map2 | \
  awk -F: ’{print $4,$5}’ | v.in.ascii format=point output=name separator=space

like?? the way it just slots into your pipeline?? obsessed. 🔥

---

👀 SEE ALSO 👀

r.buffer, r.cost, r.drain, r.grow, r.grow.distance, v.distance

---

👑 AUTHOR 👑

Michael Shapiro, U.S. Army Construction Engineering Research Laboratory

---

🧚 SOURCE CODE 🧚

available at: r.distance source code (history)

accessed: Saturday Jan 17 05:40:45 2026

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

---

okay that's the whole page, bestie, you ate it up 💅 this was the GRASS GIS 8.4.2 Reference Manual, brought to you by the GRASS Development Team, © 2003-2025 — and the access date on the source was Saturday Jan 17 05:40:45 2026, so like, mark your calendar or whatever. go compute some distances, ily 🦋🌸💖