GRASS logo

NAME

r.boxcount

KEYWORDS

SYNOPSIS

r.boxcount
r.boxcount help
r.boxcount [-gnot] input=name [output=string] k=integer [saturation=float] [resolution=integer] [--verbose] [--quiet]

Flags:

-g
Create file with instructions for Gnuplot
-n
Gnuplot graph now (i.e. on exit from r.boxcount)
-o
Overwrite output file if it exists
-t
Terse output only (i.e. only report D calculated by regression)
--verbose
Verbose module output
--quiet
Quiet module output

Parameters:

input=name
Name of input raster map
output=string
Output text file for data points
k=integer
Max 1/box size is 2^k
saturation=float
Occupied boxes as fraction of data points at saturation
Default: 0.2
resolution=integer
Smallest 1/box size to use in regression (= 1, 2, 4,...)
Default: 4

r.boxcount

NAME r.boxcount - Calculate fractal dimension by box counting. (GRASS Raster Program) SYNOPSIS r.boxcount r.boxcount help r.boxcount [-gnot] input=name [output=name] k=value [resolution=value] [saturation=value] DESCRIPTION r.boxcount calculates the box-counting (fractal) dimension of a binary raster map. The program counts the minimum number of boxes, NbE, of size 1,...,1/2^k that are required to cover all non-zero cells. It then uses this information to calculate the fractal dimension for each pair of box sizes. The results may be saved in a text file, in which case they may also be displayed in graph form by invoking the program Gnuplot (which, athough not part of GRASS, is widely available on UNIX-like systems). r.boxcount also calculates the box-counting dimension by linear regression over a range of box sizes determined by the parameters resolution and saturation. The largest box size that will be used is 1/resolution (i.e. this is the coarsest resolution). The smallest box size is set to that for which the results satisfy the condition NbE < saturation * the number of non-zero cells in the region (i.e. before saturation occurs). OPTIONS The program can be run either non-interactively or interactively. To run r.boxcount non-interactively, the user must specify at least an input file name and the value of k on the command line; any remaining parameters whose values are unspecified on the command line will be set to their default values (see below). To run the r.boxcount interactively the user should simply type r.boxcount on the command line, in which case the program will prompt for parameter values using the standard GRASS interface described in the manual entry for parser. Flags: -g Create a file containing the commands for Gnuplot to draw a graph of the results. This file will be created in the current working directory with the name output.gnu. This option requires that an output filename has been provided. GRASS 4.2.1 Baylor University 1 r.boxcount GRASS Reference Manual r.boxcount -n Invoke Gnuplot to draw a graph of the results now (i.e. automatically). This option requires the -g flag. -o Silently overwrite the files output.dat and output.gnu if they already exist in the current working directory. -t Provide only a terse description of the results (i.e. provide no information about progress and only display the fractal dimension calculated by linear regression). This option applies to the on-screen output only; it does not affect that written to output.dat. Parameters: input=name The name of a raster map layer containing binary values 0 or 1. output=name Basename for the text file in which the program output will be stored. The file name.dat is created in the user's current working directory according to whether the flag -o has been set. k=value The program calculates the box counting dimension of the input map using box sizes from 1,...,1/2^k. Note that the current region will be covered by 1 box of size 1, 4 of size 1/2, 16 of size 1/4, etc. The program automatically skips box sizes that are smaller than the size of one map cell. resolution=name Set the largest box size to 1/resolution instead of 1. Values of resolution must be from the sequence 1, 2, 4, 8, 16, 32, 64, 128, 256,... Default: 4 saturation=value Saturation is deemed to have occured when NbE divided by the number of non-zero cells in the map is >= saturation. Default: 0.2 NON-INTERACTIVE PROGRAM USE The flag -n should not be used if the program is to be invoked from a shell script since Gnuplot will wait on the user pressing the RETURN key before exiting. GRASS 4.2.1 Baylor University 2 r.boxcount GRASS Reference Manual r.boxcount NOTES r.boxcount may give erroneous results if the current region is not square, i.e. the number of rows and columns are not equal. r.boxcount works in the current geographic region with the current mask. The last row of the table of results does not contain a value for the fractal dimension, D, because this can only be calculated for pairs of box sizes. In the output file this missing value is replaced by the dummy value 99.999. In both cases the recorded values of D always relate to the box sizes recorded in the given row and the following row. It is a good idea to examine the table and/or graph of results before accepting the fractal dimension calculated by linear regression based on the default values of resolution and saturation. The user may find it helpful to study the results of applying r.boxcount to a theoretical fractal such as the Sierpinski Gasket. r.rifs may be used to produce raster maps containing this and many other well known fractals. SEE ALSO r.rifs, parser For an introduction to the box-counting method of calculating fractal dimension see: Peitgen, Jurgens and Saupe, 1992, Chaos and Fractals: New Frontiers of Science, Springer-Verlag: New York. Chapt. 4. ACKNOWLEDGEMENTS This program was written during the author's tenure of a Leverhulme Special Research Fellowhip. AUTHOR Mark Lake, Institute of Archaeology, University College London. NOTICE This program is part of the contrib section of the GRASS distribution. As such, it is externally contributed code that has not been examined or tested by the Office of GRASS Integration. GRASS 4.2.1 Baylor University 3

AUTHOR

GRASS Development Team

Last changed: $Date$

Main index - raster index - Full index

© 2003-2016 GRASS Development Team