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 out-
	      put table.

	      The centroid easting of each clump.

	      The  centroid  northing of each clump. These values
	      are output under the "Centroid Easting"  and  "Cen-
	      troid  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 resolu-
	      tion. 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 defini-
       tions 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  speci-
	      fied 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  val-
       ues  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  appearing  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 resolution 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 suitable 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 poten-
       tial 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   following  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..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 | 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)
