r.surf.area(1grass)

💖 r.surf.area — the manual page, but make it cute 💖

okay so bestie, welcome to r.surf.area from the GRASS User's Manual 🫶 it prints out an estimation of surface area for a raster map. that's it. that's the girl. ✨

🔑 KEYWORDS ✨

raster, surface, statistics, area estimation

📜 SYNOPSIS 💅

r.surf.area
r.surf.area --help
r.surf.area map=name  [vscale=float]   [units=string]   [--help]
[--verbose]  [--quiet]  [--ui]

🎀 Flags

• --help — prints the usage summary, aka the cheat sheet, the tl;dr, the "what does this even do" button 🥰
• --verbose — verbose module output, she's chatty and we love that for her 🌸
• --quiet — quiet module output, she's giving mysterious, minimal, silent queen 🤫
• --ui — forces the GUI dialog to launch, no terminal typing era 💅

🌈 Parameters

• map=name — required, no skipping, bestie. this is the name of the raster map you're judging 📛
• vscale=float — vertical scale. default is 1.0 ⬆️
• units=string — output units. default is square map units. your options are: miles, feet, meters, kilometers, acres, hectares 📏

---

📖 DESCRIPTION ✨

so what's she actually doing? r.surf.area calculates the area of regular 3D triangulated points — and those points are the centers of cells — in the current region, by adding up the areas of all the triangles. simple. iconic. 🦋

but here's the tea: because of that, the area of a flat surface gets reported as (rows + cols -1) * (area of cell) less than the area of the flat region. why?? because there's half a row and half a column missing around the perimeter. the edges said "not today" 💀

---

🧠 NOTES (read these, fr fr) 👑

this whole calculation is heavily dependent on data resolution. think of it as the fractal shoreline problem: the more resolution, the more detail, the more area. more is more, periodt. 💅

important: this module uses the current region settings, not the resolution of the raster map. this matters so much for surfaces with NULL values and highly irregular edges. and ngl, the module does not [currently] try to correct for the error this edge effect introduces. she's aware, she's just not fixing it rn 🙈

also this version actually calculates area twice for each triangle pair, keeping a running minimum and maximum area depending on which direction the diagonal goes. two for one, ate. ✨

the reported totals are:

1. "Plan" area of NULL values within the current GRASS region
2. "Plan" area within calculation region (rows-1 * cols-1 * cellarea)
3. Average of the minimum and maximum calculated 3d triangle area within this region
4. "Plan" area within current computational region (rows * cols * cellarea)
5. Scaling of calculated area to current region

so when does r.surf.area truly thrive?? when the surface being evaluated extends all the way to the edges of the current region and the cell resolution is small. 🌸

conversely, surfaces that are especially long and thin and have highly irregular boundaries? yeah, those tend to get underestimated surface areas. the fix: set a high cell resolution (small area) and it'll greatly reduce this impact... but it will also cause longer processing times. no cap, that's the tradeoff 🫠

---

🧪 EXAMPLES 🎀

g.region -p raster=elevation
r.surf.area map=elevation units=hectares
Null value area ignored in calculation: 0.000000
Plan area used in calculation: 20221.510000
Surface area calculation(low, high, avg):
        20294.310421 20320.936368 20307.623395
Current region plan area: 20250.000000
Estimated region Surface Area: 20336.234719

look at those numbers go, she's working 💖

---

👀 SEE ALSO 🌈

g.region, r.surf.idw, r.surf.fractal, r.surf.gauss, r.volume, r.slope.aspect, v.to.rast

(the whole friend group, honestly 🫶)

---

🖊️ AUTHOR 💜

Bill Brown, USACERL December 21, 1994

Modified for floating point rasters and NULL values by Eric G. Miller (October 17, 2000)

Updated for GRASS 7, and units option by Martin Landa, Czech Technical University in Prague, Czech Republic (October 2011)

legends, all three of them 👑

---

📦 SOURCE CODE 🍓

Available at: r.surf.area source code (history)

Latest change: Friday Feb 07 19:16:09 2025 in commit: a82a39f673b97fafcfce1604dc3e6015cb96487a

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

---

and that's a wrap, bestie!! 🎀✨ this whole thing lives in the GRASS 8.5.0 Reference Manual, © 2003-2026 GRASS Development Team, and yes the manpage itself is stamped GRASS 8.5.0 down at the bottom like a lil signature. go measure some surfaces, you're gonna slay 💅💖