NAME
r.volume - Calculates the volume of data "clumps",
and (optionally) produces a GRASS site_lists file
containing the calculated centroids of these clumps.
(GRASS Raster Program)
SYNOPSIS
r.volume
r.volume help
r.volume
[-fq]
data=name
[clump=name]
[site_list=name]
DESCRIPTION
This program computes the cubic volume of data contained
in user-defined clumps.
r.volume outputs:
- The category value assigned to each clump formed by
the clump map layer.
This value is stored under the "Cat Number" column (field 1)
in the output table.
- The average category value of the cells found in a data
map that fall within the boundaries of each clump in a clump map.
The table stores this value under the "Average in Clump" column (field 2).
- The summed total value of the category values assigned to the cells
falling within each of these clumps.
This value is output under the "Data Total" column (field 3).
- The number of cells from the data map that fall
within the boundaries of each clump formed by the clump map layer.
This cell count is stored under the "# Cells in Clump" column (field 4) in the
output table.
- The centroid easting of each clump.
- The centroid northing of each clump. These values are output
under the "Centroid Easting" and "Centroid Northing" columns (fields 5 and 6)
in the output.
- The total "volume" of each clump. For each clump, the volume is calculated
by multiplying the area of each cell by its category value, and
taking the sum of this value for all cells within the clump. Since,
in GRASS, each cell in the data map
will have the same cell dimensions (i.e., the same area), this is equivalent to
multiplying the area of one cell by the "Data Total" column (field 3).
(The area of each cell is equal to the product of its east-west resolution
by its north-south resolution. See
g.region.)
Results are sent to standard output in the form of a
table. If the user sets the -f flag, this table
will be output in a form suitable for input to such UNIX
programs as awk and sed; the table's
columns are stored as colon-separated fields. The user can
also (optionally) elect to store clump centroids in a GRASS
site_lists file. A sample output report is shown
below.
r.volume
works with the current geographic region definitions
and respects the current MASK.
The user can run r.volume non-interactively by
specifying parameter values
on the command line. If the user omits parameter
values from the command line,
the program will prompt the user for input using the standard
interface described
in the manual entry for
parser.
OPTIONS
Flags:
- -f
- Generate unformatted output.
Output is in a form suitable for input to UNIX programs like awk;
each column in the output is separated by a colon. Results are sent to
standard output.
- -q
- Run quietly, suppressing the printing of debugging messages to standard
output.
Parameters:
- data=name
- Name of an existing raster map layer containing the category
values to be summed. The cell resolution (area) of the data
map will also be used.
- clump=name
- Name of an existing raster map layer that defines the boundaries
of each clump. Preferably, this map should be the output of
r.clump.
If the user has imposed a mask, the program uses this mask as the
clump map layer if no other clump layer is
specified by the user.
- site_list=name
- The name to be assigned to a new GRASS site_list file,
in which clump centroids can be stored.
EXAMPLE OF REPORT
The following report might be generated by the command:
-
r.volume d=elevation
c=fields.only s=field.centers
Cat Average Data # Cells Centroid Total
# in clump Total in clump Easting Northing Volume
1 1181.09 75590 64 595500.0 4927700.0 755900000.0
2 1163.50 69810 60 597100.0 4927700.0 698100000.0
3 1146.83 34405 30 598300.0 4927700.0 344050000.0
4 1193.20 366311 307 599400.0 4927300.0 3663110000.0
.....
.....
60 1260.08 351563 279 603100.0 4921000.0 3515630000.0
61 1213.93 35204 29 603700.0 4921500.0 352040000.0
62 1207.71 33816 28 604100.0 4921500.0 338160000.0
Total Volume = 67226740000.0
For ease of example, it is assumed that each clump in the
fields.only map layer is a field, that cell category
values in the elevation map layer represent
actual elevation values in meters, and that the data base
is a UTM data base (in meters).
This means that field #1 (clump #1) contains 64 cells;
the average elevation in field #1 is 1181.09 meters. The
sum of all of the elevation values assigned to cells
within field #1 is 75590 meters. The volume (x*y*z) of
space in field #1 is equal to 755900000 cubic meters.
The "Data Total" column is the sum of the cell category values appearing in the
elevation map layer, within each field of the fields.only map layer.
The Total Volume is the sum multiplied
by the e-w resolution times the n-s resolution.
CENTROIDS
The coordinates of the clump centroids are the same as those stored
in the GRASS site_lists 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 centroids. However, they will always fall at a cell center.
FORMAT OF SITE LIST
For each line of above table the GRASS site_lists file reads:
-
easting|northing|#cat v=volume a=average t=sum n=count
This can be converted directly to a raster map layer in which each point
is assigned to a separate category.
APPLICATIONS
By preprocessing the elevation map layer with
r.mapcalc
and using suitable masking or clump maps, very interesting
applications can be done with r.volume.
For instance, one can calculate: the volume
of rock in a potential quarry; cut/fill volumes for roads; and,
water volumes in potential reservoirs.
Data layers of other measures of real values can also be used.
NOTES
The output is sent to the terminal screen. The user can capture
the output in a file using the UNIX redirection mechanism, as in the
following example:
-
r.volume
d=data_map
c=clump_map
s=site_list > table.out
Output can also be sent directly to the printer, as shown below:
-
r.volume
d=data_map
c=clump_map
s=site_list | lpr
The user should be aware of what units of measurement
the cell e-w and n-s resolution are in,
and in what units the data map's cell category values are stated
(since these three values will be multiplied together to produce the volume).
This program respects the current mask, and uses this mask as the
clump map layer if none is specified by the user.
SEE ALSO
g.region
r.clump
r.mapcalc
r.mask
s.db.rim
s.menu
parser
AUTHOR
Dr. James Hinthorne,
GIS Laboratory,
Central Washington University