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:
  1. 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.
  2. 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).
  3. 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).
  4. 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.
  5. The centroid easting of each clump.
  6. 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.
  7. 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

Last changed: $Date$