.TH r.volume .SH NAME \fIr.volume\fR \- Calculates the volume of data "clumps", and (optionally) produces a GRASS \fIsite_lists\fR file containing the calculated centroids of these clumps. .br .I "(GRASS Raster Program)" .SH SYNOPSIS \fBr.volume\fR .br \fBr.volume help\fR .br \fBr.volume\fR [\fB-fq\fR] \fBdata\*=\fIname\fR [\fBclump\*=\fIname\fR] \fB[site_list\*=\fIname\fR] .SH DESCRIPTION This program computes the cubic volume of data contained in user-defined clumps. \fIr.volume\fR outputs: .LP .RS (1) The category value assigned to each clump formed by the \fIclump\fR map layer. This value is stored under the "Cat Number" column (field 1) in the output table. .br (2) The average category value of the cells found in a \fIdata\fR map that fall within the boundaries of each clump in a \fIclump\fR map. The table stores this value under the "Average in Clump" column (field 2). .br (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). .br (4) The number of cells from the \fIdata\fR map that fall within the boundaries of each clump formed by the \fIclump\fR map layer. This cell count is stored under the "# Cells in Clump" column (field 4) in the output table. .br (5,6) The centroid (easting and northing) of each clump. These values are output under the "Centroid Easting" and "Centroid Northing" columns (fields 5 and 6) in the output. .br (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 \fIdata\fR 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). .br (The area of each cell is equal to the product of its east-west resolution by its north-south resolution. See \fIg.region\fR.) .LP 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 \fIawk\fR and \fIsed\fR; the table's columns are stored as colon-separated fields. The user can also (optionally) elect to store clump centroids in a GRASS \fIsite_lists\fR file. A sample output report is shown below. .LP .I r.volume works with the current geographic region definitions and respects the current MASK. .LP The user can run \fIr.volume\fR 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 \fIparser\fR. .SH "COMMAND LINE OPTIONS" .LP \fBFlags:\fR .IP \fB-f\fR 18 Generate unformatted output. Output is in a form suitable for input to UNIX programs like \fIawk\fR; each column in the output is separated by a colon. Results are sent to standard output. .IP \fB-q\fR 18 Run quietly, suppressing the printing of debugging messages to standard output. .LP \fBParameters:\fR .IP \fIdata\fR 18 Name of an existing raster map layer containing the category values to be summed. The cell resolution (area) of the \fIdata\fR map will also be used. .IP \fIclump\fR 18 Name of an existing raster map layer that defines the boundaries of each clump. Preferably, this map should be the output of \fIr.clump\fR. If the user has imposed a mask, the program uses this mask as the \fIclump\fR map layer if no other \fIclump\fR layer is specified by the user. .IP \fIsite_list\fR 18 The name to be assigned to a new GRASS \fIsite_lists\fR file, in which clump centroids can be stored. .SH EXAMPLE OF REPORT The following report might be generated by the command: .LP .RS \fBr.volume d\*=elevation c\*=fields.only s\*=field.centers \fR .RE .LP .NF 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 .FI For ease of example, it is assumed that each clump in the \fIfields.only\fR map layer is a field, that cell category values in the \fIelevation\fR 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. .LP The "Data Total" column is the sum of the cell category values appearing in the \fIelevation\fR map layer, within each field of the \fIfields.only\fR map layer. The Total Volume is the sum multiplied by the e-w resolution times the n-s resolution. .SH CENTROIDS The coordinates of the clump centroids are the same as those stored in the GRASS \fIsite_lists\fR 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. .SH FORMAT OF SITE LIST For each line of above table the GRASS \fIsite_lists\fR file reads: .LP .RS easting|northing|#cat v\*=volume a\*=average t\*=sum n\*=count .RE .LP This can be converted directly to a raster map layer in which each point is assigned to a separate category. .SH APPLICATIONS By preprocessing the \fIelevation\fR map layer with \fIr.mapcalc\fR and using suitable masking or clump maps, very interesting applications can be done with \fIr.volume\fR. 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. .SH 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: .LP .RS \fBr.volume d\*=data_map c\*=clump_map s\*=site_list > table.out \fR .RE .LP Output can also be sent directly to the printer, as shown below: .LP .RS \fBr.volume d\*=data_map c\*=clump_map s\*=site_list | lpr \fR .RE .LP 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 \fIdata\fR map's cell category values are stated (since these three values will be multiplied together to produce the volume). .LP This program respects the current mask, and uses this mask as the \fIclump\fR map layer if none is specified by the user. .SH SEE ALSO .I g.region, .I r.clump, .I r.mapcalc, .I r.mask, .I s.db.rim, .I s.menu and .I parser .SH AUTHOR Dr. James Hinthorne, Central Washington University GIS Laboratory