GRASS logo

NAME

r.boxcount - Find the boxcounting fractal dimension of a binary raster

KEYWORDS

raster, fractal, boxcount

SYNOPSIS

r.boxcount
r.boxcount --help
r.boxcount [-gn] input=string [output=string] k=integer [saturation=float] [resolution=integer] [xterm=string] [--help] [--verbose] [--quiet] [--ui]

Flags:

-g
Create file with instructions for Gnuplot
-n
Gnuplot graph now (i.e. on exit from r.boxcount)
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

input=string [required]
Input raster map
output=string
Output text file for data points
k=integer [required]
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
xterm=string
Name of terminal command
Default: xterm

Table of contents

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). Alternatively the text file could be read and plotted using the R statistical programming lanaguage.

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 saturation * the number of non-zero cells in the region (i.e. before saturation occurs).

The input

output is the basename for the plain text file in which the program output will be stored. The file <output>.dat is created in the user's current working directory.

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.

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 is deemed to have occurred when NbE divided by the number of non-zero cells in the map is >= saturation. Default: 0.2.

xterm is the name of the command for invoking a terminal from which to start gnuplot. Default: xterm.

Setting the -g flag causes r.boxcount to output 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. The -n flag invokes Gnuplot to draw a graph of the results immediately (i.e. automatically). This option requires the -g flag and 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.

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.

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

.

REFERENCES

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.

AUTHOR

Mark Lake, Institute of Archaeology, University College London.

ACKNOWLEDGEMENTS

This program is based on the algorithm described in: Liebovitch and Toth, 1989, 'A Fast Algorithm to Determine Fractal Dimension by Box Counting'. In Physics Letters A, vol. 141, pp.386-390. Note, however, that it uses an improved method the same or similar to that suggested by Daniel Kaplan (see note on p.389).

Uses radix sort algorithm from R. Sedgewick, 1990, 'Algorithms in C', Reading, MA: Addison Wesley.

This program was originally written during the author's tenure of a Leverhulme Special Research Fellowship and was revised while in the employment of University College London.

SOURCE CODE

Available at: r.boxcount source code (history)


Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2018 GRASS Development Team, GRASS GIS 7.4.0 Reference Manual