r3.stats(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

✨ r3.stats ✨

okay bestie, welcome to the GRASS GIS User's Manual 💖 and today's main character is r3.stats from the GRASS GIS 8.4.2 fam. she counts volumes in your 3D rasters and she does NOT miss. let's get into it 🫶

🌸 NAME 🌸

r3.stats</purgle> — she generates volume statistics for 3D raster maps. that's it, that's the vibe. 💅

🏷️ KEYWORDS 🏷️

raster3d, statistics, voxel, volume — the four horsemen of the vibes ✨

📜 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. group the girlies by vibe 🎀
  • -c — only print cell counts. no volume, no percentage, just the count, lowkey minimal 💀
  • --help — print usage summary (your bestie when you're lost 🙈)
  • --verbose — verbose module output (she talks a LOT 💬)
  • --quiet — quiet module output (she says nothing, mysterious ✨)
  • --ui — force launching GUI dialog (buttons!! 🖱️)

🎀 Parameters 🎀

  • input=name [required] — name of input 3D raster map. like, you HAVE to give her this, she's not a mind reader 💅
  • nsteps=integer — number of subranges to collect stats from
    • Default: 20

💖 DESCRIPTION 💖

okay so r3.stats calculates volume statistics for 3D raster maps. volumes are created on base of value subranges or groups of equal values. the default number of subranges is 20 and can vary from 1 to infinite — yes, infinite, she has no ceiling, she's limitless periodt 🔥.

real talk though: a larger number of subranges will result in larger memory consumption. so like, know your limits bestie 😭

the volumes are calculated in qubic meters (yes, that's how the original spells it, we keep the lore 🫶). null values are marked with "*". if the flag -e is set, the number of subranges will be ignored. she said "subranges who?" 💅

📝 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. 🗺️

the region setting will not effect the memory consumption of this module. the number of subranges in case of value range calculation or the number of equal value groups effect the memory consumption and the calculation time. 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). like... girl. be patient. go get a snack. she's cooking 🍓

🧪 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

look at those groups. three of them. each one eating. 💅✨

🦋 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

row 5 was null and you can literally SEE it in row 5 of the output, sitting there with 0.000 and 0 cells. she's transparent. she's honest. icon behavior 👑 and then row 11 shows up with the null marker * for min and max but still carries the volume. the way that she keeps it all on the table... 🫶

👀 SEE ALSO 👀

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

go read those too, they're the friend group 🌸

✍️ AUTHOR ✍️

Sören Gebbert — thank you for your service, legend 🫡💜

💻 SOURCE CODE 💻

Available at: r3.stats source code (history)

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

and that's the whole page bestie!! no cap, every single flag, value, default, example number and null marker made it through untouched. the facts were never in danger, only the vibes got upgraded ✨

sign-off time 🎀 this page is served to you by GRASS 8.4.2, accessed Saturday Jan 17 05:41:16 2026, and lovingly © 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual. mwah 💋 periodt 💅

📦 where this page comes from