r.roughness.vector

Calculates surface roughness in a moving-window, as the orientation of vectors normal to surface planes.

r.roughness.vector elevation=name slope=string aspect=string [window=integer] [strength=string] [fisher=string] [compass=string] [colatitude=string] [xcos=string] [ycos=string] [zcos=string] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.roughness.vector elevation=name slope=string aspect=string

grass.script.run_command("r.roughness.vector", elevation, slope, aspect, window=3, strength=None, fisher=None, compass=None, colatitude=None, xcos=None, ycos=None, zcos=None, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.roughness.vector", elevation="name", slope="string", aspect="string")

Parameters

Command linePython (grass.script)

elevation=name [required]
    Name of elevation raster map
slope=string [required]
    Input slope map
aspect=string [required]
    Input aspect map
window=integer
    Moving-window size (uses r.neighbors)
    Default: 3
strength=string
    Output "vector strength" map
fisher=string
    Output "Fisher's K parameter" map
compass=string
    Input compass aspect map (optional)
colatitude=string
    Input colatitude map (optional)
xcos=string
    Input x directional cosine map (optional)
ycos=string
    Input y directional cosine map (optional)
zcos=string
    Input z directional cosine map (optional)
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

elevation : str, required
    Name of elevation raster map
    Used as: input, raster, name
slope : str, required
    Input slope map
    Used as: input, raster
aspect : str, required
    Input aspect map
    Used as: input, raster
window : int, optional
    Moving-window size (uses r.neighbors)
    Default: 3
strength : str, optional
    Output "vector strength" map
    Used as: input, raster
fisher : str, optional
    Output "Fisher's K parameter" map
    Used as: input, raster
compass : str, optional
    Input compass aspect map (optional)
    Used as: input, raster
colatitude : str, optional
    Input colatitude map (optional)
    Used as: input, raster
xcos : str, optional
    Input x directional cosine map (optional)
    Used as: input, raster
ycos : str, optional
    Input y directional cosine map (optional)
    Used as: input, raster
zcos : str, optional
    Input z directional cosine map (optional)
    Used as: input, raster
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

In this script surface roughness is taken as the dispersion of vectors normal to surface areas (pixels). Normal vectors are defined by slope and aspect.

This script will create several temporary maps, for the directional cosines in each direction (x,y,z), for the sum of these cosines and vector strength.

The options compass, colatitude, xcos, ycosm and zcos are created as temporary files each time the script is run. If the user wants to create several map (with different window sizes, for instance), it is recommended to create those maps with r.mapcalc and use them as input:

  r.mapcalc compass = "if(aspect==0,0,if(aspect < 90, 90-aspect, 360+90-aspect))"
  r.mapcalc colatitude = "90 - slope"
  r.mapcalc xcos = "sin(colatitude)*cos(compass)"
  r.mapcalc ycos = "sin(colatitude)*sin(compass)"
  r.mapcalc zcos = "cos(colatitude)"

If the user does not specify the output maps names, they will be set to

INPUT_MAP_vector_strength_NxN

and

INPUT_MAP_fisher_K_NxN

where N is the window size.

EXAMPLE

  # calculate roughness factor by search window = 5
  r.roughness.vector elevation=DEM slope=slope aspect=aspect window=5

REFERENCES

Hobson, R.D., 1972. Surface roughness in topography: quantitative approach. In: Chorley, R.J. (ed). Spatial analysis in geomorphology. Methuer, London, p.225-245.

McKean, J. & Roering, J., 2004. Objective landslide detection and surface morphology mapping using high-resolution airborne laser altimetry. Geomorphology, 57:331-351. https://doi.org/10.1016/S0169-555X(03)00164-8.

Grohmann, C.H., Smith, M.J. & Riccomini, C., 2011. Multiscale Analysis of Topographic Surface Roughness in the Midland Valley, Scotland. Geoscience and Remote Sensing, IEEE Transactions on, 49:1200-1213. https://doi.org/10.1109/TGRS.2010.2053546

AUTHORS

Carlos Henrique Grohmann - Institute of Energy and Environment, University of São Paulo, Brazil. (http://carlosgrohmann.com)
Helmut Kudrnovsky

SOURCE CODE

Available at: r.roughness.vector source code (history)
Latest change: Thursday Mar 20 21:36:57 2025 in commit 7286ecf