r.geomorphon(1grass)

📦
version 8.5.0 · 10 versions
, in alpine 3.24, ubuntu stonking

okay so bestie, come closer — this is r.geomorphon(1grass) from the GRASS User's Manual, and she is that girl. We're gonna make terrain forms make sense together, no cap. 💖

✨ NAME ✨

r.geomorphon — calculates geomorphons (terrain forms) and associated geometry using machine vision approach. 🦋

🎀 KEYWORDS 🎀

raster, geomorphons, terrain patterns, machine vision geomorphometry

💅 SYNOPSIS 💅

r.geomorphon
r.geomorphon --help
r.geomorphon [-me] elevation=name  [forms=name]   [ternary=name]
       [positive=name]   [negative=name]   [intensity=name]   [exposition=name]
       [range=name]   [variance=name]   [elongation=name]   [azimuth=name]
       [extend=name]   [width=name]  search=integer skip=integer flat=float
       dist=float  [comparison=string]   [coordinates=east,north]
       [profiledata=name]   [profileformat=string]   [--overwrite]  [--help]
       [--verbose]  [--quiet]  [--ui]

🚩 Flags 🚩

  • -m — use meters to define search units. (the default is cells, bestie)
  • -e — use extended form correction
  • --overwrite — allow output files to overwrite existing files 👀
  • --help — print usage summary
  • --verbose — verbose module output
  • --quiet — quiet module output 🤫
  • --ui — force launching GUI dialog ✨

🧚 Parameters 🧚

  • elevation=name [required] — name of input elevation raster map
  • forms=name — most common geomorphic forms
  • ternary=name — code of ternary patterns
  • positive=name — code of binary positive patterns
  • negative=name — code of binary negative patterns
  • intensity=name — rasters containing mean relative elevation of the form
  • exposition=name — rasters containing maximum difference between extend and central cell
  • range=name — rasters containing difference between max and min elevation of the form extend
  • variance=name — rasters containing variance of form boundary
  • elongation=name — rasters containing local elongation
  • azimuth=name — rasters containing local azimuth of the elongation
  • extend=name — rasters containing local extend (area) of the form
  • width=name — rasters containing local width of the form
  • search=integer [required] — outer search radius. Default: 3
  • skip=integer [required] — inner search radius. Default: 0
  • flat=float [required] — flatness threshold (degrees). Default: 1
  • dist=float [required] — flatness distance, zero for none. Default: 0
  • comparison=string — comparison mode for zenith/nadir line-of-sight search. Options: anglev1, anglev2, anglev2_distance. Default: anglev1
  • coordinates=east,north — coordinates to profile
  • profiledata=name — profile output file name ("-" for stdout)
  • profileformat=string — profile output format. Options: json, yaml, xml

🌈 DESCRIPTION 🌈

r.geomorphon calculates terrain forms using a machine-vison technique called geomorphons. periodt.

👑 What is geomorphon: 👑

A geomorphon is a whole new concept of presentation and analysis of terrain forms, and honestly? it's giving icon status. 💫 This concept utilises an 8-tuple pattern of the visibility neighbourhood, and it breaks the well known limitation of the standard calculus approach, where all terrain forms cannot be detected in a single window size. (the way that standard approach could never 💀)

So the pattern arises from a comparison of a focus pixel with its eight neighbors, starting from the one located to the east and continuing counterclockwise, producing a ternary operator. For example, a tuple {+,-,-,-,0,+,+,+} describes one possible pattern of relative measures {higher, lower, lower, lower, equal, higher, higher, higher} for pixels surrounding the focus pixel. slay.

ngl it's important to stress that the visibility neighbors are not necessarily immediate neighbors of the focus pixel in the grid — they're the pixels determined from the line-of-sight principle along the eight principal directions. 🧭

This principle relates surface relief and horizontal distance by means of so-called zenith and nadir angles along the eight principal compass directions. The ternary operator converts the information contained in all the pairs of zenith and nadir angles into the ternary pattern (8-tuple). The result depends on the values of two parameters: search radius (L) and relief threshold (d).

  • The search radius is the maximum allowable distance for calculation of zenith and nadir angles.
  • The relief threshold is a minimum value of difference between LOSs angle (zenith and nadir) that is considered significantly different from the horizon.

Two lines-of-sight are necessary because zenith LOS only does not detect positive forms correctly. 🫶

