
NAME
	Gvolume - tool for summing cell values within clumps and calculating
		volumes and centroids of patches or clumps.

SYNOPSIS
	Gvolume d=data_map [c=clump_map] [s=site_list]

DESCRIPTION
	Gvolume 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 site list of the centroids for each clump.  If a
	clump_map layer name 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.

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

	Gvolume works in the current window and respects the current MASK.

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

	Gvolume d=elevation c=fields.only s=field.centers 

Gvolume 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 SITE LIST
	For each line of above table the site list reads:
	easting|northing|#cat v=volume a=average t=sum n=count

	This can be converted directly to a cell file with each point
	a separate category.

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

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



