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$