<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>GRASS GIS: r.volume</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="grassdocs.css" type="text/css">
</head>
<body bgcolor="white">
<img src="grass_logo.png" alt="GRASS logo"><hr align=center size=6 noshade>
<h2>NAME</h2>
<em><b>r.volume</b></em> - Calculates the volume of data "clumps", and (optionally) produces a GRASS vector points map containing the calculated centroids of these clumps.
<h2>KEYWORDS</h2>
raster
<h2>SYNOPSIS</h2>
<b>r.volume</b><br>
<b>r.volume help</b><br>
<b>r.volume</b> [-<b>f</b>] <b>data</b>=<em>string</em> [<b>clump</b>=<em>string</em>] [<b>centroids</b>=<em>string</em>] [--<b>overwrite</b>] [--<b>verbose</b>] [--<b>quiet</b>]
<h3>Flags:</h3>
<DL>
<DT><b>-f</b></DT>
<DD>Generate unformatted report</DD>
<DT><b>--overwrite</b></DT>
<DD>Allow output files to overwrite existing files</DD>
<DT><b>--verbose</b></DT>
<DD>Verbose module output</DD>
<DT><b>--quiet</b></DT>
<DD>Quiet module output</DD>
</DL>
<h3>Parameters:</h3>
<DL>
<DT><b>data</b>=<em>string</em></DT>
<DD>Existing raster map representing data that will be summed within clumps</DD>
<DT><b>clump</b>=<em>string</em></DT>
<DD>Existing raster map, preferably the output of r.clump</DD>
<DT><b>centroids</b>=<em>string</em></DT>
<DD>Vector points map to contain clump centroids</DD>
</DL>
<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 data_map layer sorted by category on a clump 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 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.
<p>
<H2>EXAMPLE</H2>
The following report was generated by the command:
(spearfish data base; fields.only is the fields layer without the
National Forest category)
<p>
r.volume data=elevation clump=fields.only centroids=field.centers
<p>
<pre><tt>
Volume report on data from elevation using clumps on fields.only map
Cat Average Data # Cells Centroid Total
Number in clump Total in clump Easting Northing Volume
1 1181.09 75590 64 595500.00 4927700.00 755900000.00
2 1163.50 69810 60 597100.00 4927700.00 698100000.00
3 1146.83 34405 30 598300.00 4927700.00 344050000.00
4 1193.20 366311 307 599400.00 4927300.00 3663110000.00
.....
.....
.....
60 1260.08 351563 279 603100.00 4921000.00 3515630000.00
61 1213.93 35204 29 603700.00 4921500.00 352040000.00
62 1207.71 33816 28 604100.00 4921500.00 338160000.00
Total Volume = 67226740000.00
</tt></pre>
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 e-w resolution times the n-s resolution. Note that
the units on the volume may be difficult if the units of cell
values on the data_map layer and the resolution units differ.
<p>
<h3>CENTROIDS</h3>
The centroid coordinates are the same as those stored in the sites
file (if one was requested). 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.
<h3>FORMAT OF CENTROIDS table<BR></h3>
For each line of above table the vector points table contains
these columns:
<tt>
easting,
northing,
cat,
volume,
average,
sum,
count
</tt>
<p>
This can be converted directly to a raster map with each point
a separate category using <em>v.to.rast</em>.
<p>
<!-- As far as I can tell, no attributes are written to a table in Grass 6.3
(Jan 2008), as this program hasn't been updated to use the Grass 6 vector library. - EP
-->
<h3>APPLICATIONS</h3>
By preprocessing the elevation layer with <em>r.mapcalc</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. Data layers of
other measures of real values.
<H2>AUTHOR</H2>
Dr. James Hinthorne, Central Washington University GIS Laboratory<BR>
December 1988.
<HR>
<P><a href="index.html">Main index</a> - <a href="raster.html">raster index</a> - <a href="full_index.html">Full index</a></P>
<P>© 2003-2008 <a href="http://grass.osgeo.org">GRASS Development Team</a></p>
</body>
</html>
