r.distance(1grass)

✨ r.distance ✨

okay bestie, gather round — this is r.distance, and no cap it's lowkey one of the most useful tools in GRASS for "how far apart are these two things actually" energy. It lives in the GRASS User's Manual, and it's giving raster, distance vibes (those are the keywords, 💅).

---

🌸 NAME 🌸

r.distance — locates the closest points between objects in two raster maps. That's it, that's the whole gig. 💖

---

🎀 KEYWORDS 🎀

raster, distance

---

🦋 SYNOPSIS 🦋

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

🌈 Flags:

• -l — include category labels in the output. yes queen, labels.
• -o — report zero distance if rasters are overlapping (they're touching, so like… zero ✋)
• -n — report null objects as * — star them out, iconic ⭐
• --help — print usage summary (when u forgot how it works, we've all been there 🙈)
• --verbose — verbose module output (it will NOT stop talking)
• --quiet — quiet module output (shhh 🤫)
• --ui — force launching GUI dialog (for the visual girlies)

💜 Parameters:

• map=name1,name2[,name1,name2,...] — required. Name of two input raster maps for computing inter-class distances. pair them UP bestie 🫶
• separator=character — field separator. Special characters you can use: pipe, comma, space, tab, newline. pick ur ~vibe~ of separator.
• sort=string — sort output by distance. Default: sorted by categories. Options: asc, desc.
  • asc: sort by distance in ascending order (small → big 🔼)
  • desc: sort by distance in descending order (big → small 🔽)
• format=name — required. output format. Options: plain, csv, json. Default: plain.
  • plain: human readable text output
  • csv: CSV (Comma Separated Values)
  • json: JSON (JavaScript Object Notation)

---

💖 DESCRIPTION 💖

So r.distance locates the closest points between "objects" in two raster maps. And before you ask — an "object" here is defined as all the grid cells that have the same category number. and "closest" means having the shortest "straight-line" distance. periodt.

The cell centers are what get considered for the distance calculation, just so u know (two adjacent grid cells have the distance between their cell centers — that's the rule, iykyk).

The output is an ascii list, one line per pair of objects, in this form:

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

Let's break down every single field, no skipping ✨:

• 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.
• -o — the -o flag reports zero distance if the input rasters are overlapping.

---

💅 NOTES 💅

The output format lends itself to filtering — it's basically built for it, main character energy fr fr. For example, to "see" lines connecting each of the category pairs in two maps, filter the output using awk and then into d.graph:

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

To create a vector map of all the "map1" coordinates, 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

---

⭐ 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 — shoutout legend, genuinely ate 🫶

---

🔥 SOURCE CODE 🔥

Available at: r.distance source code (history)

Latest change: Saturday Oct 11 04:38:40 2025 in commit: 3dd71f5fab83b72a2db2da959fe075c5b3b52200

Main index | Raster 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!! 🎀✨ this was GRASS 8.5.0, r.distance(1grass), and yes ur girl read every single line so u didn't have to. slay, go measure some distances, no cap 💖🦋