r3.stats(1grass)

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

✨ r3.stats ✨

okay bestie, gather round, because we're talking about r3.stats from the GRASS User's Manual and it is literally the volume-stats girlie of the 3D raster world 🎀

🌸 NAME 🌸

r3.stats — she generates volume statistics for 3D raster maps. that's it, that's the job, and she slays it 💅

🦋 KEYWORDS 🦋

raster3d, statistics, voxel, volume — the four horsemen of your 3D-analysis era ✨

💖 SYNOPSIS 💖

r3.stats
r3.stats --help
r3.stats [-ec] input=name  [nsteps=integer]   [--help]  [--verbose]
[--quiet]  [--ui]

🎀 Flags

  • -e — calculate statistics based on equal value groups. (grouping vibes only, no ranges here)
  • -c — only print cell counts. minimalism, we love her
  • --help — print usage summary. your little cheat sheet 🫶
  • --verbose — verbose module output. she will talk
  • --quiet — quiet module output. she will not talk
  • --ui — force launching GUI dialog. pop-up time ✨

🍓 Parameters

  • input=name [required] — name of input 3D raster map. the main character we're analyzing, no cap
  • nsteps=integer — number of subranges to collect stats from. Default: 20

🌈 DESCRIPTION 🌈

so r3.stats calculates volume statistics for 3D raster maps. the volumes get created on the basis of value subranges or groups of equal values. the default number of subranges is 20, and honestly it can vary from 1 to infinite (infinite!! go off queen). a bigger number of subranges means bigger memory consumption — that's just the trade-off, bestie, it's giving "you can't sit with us unless you bring RAM".

the volumes are calculated in qubic meters (yes that's the spelling in the original, i don't make the rules 💀). Null values are marked with *. and if the flag -e is set, the number of subranges will be ignored — periodt.

💅 NOTES 💅

as with most GRASS 3D raster map modules, r3.stats operates on the cell array defined by the current 3D region settings, not the original extent and resolution of the input map. see g.region for that. region check first, always 🫶

the region setting will not effect the memory consumption of this module. (their word, not mine!) it's the number of subranges in case of value range calculation, or the number of equal value groups, that effects the memory consumption and the calculation time.

⚠️ okay so listen: the user can expect a huge time consumption to calculate the equal value groups (flag -e) if large region settings occur for maps which have many equal value groups (> 100000). that's not a vibe check, that's a warning check. go make a snack, she's gonna be a while 😭

👑 EXAMPLES 👑

🧚 Lausanne FOSS4G 2006 3D demo dataset example

the 3D raster map geology has three values. each value represents a specific geological layer: clay = 1, sand = 2, and bedrock = 3. to calculate the volume of each geological layer, we can use the flag -e to group equal values into single volumes. r3.stats geology -e will produce the following output:

  num   |        value       |     volume    |   perc  |    count
      1             1.000000   300822000.000   50.13700        50137
      2             2.000000   101400000.000   16.90000        16900
      3             3.000000   197778000.000   32.96300        32963
      4                    *           0.000   0.00000            0
Number of groups with equal values: 3
Sum of non Null cells:
        Volume = 600000000.000
        Percentage = 100.000
        Count = 100000
Sum of all cells:
        Volume = 600000000.000
        Percentage = 100.000
        Count = 100000

💜 Generic example

#create a small 3D region
g.region n=1000 s=0 e=2000 w=0 t=300 b=0 res3=100
#create a raster3D map with row() and null values
r3.mapcalc "volmap = if(row() == 5, null(), row())"
#run r3.stats with a subrange of 10
r3.stats input=volmap nsteps=10
#the result should look like this
 num   | minimum <= value   | value < maximum    |     volume    |   perc  | cell count
      1          1.000000000          1.900000000    60000000.000   10.00000           60
      2          1.900000000          2.800000000    60000000.000   10.00000           60
      3          2.800000000          3.700000000    60000000.000   10.00000           60
      4          3.700000000          4.600000000    60000000.000   10.00000           60
      5          4.600000000          5.500000000           0.000   0.00000            0
      6          5.500000000          6.400000000    60000000.000   10.00000           60
      7          6.400000000          7.300000000    60000000.000   10.00000           60
      8          7.300000000          8.200000000    60000000.000   10.00000           60
      9          8.200000000          9.100000000    60000000.000   10.00000           60
     10          9.100000000         10.000000001    60000000.000   10.00000           60
     11                    *                    *    60000000.000   10.00000           60
Sum of non Null cells:
        Volume = 540000000.000
        Percentage =  90.000
        Cell count = 540
Sum of all cells:
        Volume = 600000000.000
        Percentage = 100.000
        Cell count = 600

🔥 SEE ALSO 🔥

g.region, r3.univar, r.stats, r.statistics, v.univar

(the whole friend group, fr fr 🫶)

⭐ AUTHOR ⭐

Sören Gebbert — legend behaviour, we stan 💖

🌟 SOURCE CODE 🌟

available at: r3.stats source code (history)

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

main index | 3D raster index | Topics index | Keywords index | Graphical index | Full index

and that's the whole page, bestie!! no notes, she ate, she left no crumbs 👑

© 2003-2026 GRASS Development Team — GRASS 8.5.0 Reference Manual 💜 this was GRASS 8.5.0's r3.stats(1grass), signing off with main character energy ✨🦋🎀

📦 where this page comes from