Skip to content

r.surf.fractal

Creates a fractal surface of a given fractal dimension.

r.surf.fractal output=name [dimension=float] [number=integer] [seed=integer] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.surf.fractal output=name

grass.script.run_command("r.surf.fractal", output, dimension=2.05, number=0, seed=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.surf.fractal", output="name")

grass.tools.Tools.r_surf_fractal(output, dimension=2.05, number=0, seed=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_surf_fractal(output="name")

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

Parameters

output=name [required]
    Name for output raster map
dimension=float
    Fractal dimension of surface (2 < D < 3)
    Default: 2.05
number=integer
    Number of intermediate images to produce
    Default: 0
seed=integer
    Seed value for the random number generator
    Using the same seed ensures identical results, while a randomly generated seed produces different outcomes in each run.
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

output : str, required
    Name for output raster map
    Used as: output, raster, name
dimension : float, optional
    Fractal dimension of surface (2 < D < 3)
    Default: 2.05
number : int, optional
    Number of intermediate images to produce
    Default: 0
seed : int, optional
    Seed value for the random number generator
    Using the same seed ensures identical results, while a randomly generated seed produces different outcomes in each run.
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

output : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
    Name for output raster map
    Used as: output, raster, name
dimension : float, optional
    Fractal dimension of surface (2 < D < 3)
    Default: 2.05
number : int, optional
    Number of intermediate images to produce
    Default: 0
seed : int, optional
    Seed value for the random number generator
    Using the same seed ensures identical results, while a randomly generated seed produces different outcomes in each run.
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

Returns:

result : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned. If an array type (e.g., np.ndarray) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.

Raises:

grass.tools.ToolError: When the tool ended with an error.

DESCRIPTION

r.surf.fractal creates a fractal surface of a given fractal dimension. It uses the spectral synthesis method. The module can create intermediate layers showing the build up of different spectral coefficients (see Saupe, pp.106-107 for an example of this).

This module generates naturally looking synthetical elevation models (DEM).

NOTE

This module requires the FFTW library for computing Discrete Fourier Transforms.

EXAMPLE

Generate surface using fractals in selected region, set color table and display with shade.

g.region -p raster=elevation

r.surf.fractal output=fractals

r.colors map=fractals color=byr
r.relief input=fractals output=fractals_shade

d.mon wx0
d.shade shade=fractals_shade color=fractals b=50

Artificial surface created with fractals
Artificial surface created with fractals

Compare results when using different fractal dimensions:

# D=2.0005
g.region -dp
r.surf.fractal out=dem_d2_0005 dim=2.0005
r.info -r dem_d2_0005
r.mapcalc "dem_d2_0005_final = 1.0 * dem_d2_0005 + abs(min(dem_d2_0005))"
r.colors dem_d2_0005_final color=terrain
r.slope.aspect dem_d2_0005_final aspect=dem_d2_0005_final_as

# D=2.90
r.surf.fractal out=dem_d2_90 dim=2.90
r.info -r dem_d2_90
r.mapcalc "dem_d2_90_final = 1.0 * dem_d2_90 + abs(min(dem_d2_90))"
r.colors dem_d2_90_final color=terrain
r.slope.aspect dem_d2_90_final aspect=dem_d2_90_final_as

Artificial DEMs created with fractals
Artificial DEMs created with fractals:
top: fractal dimension d=2.0005 (left: elevation map, right: aspect map)
top: fractal dimension d=2.90 (left: elevation map, right: aspect map)

REFERENCES

Saupe, D. (1988) Algorithms for random fractals, in Barnsley M., Devaney R., Mandelbrot B., Peitgen, H-O., Saupe D., and Voss R. (1988) The Science of Fractal Images, Ch. 2, pp.71-136. London: Springer-Verlag.

SEE ALSO

r.surf.contour, r.surf.idw, r.surf.gauss, r.surf.random, v.surf.idw, v.surf.rst

AUTHOR

Jo Wood, Midlands Regional Research Laboratory (ASSIST), University of Leicester

SOURCE CODE

Available at: r.surf.fractal source code (history)
Latest change: Thursday May 08 20:58:05 2025 in commit 4144ba8