r.volume(1)		      Grass User's Manual		   r.volume(1)



NNAAMMEE
       rr..vvoolluummee   -  Calculates  the volume of data "clumps", and (optionally)
       produces a GRASS _s_i_t_e___l_i_s_t_s file containing the calculated centroids of
       these clumps.
       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..vvoolluummee
       rr..vvoolluummee hheellpp
       rr..vvoolluummee [--ffqq] ddaattaa==_n_a_m_e [cclluummpp==_n_a_m_e] [ssiittee__lliisstt==_n_a_m_e]

DDEESSCCRRIIPPTTIIOONN
       This  program  computes	the  cubic  volume  of data contained in user-
       defined clumps.	_r_._v_o_l_u_m_e outputs:

	      The category value assigned to each clump formed	by  the  _c_l_u_m_p
	      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 _d_a_t_a map that
	      fall  within  the  boundaries of each clump in a _c_l_u_m_p 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  _d_a_t_a map that fall within the
	      boundaries of each clump formed by the _c_l_u_m_p  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 _d_a_t_a 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_._r_e_g_i_o_n.)



       Results	are  sent  to  standard output in the form of a table.	If the
       user sets the --ff flag, this table will be output in a form suitable for
       input  to  such	UNIX  programs as _a_w_k and _s_e_d; the table's columns are
       stored as colon-separated fields.  The user can also (optionally) elect
       to  store  clump  centroids in a GRASS _s_i_t_e___l_i_s_t_s file. A sample output
       report is shown below.


       _r_._v_o_l_u_m_e works with  the  current  geographic  region  definitions  and
       respects the current MASK.


       The  user  can  run  _r_._v_o_l_u_m_e 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 _p_a_r_s_e_r.

OOPPTTIIOONNSS
   FFllaaggss::
       --ff     Generate unformatted output.  Output is in a form  suitable  for
	      input  to  UNIX  programs like _a_w_k; each column in the output is
	      separated by a colon. Results are sent to standard output.

       --qq     Run quietly, suppressing the printing of debugging  messages  to
	      standard output.


   PPaarraammeetteerrss::
       ddaattaa==_n_a_m_e
	      Name  of	an  existing  raster map layer containing the category
	      values to be summed. The cell resolution (area) of the ddaattaa  map
	      will also be used.

       cclluummpp==_n_a_m_e
	      Name of an existing raster map layer that defines the boundaries
	      of each clump. Preferably, this map  should  be  the  output  of
	      _r_._c_l_u_m_p.	 If the user has imposed a mask, the program uses this
	      mask as the cclluummpp map layer if no other cclluummpp layer is specified
	      by the user.

       ssiittee__lliisstt==_n_a_m_e
	      The  name to be assigned to a new GRASS ssiittee__lliisstt file, in which
	      clump centroids can be stored.


EEXXAAMMPPLLEE OOFF RREEPPOORRTT
       The following report might be generated by the command: rr..vvoolluummee dd==_e_l_e_-
       _v_a_t_i_o_n cc==_f_i_e_l_d_s_._o_n_l_y ss==_f_i_e_l_d_._c_e_n_t_e_r_s


       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 _f_i_e_l_d_s_._o_n_l_y
       map layer is a field, that cell category values in  the	_e_l_e_v_a_t_i_o_n  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  appear-
       ing  in	the  _e_l_e_v_a_t_i_o_n map layer, within each field of the _f_i_e_l_d_s_._o_n_l_y
       map layer.  The Total Volume is the sum multiplied by the  e-w  resolu-
       tion times the n-s resolution.

CCEENNTTRROOIIDDSS
       The  coordinates of the clump centroids are the same as those stored in
       the GRASS _s_i_t_e___l_i_s_t_s 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.

FFOORRMMAATT OOFF SSIITTEE LLIISSTT
       For each line of above table the GRASS _s_i_t_e___l_i_s_t_s 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.

AAPPPPLLIICCAATTIIOONNSS
       By preprocessing the _e_l_e_v_a_t_i_o_n map layer with _r_._m_a_p_c_a_l_c and using suit-
       able  masking  or clump maps, very interesting applications can be done
       with _r_._v_o_l_u_m_e.  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.

NNOOTTEESS
       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  fol-
       lowing example: rr..vvoolluummee dd==_d_a_t_a___m_a_p cc==_c_l_u_m_p___m_a_p ss==_s_i_t_e___l_i_s_t > _t_a_b_l_e_._o_u_t



       Output can also be sent directly to the printer, as shown below: rr..vvooll--
       uummee dd==_d_a_t_a___m_a_p cc==_c_l_u_m_p___m_a_p ss==_s_i_t_e___l_i_s_t | 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 _d_a_t_a 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 _c_l_u_m_p
       map layer if none is specified by the user.

SSEEEE AALLSSOO
       _g_._r_e_g_i_o_n

       _r_._c_l_u_m_p

       _r_._m_a_p_c_a_l_c

       _r_._m_a_s_k

       _s_._d_b_._r_i_m

       _s_._m_e_n_u

       _p_a_r_s_e_r

AAUUTTHHOORR
       Dr. James Hinthorne, GIS Laboratory, Central Washington University

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_4 _$



GRASS 5.0							   r.volume(1)
