1r.volume(1) GRASS GIS User's Manual r.volume(1)
2
6 r.volume - Calculates the volume of data "clumps".
7 Optionally produces a GRASS vector points map containing the calculated
8 centroids of these clumps.
9
11 raster, volume, clumps
12
14 r.volume
15 r.volume --help
16 r.volume [-f] input=name [clump=name] [centroids=name] [out‐
17 put=name] [--overwrite] [--help] [--verbose] [--quiet] [--ui]
18 Flags:
20 -f
21 Generate unformatted report (items separated by colon)
22 --overwrite
24 Allow output files to overwrite existing files
25 --help
27 Print usage summary
28 --verbose
30 Verbose module output
31 --quiet
33 Quiet module output
34 --ui
36 Force launching GUI dialog
37 Parameters:
39 input=name [required]
40 Name of input raster map representing data that will be summed
41 within clumps
42 clump=name
44 Name of input clump raster map
45 Preferably the output of r.clump. If no clump map is given than
46 MASK is used.
47 centroids=name
49 Name for output vector points map to contain clump centroids
50 output=name
52 Name for output file to hold the report
53 If no output file given report is printed to standard output
54
56 r.volume is a tool for summing cell values within clumps and calculat‐
57 ing volumes and centroids of patches or clumps.
58 r.volume generates a table containing the sum of all cells from a input
60 raster map sorted by category on a clump raster map, and optionally
61 generates a vector points map of the centroids for each clump. If a
62 clump map is not specified, the current MASK is used. The MASK can be
63 defined by r.mask. The sum is multiplied by the area of a cell to give
64 the volume occupied by that cell. See below for an example of the out‐
65 put table.
66
68 If a clump map is not given and a MASK not set, the program exits with
69 an error message.
70 r.volume works in the current region and respects the current MASK.
72 CENTROIDS
74 The centroid coordinates are the same as those stored in the vector map
75 (if one was requested by centroids parameter). They are guaranteed to
76 fall on a cell of the appropriate category, thus they are not always
77 the true, mathematical centroid. They will always fall at a cell cen‐
78 ter.
79 Attribute table linked to the vector map with centroids contains sev‐
81 eral columns:
82 · cat - category value (integer)
84 · volume - volume value (double precision)
86 · average - average value in the clump (double precision)
88 · sum - sum of cell values in the clump (double precision)
90 · count - number of cells with the category (integer)
92 Vector points can be converted directly to a raster map with each point
94 a separate category using v.to.rast.
95 APPLICATIONS
97 By preprocessing the elevation raster map with r.mapcalc and using
98 suitable masking or clump maps, very interesting applications can be
99 done with r.volume. Such as, calculating the volume of rock in a
100 potential quarry; calculating cut/fill volumes for roads; finding water
101 volumes in potential reservoirs.
102
104 Computation of a water basin volume
105 The example is based on the North Carolina sample dataset:
106 # set computational region to small basin within extent of LiDAR elevation model
107 g.region n=220361 s=220123 w=638527 e=638894 align=elev_lid792_1m -p
108 # generate shared relief map for better terrain visualization
109 r.relief input=elev_lid792_1m output=elev_lid792_1m_shaded
110 d.shade shade=elev_lid792_1m_shaded color=elev_lid792_1m
111 # query terrain height at a position within the basin
112 r.what map=elev_lid792_1m coordinates=638684.0,220210.0
113 # 638684.0|220210.0||112.2362
114 # fill the basin with water, approx 1.5m above terrain
115 r.lake elevation=elev_lid792_1m water_level=113.7 lake=mylake coordinates=638684.0,220210.0
116 # Lake depth from 0.000000 to 1.622047 (specified water level is taken as zero)
117 # Lake area 764.000000 square meters
118 # Lake volume 648.875328 cubic meters
119 # compute water volume
120 r.volume input=elev_lid792_1m clump=mylake
121 #
122 # Category Average Data # Cells Centroid Total
123 # Number in clump Total in clump Easting Northing Volume
124 # -----------------------------------------------------------------------------
125 # 1 112.66 54188 481 638683.50 220210.50 54188.35
126 # 2 112.14 6504 58 638679.50 220215.50 6504.14
127 # -----------------------------------------------------------------------------
128 # Total Volume = 60692.49
129 Figure: Water filled based shown on shaded elevation map
130 Report of geological data
132 The following report was generated by the command (North Carolina sam‐
133 ple dataset):
134 # set computational region
135 g.region raster=elevation -p
136 # compute volume
137 r.volume input=elevation clump=geology_30m
138 #
139 # Volume report on data from <elevation> using clumps on <geology_30m> raster map
140 #
141 # Category Average Data # Cells Centroid Total
142 # Number in clump Total in clump Easting Northing Volume
143 # -----------------------------------------------------------------------------
144 # 217 118.93 86288828 725562 635325.00 221535.00 8628882798.63
145 # 262 108.97 21650560 198684 638935.00 222495.00 2165056037.02
146 # 270 92.23 63578874 689373 642405.00 221485.00 6357887443.53
147 # 405 132.96 33732662 253710 631835.00 224095.00 3373266208.59
148 # 583 139.35 3011288 21609 630205.00 224665.00 301128821.55
149 # 720 124.30 599618 4824 634075.00 227995.00 59961816.06
150 # 766 132.43 936791 7074 631425.00 227845.00 93679120.08
151 # 862 118.31 7302317 61722 630505.00 218885.00 730231746.74
152 # 910 94.20 4235816 44964 639215.00 216365.00 423581613.11
153 # 921 135.22 1693985 12528 630755.00 215445.00 169398523.05
154 # 945 127.24 1145 9 630015.00 215015.00 114512.03
155 # 946 89.91 365748 4068 639085.00 215255.00 36574833.85
156 # 948 129.02 112632 873 630185.00 215115.00 11263181.57
157 # -----------------------------------------------------------------------------
158 # Total Volume = 22351026655.81
159 The Data Total column is the sum of the elevations for each in each of
160 the fields. The Total Volume is the sum multiplied by the east-west
161 resolution times the north-south resolution. Note that the units on the
162 volume may be difficult if the units of cell values on the input raster
163 map and the resolution units differ.
164
166 r.clump, r.mask, r.mapcalc
167
169 Dr. James Hinthorne, Central Washington University GIS Laboratory,
170 December 1988.
171 Updated to GRASS 7 by Martin Landa, Czech Technical University in
172 Prague, Czech Republic
173
175 Available at: r.volume source code (history)
176 Main index | Raster index | Topics index | Keywords index | Graphical
178 index | Full index
179 © 2003-2020 GRASS Development Team, GRASS GIS 7.8.5 Reference Manual
181GRASS 7.8.5 r.volume(1)