r.volume(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

💧 r.volume — the GRASS GIS User's Manual, but make it cute ✨

okay bestie, buckle up, because r.volume is genuinely one of those tools that sounds boring and then absolutely eats 💅

✨ NAME ✨

r.volume — Calculates the volume of data "clumps". Optionally produces a GRASS vector points map containing the calculated centroids of these clumps. 🫶

🌸 KEYWORDS 🌸

raster, volume, clumps

🎀 SYNOPSIS 🎀

r.volume
r.volume --help
r.volume [-f] input=name  [clump=name]   [centroids=name]
[output=name]   [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

🦋 Flags:

  • -f — Generate unformatted report (items separated by colon)
  • --overwrite — Allow output files to overwrite existing files
  • --help — Print usage summary
  • --verbose — Verbose module output
  • --quiet — Quiet module output
  • --ui — Force launching GUI dialog

🍓 Parameters:

  • input=name [required] — Name of input raster map representing data that will be summed within clumps
  • clump=name — Name of input clump raster map. Preferably the output of r.clump. If no clump map is given than MASK is used.
  • centroids=name — Name for output vector points map to contain clump centroids
  • output=name — Name for output file to hold the report. If no output file given report is printed to standard output

💖 DESCRIPTION 💖

r.volume is a tool for summing cell values within clumps and calculating volumes and centroids of patches or clumps. no cap, that's literally the whole job and it does it beautifully 😌

r.volume generates a table containing the sum of all cells from a input raster map sorted by category on a clump raster map, and optionally generates a vector points map of the centroids for each clump. If a clump map is not specified, the current MASK is used. The MASK can be defined by r.mask. The sum is multiplied by the area of a cell to give the volume occupied by that cell. See below for an example of the output table. 👑

🧚 NOTES 🧚

If a clump map is not given and a MASK not set, the program exits with an error message. 💀 like, it's not gonna guess for you, bestie.

r.volume works in the current region and respects the current MASK.

🌈 CENTROIDS 🌈

The centroid coordinates are the same as those stored in the vector map (if one was requested by centroids parameter). They are guaranteed to fall on a cell of the appropriate category, thus they are not always the true, mathematical centroid. They will always fall at a cell center. (lowkey a glow-up, highkey a compromise, iykyk)

Attribute table linked to the vector map with centroids contains several columns:

  • cat - category value (integer)
  • volume - volume value (double precision)
  • average - average value in the clump (double precision)
  • sum - sum of cell values in the clump (double precision)
  • count - number of cells with the category (integer)

Vector points can be converted directly to a raster map with each point a separate category using v.to.rast. ✨

🌸 APPLICATIONS 🌸

By preprocessing the elevation raster map with r.mapcalc and using suitable masking or clump maps, very interesting applications can be done with r.volume. Such as, calculating the volume of rock in a potential quarry; calculating cut/fill volumes for roads; finding water volumes in potential reservoirs. 🏞️ literally main character energy for civil engineering

💅 EXAMPLE 💅

💜 Computation of a water basin volume

The example is based on the North Carolina sample dataset:

# set computational region to small basin within extent of LiDAR elevation model
g.region n=220361 s=220123 w=638527 e=638894 align=elev_lid792_1m -p
# generate shared relief map for better terrain visualization
r.relief input=elev_lid792_1m output=elev_lid792_1m_shaded
d.shade shade=elev_lid792_1m_shaded color=elev_lid792_1m
# query terrain height at a position within the basin
r.what map=elev_lid792_1m coordinates=638684.0,220210.0
# 638684.0|220210.0||112.2362
# fill the basin with water, approx 1.5m above terrain
r.lake elevation=elev_lid792_1m water_level=113.7 lake=mylake coordinates=638684.0,220210.0
#  Lake depth from 0.000000 to 1.622047 (specified water level is taken as zero)
#  Lake area 764.000000 square meters
#  Lake volume 648.875328 cubic meters
# compute water volume
r.volume input=elev_lid792_1m clump=mylake
#
# Category   Average   Data   # Cells        Centroid             Total
# Number     in clump  Total  in clump   Easting     Northing     Volume
# -----------------------------------------------------------------------------
#        1    112.66     54188     481   638683.50   220210.50         54188.35
#        2    112.14      6504      58   638679.50   220215.50          6504.14
# -----------------------------------------------------------------------------
#                                                 Total Volume =       60692.49
Figure: Water filled based shown on shaded elevation map

🦋 Report of geological data

The following report was generated by the command (North Carolina sample dataset):

# set computational region
g.region raster=elevation -p
# compute volume
r.volume input=elevation clump=geology_30m
#
# Volume report on data from <elevation> using clumps on <geology_30m> raster map
#
# Category   Average   Data   # Cells        Centroid             Total
# Number     in clump  Total  in clump   Easting     Northing     Volume
# -----------------------------------------------------------------------------
#      217    118.93  86288828  725562   635325.00   221535.00    8628882798.63
#      262    108.97  21650560  198684   638935.00   222495.00    2165056037.02
#      270     92.23  63578874  689373   642405.00   221485.00    6357887443.53
#      405    132.96  33732662  253710   631835.00   224095.00    3373266208.59
#      583    139.35   3011288   21609   630205.00   224665.00     301128821.55
#      720    124.30    599618    4824   634075.00   227995.00      59961816.06
#      766    132.43    936791    7074   631425.00   227845.00      93679120.08
#      862    118.31   7302317   61722   630505.00   218885.00     730231746.74
#      910     94.20   4235816   44964   639215.00   216365.00     423581613.11
#      921    135.22   1693985   12528   630755.00   215445.00     169398523.05
#      945    127.24      1145       9   630015.00   215015.00        114512.03
#      946     89.91    365748    4068   639085.00   215255.00      36574833.85
#      948    129.02    112632     873   630185.00   215115.00      11263181.57
# -----------------------------------------------------------------------------
#                                                 Total Volume = 22351026655.81

The Data Total column is the sum of the elevations for each in each of the fields. The Total Volume is the sum multiplied by the east-west resolution times the north-south resolution. Note that the units on the volume may be difficult if the units of cell values on the input raster map and the resolution units differ. 🙈 (yes bestie, units are the villain of every story)

👑 SEE ALSO 👑

r.clump, r.mask, r.mapcalc

🫶 AUTHORS 🫶

Dr. James Hinthorne, Central Washington University GIS Laboratory, December 1988.

Updated to GRASS 7 by Martin Landa, Czech Technical University in Prague, Czech Republic

💖 SOURCE CODE 💖

Available at: r.volume source code (history)

Accessed: Saturday Jan 17 05:41:05 2026

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

© 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual

okay and that's the whole page!! 🎀 brought to you by GRASS 8.4.2, dated Saturday Jan 17 05:41:05 2026, straight from the GRASS GIS 8.4.2 Reference Manual, © 2003-2025 GRASS Development Team. go forth and compute some volumes, bestie 💅✨

📦 where this page comes from