There are 3**8 = 6561 possible ternary patterns (8-tuples). By removing all patterns that are the result of either rotation or reflection of other patterns, a set of 498 patterns remains, referred to as geomorphons. This is a comprehensive and exhaustive set of idealized landforms that are independent of the size, relief, and orientation of the actual landform. iconic. 👑

Form recognition depends on two free parameters: Search radius and flatness threshold.

  • Using larger values of L is tantamount to terrain classification from a higher and wider perspective, whereas using smaller values of L is tantamount to terrain classification from a local point of view.
  • A character of the map depends on the value of L.
  • Using small value of L results in the map that correctly identifies landforms if their size is smaller than L; landforms having larger sizes are broken down into components.
  • Using larger values of L allows simultaneous identification of landforms on variety of sizes at the expense of recognition smaller, second-order forms.

There are two additional parameters:

  • skip radius, used to eliminate impact of small irregularities. 🙈
  • On the contrary, flatness distance eliminates the impact of very high distance (in meters) of search radius which may not detect elevation difference if this is at a very far distance. Important especially with low resolution DEMs, bestie. 💜

✨ OPTIONS ✨

  • -m — okay so all the distance parameters (that's search, skip and flat distances btw bestie) get supplied as meters instead of cells (which is the default, fyi). To dodge the whole situation where the distance you gave is smaller than one cell, the program first checks if your distance is longer than one cell in both the NS and WE directions. For LatLong projection it only checks the NS distance, because in latitude the angular unit always covers a bigger-or-equal distance than the longitude one, periodt. If you give the distance in cells, then for all projections it gets recalculated into meters using the formula: number_of_cells*resolution_along_NS_direction. This matters a lot if you're calculating geomorphons for big areas in LatLong projection. 💅
  • elevation — the Digital Elevation Model, your main character 🏔️. The data can be literally any type and any projection, no cap. During calculation the DEM is stored as a floating point raster.
  • search — this decides the length of the geodesic distances in all eight directions where the line-of-sight gets calculated. To speed things up, it only picks the cells whose centers fall into the distance. ⭐
  • skip — this sets the length of the geodesic distances at the beginning of calculation in all eight directions, where the line-of-sight is yet to be calculated. To make it fast, this distance always gets recalculated into a number of cells that are skipped at the start of every line-of-sight, and it ends up equal in all directions. This parameter eliminates forms of very small extent — i.e. smaller than the skip parameter. 🦋
  • flat — the difference (in degrees) between the zenith and nadir line-of-sight that indicates a flat direction. Higher threshold = more flat maps. If your map resolution is low (more than 1 km per cell) the threshold should be very small (much smaller than 1 degree) because over such a distance 1 degree of difference means several meters of height difference. 😭
  • dist — the Flat distance. This is an extra parameter defining the distance above which the threshold starts to decrease, all to avoid problems with pseudo-flat line-of-sights if a real elevation difference shows up at the distance where its value is higher (TO BE CORRECTED). 🙈
  • comparison — the comparison mode for the zenith/nadir line-of-sight search. "anglev1" is the original r.geomorphon comparison mode. "anglev2" is an improved mode that better handles angle thresholds and zenith/nadir angles that are exactly equal. "anglev2_distance" does all that plus takes the zenith/nadir distances into account when the angles are exactly equal. 👑
  • forms — returns a geomorphic map with the 10 most popular terrestrial forms. The legend for the forms, its definition by the number of + and -, and its idealized visualisation are all presented at the image. 🎀

🧚 Forms represented by geomorphons

  • ternary — returns the code of one of 498 unique ternary patterns for every cell. The code is a decimal representation of 8-tuple minimalised patterns written in ternary system. The full list of patterns lives in the source code directory as patterns.txt. This map can be used to create an alternative form classification using a supervised approach. ✨
  • positive and negative — returns codes of binary patterns for zenith (positive) and nadir (negative) line-of-sights. The code is a decimal representation of 8-tuple minimalised patterns written in binary system. The full list of patterns is available in the source code directory as patterns.txt.
  • coordinates — the central point of a single geomorphon to profile. The central point must be within the computational region, which should be large enough to accommodate the search radius. Setting the region bigger than that won't produce more accurate data — in the current implementation it just slows the computation down. For the best results, remember to align the region to the raster cells. Profiling is mutually exclusive with any raster outputs, but other parameters and flags (like elevation, search, comparison, -m and -e) work as usual. 💖
  • profiledata — the output file name for the complete profile data. "-" means write to the standard output. The data is in a machine-readable format and it includes assorted values describing the computation context and parameters, plus its intermediate and final results.
  • profileformat — the format of the profile data: "json", "yaml" or "xml".
NOTE: the parameters below are experimental. Their usefulness is currently under investigation. 🧪
  • intensity — returns the average difference between the central cell of the geomorphon and the eight cells in the visibility neighbourhood. This parameter shows the local (as is visible) exposition/abasement of the form in the terrain.
  • range — returns the difference between the minimum and maximum values of the visibility neighbourhood.
  • variance — returns the variance (difference between particular values and the mean value) of the visibility neighbourhood.
  • extend — returns the area of the polygon created by the 8 points where the line-of-sight cuts the terrain (see the image in the description section). 🌸
  • azimuth — returns the orientation of the polygon constituting the geomorphon. This orientation is currently calculated as the orientation of the least square fit line to the eight verticles of this polygon.
  • elongation — returns the proportion between the sides of the bounding box rectangle calculated for the geomorphon rotated to fit the least square line.
  • width — returns the length of the shorter side of the bounding box rectangle calculated for the geomorphon rotated to fit the least square line.

📝 NOTES 📝

From a computational point of view there are no limitations on the input DEM and the free parameters used in the calculation. But like… in practice there are some issues with DEM resolution and search radius, bestie. A low resolution DEM, especially above 1 km per cell, requires a smaller-than-default flatness threshold. On the other hand, only forms with a high local elevation difference will be detected correctly. Why? Because at very high distances (think order of kilometers or higher) even a relatively high elevation difference gets recognized as flat. For example: at a distance of 8 km (8 cells with a 1 km resolution DEM) a relative elevation difference of at least 136 m is required for it to be noticed as non-flat. The flatness distance threshold may be helpful to avoid this problem. 💀

🎬 EXAMPLES 🎬

Geomorphon calculation: extraction of terrestrial landforms

Geomorphon calculation example using the EU DEM 25m:

g.region raster=eu_dem_25m -p
r.geomorphon elevation=eu_dem_25m forms=eu_dem_25m_geomorph
# verify terrestrial landforms found in DEM
r.category eu_dem_25m_geomorph
 1  flat
 2  peak
 3  ridge
 4  shoulder
 5  spur
 6  slope
 7  hollow
 8  footslope
 9  valley
10 pit

Extraction of peaks

Using the resulting terrestrial landforms map, single landforms can be extracted — e.g. the peaks — and converted into a vector point map. Obsessed with this one fr fr:

r.mapcalc expression="eu_dem_25m_peaks = if(eu_dem_25m_geomorph == 2, 1, null())"
r.thin input=eu_dem_25m_peaks output=eu_dem_25m_peaks_thinned
r.to.vect input=eu_dem_25m_peaks_thinned output=eu_dem_25m_peaks type=point
v.info input=eu_dem_25m_peaks

🔥 REFERENCES 🔥

  • Stepinski, T., Jasiewicz, J., 2011, Geomorphons - a new approach to classification of landform, in : Eds: Hengl, T., Evans, I.S., Wilson, J.P., and Gould, M., Proceedings of Geomorphometry 2011, Redlands, 109-112 (PDF)
  • Jasiewicz, J., Stepinski, T., 2013, Geomorphons - a pattern recognition approach to classification and mapping of landforms, Geomorphology, vol. 182, 147-156 (DOI: 10.1016/j.geomorph.2012.11.005)

👀 SEE ALSO 👀

r.param.scale

🫶 AUTHORS 🫶

Jarek Jasiewicz, Tomek Stepinski (merit contribution)

💾 SOURCE CODE 💾

Available at: r.geomorphon source code (history)

Latest change: Monday Nov 17 13:07:11 2025 in commit: 66c1733a055484761c1c25bdec937ebf0b31f00e

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

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual

okay that's the whole entire page bestie, and lowkey it's giving iconic 💅✨ — this is GRASS 8.5.0, the r.geomorphon(1grass) page, last touched Monday Nov 17 13:07:11 2025 (commit 66c1733a055484761c1c25bdec937ebf0b31f00e), © 2003-2026 GRASS Development Team. slay, go map some landforms 🏔️🎀

📦 where this page comes from