NAME

       r3.stats  - Generates volume statistics for 3D raster maps.

KEYWORDS

       raster3d, voxel, statistics

SYNOPSIS

       r3.stats
       r3.stats help
       r3.stats [-e] input=name  [nsteps=integer]   [--verbose]  [--quiet]

   Flags:
       -e
           Calculate statistics based on equal value groups

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       input=name
           Name of input raster3d map

       nsteps=integer
           Number of subranges to collect stats from
           Default: 20

DESCRIPTION

       r3.stats  calculates volume statistics for 3D raster maps.  Volumes are created on base of
       value subranges or groups of equal values.  The default number of subranges is 20 and  can
       vary  from  1  to  infinite.   Larger  number  of  subranges  will result in larger memory
       consumption.  The volumes are calculated in qubic meters. Null values are marked with "*".
       If the flag -e is set, the number of subranges will be ignored.

NOTES

       As  with  most GRASS 3D raster map modules, r3.stats operates on the cell array defined by
       the current 3D region settings, not the original extent and resolution of the  input  map.
       See g.region.

       The  region  setting will not effect the memory consumption of this module.  The number of
       subranges in case of value range calculation or the number of equal  value  groups  effect
       the  memory  consumption  and  the  calculation  time.   The  user  can expect a huge time
       consumption to calculate the equal value groups (flag -e) if large region  settings  occur
       for maps which have many equal value groups (> 100000).

EXAMPLES

   Lausanne FOSS4G 2006 3D demo dataset example
       The  3D  raster  map geology has three values. Each value represents a specific geological
       layer, clay = 1, sand = 2 and bedrock = 3. To calculate  the  volume  of  each  geological
       layer, we can use the flag -e to group equal values into single volumes.  r3.stats geology
       -e will produce the following output:

         num   |        value       |     volume    |   perc  |    count
             1             1.000000   300822000.000   50.13700        50137
             2             2.000000   101400000.000   16.90000        16900
             3             3.000000   197778000.000   32.96300        32963
             4                    *           0.000   0.00000            0
       Number of groups with equal values: 3
       Sum of non Null cells:
               Volume = 600000000.000
               Percentage = 100.000
               Count = 100000
       Sum of all cells:
               Volume = 600000000.000
               Percentage = 100.000
               Count = 100000

   Generic example

       #create a small 3D region
       g.region n=1000 s=0 e=2000 w=0 t=300 b=0 res3=100
       #create a raster3D map with row() and null values
       r3.mapcalc "volmap = if(row() == 5, null(), row())"
       #run r3.stats with a subrange of 10
       r3.stats input=volmap nsteps=10
       #the result should look like this
        num   | minimum <= value   | value < maximum    |     volume    |   perc  | cell count
             1          1.000000000          1.900000000    60000000.000   10.00000           60
             2          1.900000000          2.800000000    60000000.000   10.00000           60
             3          2.800000000          3.700000000    60000000.000   10.00000           60
             4          3.700000000          4.600000000    60000000.000   10.00000           60
             5          4.600000000          5.500000000           0.000   0.00000            0
             6          5.500000000          6.400000000    60000000.000   10.00000           60
             7          6.400000000          7.300000000    60000000.000   10.00000           60
             8          7.300000000          8.200000000    60000000.000   10.00000           60
             9          8.200000000          9.100000000    60000000.000   10.00000           60
            10          9.100000000         10.000000001    60000000.000   10.00000           60
            11                    *                    *    60000000.000   10.00000           60
       Sum of non Null cells:
               Volume = 540000000.000
               Percentage =  90.000
               Cell count = 540
       Sum of all cells:
               Volume = 600000000.000
               Percentage = 100.000
               Cell count = 600

SEE ALSO

        g.region, r3.univar, r.stats, r.statistics, v.univar

AUTHOR

       Sören Gebbert

       Last changed: $Date: 2011-09-13 13:13:36 -0700 (Tue, 13 Sep 2011) $

       Full index

       © 2003-2013 GRASS Development Team