Geografic-Information-System/raster/r.volume/r.volume.html

<h2>DESCRIPTION</h2>

<em>r.volume</em> is a tool for summing cell values within clumps and
calculating volumes and centroids of patches or clumps.

<p>
<em>r.volume</em> generates a table containing the sum of all cells
from a <b>input</b> raster map sorted by category on a <b>clump</b>
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 <em><a href="r.mask.html">r.mask</a></em>. 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.

<!-- The table is placed in the user's home directory in the file
Gvol.report. (or not???)

NOTE: I can't find any evidence of this in the source code, and I have
tested the module out as of Jan 10, 2008. I'll leave the above comment
about automatic report generation commented out from the manpage for
now, unless I get notification otherwise. - EP -->

<h2>NOTES</h2>

<p>
If a clump map is not given and a MASK not set, the program exits with
an error message.

<p>
<em>r.volume</em> works in the current region and respects the current
MASK.

<h3>CENTROIDS</h3>

The centroid coordinates are the same as those stored in the vector
map (if one was requested by <b>centroids</b> 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.

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

<ul>
  <li><tt>cat</tt> - category value (integer)</li>
  <li><tt>volume</tt> - volume value (double precision)</li>
  <li><tt>average</tt> - average value in the clump (double precision)</li>
  <li><tt>sum</tt> - sum of cell values in the clump (double precision)</li>
  <li><tt>count</tt> - number of cells with the category (integer)</li>
</ul>

<p>
Vector points can be converted directly to a raster map with each
point a separate category
using <em><a href="v.to.rast.html">v.to.rast</a></em>.

<h3>APPLICATIONS</h3>

By preprocessing the elevation raster map
with <em><a href="r.mapcalc.html">r.mapcalc</a></em> and using
suitable masking or clump maps, very interesting applications can be
done with <em>r.volume</em>.  Such as, calculating the volume of rock
in a potential quarry; calculating cut/fill volumes for roads; finding
water volumes in potential reservoirs. 

<h2>EXAMPLE</h2>

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

<div class="code"><pre>
# set computational region
g.region raster=elevation

# compute volume
r.volume input=elevation clump=geology_30m

Volume report on data from &lt;elevation&gt; using clumps on &lt;geology_30m&gt; 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
</pre></div>

The <tt>Data Total</tt> column is the sum of the elevations for each
in each of the fields.  The <tt>Total Volume</tt> 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 <b>input</b> raster map and the resolution
units differ.

<h2>SEE ALSO</h2>

<em>
  <a href="r.clump.html">r.clump</a>,
  <a href="r.mask.html">r.mask</a>,
  <a href="r.mapcalc.html">r.mapcalc</a>
</em>

<h2>AUTHORS</h2>

Dr. James Hinthorne, Central Washington University GIS Laboratory,
December 1988.<br>
Updated to GRASS 7 by Martin Landa, Czech Technical University in Prague, Czech Republic

<p>
<i>Last changed: $Date$</i>