r.surf.volcano
Creates an artificial surface resembling a seamount or cone volcano.
r.surf.volcano [-r] output=name [peak=float] [crater=float] [method=string] [friction=integer] [slope_steepness=float] [sigma=float] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.surf.volcano output=name
grass.tools.Tools.r_surf_volcano(output, peak=1000.0, crater=0.0, method="polynomial", friction=6, slope_steepness=1.0, sigma=1.0, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.r_surf_volcano(output="name")
This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.
grass.script.run_command("r.surf.volcano", output, peak=1000.0, crater=0.0, method="polynomial", friction=6, slope_steepness=1.0, sigma=1.0, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.run_command("r.surf.volcano", output="name")
Parameters
output=name [required]
Name for output raster map
peak=float
Height of cone
Default: 1000.0
crater=float
Depth of crater below the cone
A larger (deeper) value here also means a wider crater.
Default: 0.0
method=string
Mathematical function for creating the mountain
Allowed values: polynomial, gaussian, lorentzian, logarithmic, exponential
Default: polynomial
polynomial: 1/distance^n
gaussian: Gaussian function
lorentzian: Cauchy-Lorentz distribution
logarithmic: Logarithmic decay
exponential: Exponential decay
friction=integer
Polynomial friction of distance, (the 'n' in 1/d^n)
Higher values generate steeper slopes. (only used with the polynomial method)
Allowed values: 1-25
Default: 6
slope_steepness=float
Slope steepness (used with all methods except polynomial)
For Gaussian: nearer to 0 is flatter, higher values generate steeper slopes. For Lorentzian, logarithmic, and exponential the opposite is true.
Default: 1.0
sigma=float
Surface roughness factor
Nearer to 0 is smoother, higher values make a rougher surface.
Default: 1.0
-r
Roughen the surface
--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 | type(np.ndarray) | type(np.array) | type(gs.array.array), required
Name for output raster map
Used as: output, raster, name
peak : float, optional
Height of cone
Default: 1000.0
crater : float, optional
Depth of crater below the cone
A larger (deeper) value here also means a wider crater.
Default: 0.0
method : str, optional
Mathematical function for creating the mountain
Allowed values: polynomial, gaussian, lorentzian, logarithmic, exponential
polynomial: 1/distance^n
gaussian: Gaussian function
lorentzian: Cauchy-Lorentz distribution
logarithmic: Logarithmic decay
exponential: Exponential decay
Default: polynomial
friction : int, optional
Polynomial friction of distance, (the 'n' in 1/d^n)
Higher values generate steeper slopes. (only used with the polynomial method)
Allowed values: 1-25
Default: 6
slope_steepness : float, optional
Slope steepness (used with all methods except polynomial)
For Gaussian: nearer to 0 is flatter, higher values generate steeper slopes. For Lorentzian, logarithmic, and exponential the opposite is true.
Default: 1.0
sigma : float, optional
Surface roughness factor
Nearer to 0 is smoother, higher values make a rougher surface.
Default: 1.0
flags : str, optional
Allowed values: r
r
Roughen the surface
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.
output : str, required
Name for output raster map
Used as: output, raster, name
peak : float, optional
Height of cone
Default: 1000.0
crater : float, optional
Depth of crater below the cone
A larger (deeper) value here also means a wider crater.
Default: 0.0
method : str, optional
Mathematical function for creating the mountain
Allowed values: polynomial, gaussian, lorentzian, logarithmic, exponential
polynomial: 1/distance^n
gaussian: Gaussian function
lorentzian: Cauchy-Lorentz distribution
logarithmic: Logarithmic decay
exponential: Exponential decay
Default: polynomial
friction : int, optional
Polynomial friction of distance, (the 'n' in 1/d^n)
Higher values generate steeper slopes. (only used with the polynomial method)
Allowed values: 1-25
Default: 6
slope_steepness : float, optional
Slope steepness (used with all methods except polynomial)
For Gaussian: nearer to 0 is flatter, higher values generate steeper slopes. For Lorentzian, logarithmic, and exponential the opposite is true.
Default: 1.0
sigma : float, optional
Surface roughness factor
Nearer to 0 is smoother, higher values make a rougher surface.
Default: 1.0
flags : str, optional
Allowed values: r
r
Roughen the surface
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
DESCRIPTION
r.surf.volcano creates an artificial surface resembling a seamount or cone volcano. The user can alter the size and shape of the mountain and optionally roughen its surface.
NOTES
The friction of distance controls the shape of the mountain when using the default polynomial method. Higher values generate steeper slopes.
The pseudo-kurtosis factor is used with all other methods to control the slope steepness. For the Gaussian method, setting the value nearer to zero creates a flatter surface, while higher values generate steeper slopes. For Lorentzian, logarithmic, and exponential methods, the opposite is true.
The surface roughness factor controls the fixed standard deviation distance (sigma) used in the Gaussian random number generator. It is only used when the -r roughen surface flag is turned on. A value closer to zero makes a smoother surface, a higher value makes a rougher surface.
It is possible to set a negative value for the peak in order to create a pit.
EXAMPLES
Create a simple Gaussian bell
r.surf.volcano -r output=seamount method=gaussian
# view in the display monitor
r.colors seamount color=roygbiv
d.rast seamount
# render in 3D
m.nviz.image elevation_map=seamount out=gaussian \
perspective=10 resolution_fine=1 height=3500
pnmtopng gaussian.ppm > gaussian.png
# export to Matlab
r.out.mat in=seamount out=seamount.mat
# integrate into existing DEM
r.mapcalc "seamount_dem = if(seamount > dem, seamount, dem)"
r.colors seamount_dem color=srtm
Gaussian bell
Create a roughened volcano with a crater
r.surf.volcano -r output=volcano crater=250 --verbose
r.relief in=volcano out=volcano.shade
Create a fancy 3D scene
r.surf.volcano -r output=base_volcano peak=1000 crater=200
r.surf.fractal output=base_fractal
r.mapcalc "artificial_land = base_volcano*3.5 + base_fractal"
m.nviz.image elevation_map=artificial_land out=volcano3D \
perspective=25 resolution_fine=1 height=30000
pnmtopng volcano3D.ppm > volcano3D.png
Synthetic volcano from r.surf.volcano combined with fractal landscape from r.surf.fractal
SEE ALSO
AUTHOR
Hamish Bowman
Dept. of Geology University of Otago Dunedin, New Zealand
SOURCE CODE
Available at: r.surf.volcano source code
(history)
Latest change: Saturday Jul 18 03:02:11 2026 in commit 31cff1a