NAME

       r.volume   -  Calculates  the  volume  of data "clumps", and (optionally) produces a GRASS
       vector points map containing the calculated centroids of these clumps.

KEYWORDS

       raster, volume

SYNOPSIS

       r.volume
       r.volume help
       r.volume   [-f]   data=string    [clump=string]      [centroids=string]      [--overwrite]
       [--verbose]  [--quiet]

   Flags:
       -f
           Generate unformatted report

       --overwrite
           Allow output files to overwrite existing files

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       data=string
           Existing raster map representing data that will be summed within clumps

       clump=string
           Existing raster map, preferably the output of r.clump

       centroids=string
           Vector points map to contain clump centroids

DESCRIPTION

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

       r.volume 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.

NOTES

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

       r.volume works in the current region and respects the current MASK.

EXAMPLE

       The following report was generated by the command: (spearfish data  base;  fields.only  is
       the fields layer without the National Forest category)

       r.volume data=elevation clump=fields.only centroids=field.centers

       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
         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.

   CENTROIDS
       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.

   FORMAT OF CENTROIDS table
       For each line of above table the vector points  table  contains  these  columns:  easting,
       northing, cat, volume, average, sum, count

       This  can  be converted directly to a raster map with each point a separate category using
       v.to.rast.

   APPLICATIONS
       By preprocessing the elevation layer with r.mapcalc and using suitable  masking  or  clump
       maps,  very  interesting applications can be done with r.volume.  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.

AUTHOR

       Dr. James Hinthorne, Central Washington University GIS Laboratory
       December 1988.

       Full index

       © 2003-2013 GRASS Development Team