1r.geomorphon(1)             GRASS GIS User's Manual            r.geomorphon(1)
2
3
4

NAME

6       r.geomorphon   -  Calculates geomorphons (terrain forms) and associated
7       geometry using machine vision approach.
8

KEYWORDS

10       raster, geomorphons, terrain patterns, machine vision geomorphometry
11

SYNOPSIS

13       r.geomorphon
14       r.geomorphon --help
15       r.geomorphon  [-me]   elevation=name    [forms=name]     [ternary=name]
16       [positive=name]      [negative=name]      [intensity=name]     [exposi‐
17       tion=name]   [range=name]   [variance=name]   [elongation=name]    [az‐
18       imuth=name]   [extend=name]   [width=name]  search=integer skip=integer
19       flat=float dist=float   [comparison=string]    [coordinates=east,north]
20       [profiledata=name]    [profileformat=string]    [--overwrite]  [--help]
21       [--verbose]  [--quiet]  [--ui]
22
23   Flags:
24       -m
25           Use meters to define search units (default is cells)
26
27       -e
28           Use extended form correction
29
30       --overwrite
31           Allow output files to overwrite existing files
32
33       --help
34           Print usage summary
35
36       --verbose
37           Verbose module output
38
39       --quiet
40           Quiet module output
41
42       --ui
43           Force launching GUI dialog
44
45   Parameters:
46       elevation=name [required]
47           Name of input elevation raster map
48
49       forms=name
50           Most common geomorphic forms
51
52       ternary=name
53           Code of ternary patterns
54
55       positive=name
56           Code of binary positive patterns
57
58       negative=name
59           Code of binary negative patterns
60
61       intensity=name
62           Rasters containing mean relative elevation of the form
63
64       exposition=name
65           Rasters containing maximum difference between  extend  and  central
66           cell
67
68       range=name
69           Rasters  containing difference between max and min elevation of the
70           form extend
71
72       variance=name
73           Rasters containing variance of form boundary
74
75       elongation=name
76           Rasters containing local elongation
77
78       azimuth=name
79           Rasters containing local azimuth of the elongation
80
81       extend=name
82           Rasters containing local extend (area) of the form
83
84       width=name
85           Rasters containing local width of the form
86
87       search=integer [required]
88           Outer search radius
89           Default: 3
90
91       skip=integer [required]
92           Inner search radius
93           Default: 0
94
95       flat=float [required]
96           Flatness threshold (degrees)
97           Default: 1
98
99       dist=float [required]
100           Flatness distance, zero for none
101           Default: 0
102
103       comparison=string
104           Comparison mode for zenith/nadir line-of-sight search
105           Options: anglev1, anglev2, anglev2_distance
106           Default: anglev1
107
108       coordinates=east,north
109           Coordinates to profile
110
111       profiledata=name
112           Profile output file name ("-" for stdout)
113
114       profileformat=string
115           Profile output format
116           Options: json, yaml, xml
117

DESCRIPTION

119   What is geomorphon:
120       Geomorphon is a new concept of presentation  and  analysis  of  terrain
121       forms.  This  concept utilises 8-tuple pattern of the visibility neigh‐
122       bourhood  and breaks well known limitation  of  standard  calculus  ap‐
123       proach  where  all  terrain forms cannot be detected in a single window
124       size. The pattern arises from a comparison of a focus  pixel  with  its
125       eight  neighbors starting from the one located to the east and continu‐
126       ing counterclockwise  producing ternary operator. For example, a  tuple
127       {+,-,-,-,0,+,+,+}  describes  one possible pattern of relative measures
128       {higher, lower, lower, lower, equal, higher, higher, higher} for pixels
129       surrounding  the  focus pixel. It is important to stress that the visi‐
130       bility neighbors are not necessarily an immediate neighbors of the  fo‐
131       cus pixel in the grid, but the pixels determined from the line-of-sight
132       principle along the eight principal directions. This principle  relates
133       surface relief and horizontal distance by means of so-called zenith and
134       nadir angles along the eight principal compass directions. The  ternary
135       operator  converts the information contained in all the pairs of zenith
136       and nadir angles into the ternary pattern (8-tuple). The result depends
137       on the values of two parameters: search radius (L) and relief threshold
138       (d). The search radius is the maximum allowable distance  for  calcula‐
139       tion  of  zenith  and  nadir  angles. The relief threshold is a minimum
140       value of difference between  LOSs angle (zenith and nadir) that is con‐
141       sidered  significantly  different  from the horizon. Two lines-of-sight
142       are necessary due to zenith LOS only, does not  detect  positive  forms
143       correctly.
144
145       There  are 3**8 = 6561 possible ternary patterns (8-tuples). However by
146       eliminating all patterns that are results of either rotation or reflec‐
147       tion  of  other patterns wa set of 498 patterns remain referred as geo‐
148       morphons.  This is a comprehensive  and  exhaustive  set  of  idealized
149       landforms  that are independent of the size, relief, and orientation of
150       the actual landform.
151
152       Form recognition depends on two  free  parameters:  Search  radius  and
153       flatness  threshold. Using larger values of L and is tantamount to ter‐
154       rain classification from a higher and wider perspective, whereas  using
155       smaller  values of L and is tantamount to terrain classification from a
156       local point of view. A character of the map depends on the value of  L.
157       Using  small  value  of  L results in the map that correctly identifies
158       landforms if their size is smaller  than  L;  landforms  having  larger
159       sizes  are broken down into components. Using larger values of L allows
160       simultaneous identification of landforms on variety of sizes in expense
161       of  recognition  smaller,  second-order forms. There are two additional
162       parameters: skip radius used to eliminate impact of  small  irregulari‐
163       ties.  On  the contrary flatness distance eliminates the impact of very
164       high distance (in meters) of search radius which may not detect  eleva‐
165       tion  difference  if this is at very far distance. Important especially
166       with low resolution DEMS.
167

OPTIONS

169       -m
170           All distance parameters (search, skip, flat distances) are supplied
171           as  meters instead of cells (default). To avoid situation when sup‐
172           plied distances is smaller than one cell  program  first  check  if
173           supplied  distance is longer than one cell in both NS and WE direc‐
174           tions. For LatLong projection only NS distance checked, because  in
175           latitude angular unit comprise always bigger or equal distance than
176           longitude one. If distance is supplied in cells,  For  all  projec‐
177           tions   is   recalculated   into  meters  according  formula:  num‐
178           ber_of_cells*resolution_along_NS_direction. It is important if geo‐
179           morphons are calculated for large areas in LatLong projection.
180
181       elevation
182           Digital  elevation  model.  Data can be of any type and any projec‐
183           tion. During calculation DEM is stored as floating point raster.
184
185       search
186           Determines length on the geodesic distances in all eight directions
187           where  line-of-sight  is calculated. To speed up calculation is de‐
188           termines only these cells which centers falls into the distance.
189
190       skip
191           Determines length on the geodesic distances  at  the  beginning  of
192           calculation  all eight directions where line-of-sight is yet calcu‐
193           lated. To speed up calculation this distance is always recalculated
194           into  number  of  cell  which are skipped at the beginning of every
195           line-of-sight and is equal in all direction.  This parameter elimi‐
196           nates forms of very small extend, smaller than skip parameter.
197
198       flat
199           The  difference (in degrees) between zenith and nadir line-of-sight
200           which indicate flat direction. If  higher  threshold  produce  more
201           flat  maps.  If  resolution  of  the map is low (more than 1 km per
202           cell) threshold should be very small (much smaller than  1  degree)
203           because  on  such distance 1 degree of difference means several me‐
204           ters of high difference.
205
206       dist
207           >Flat distance. This is additional parameter defining the  distance
208           above which the threshold starts to decrease to avoid problems with
209           pseudo-flat line-of-sights if real elevation difference appears  on
210           the distance where its value is higher (TO BE CORRECTED).
211
212       comparison
213           Comparison mode for zenith/nadir line-of-sight search. "anglev1" is
214           the original r.geomorphon comparison mode. "anglev2" is an improved
215           mode, which better handles angle thresholds and zenith/nadir angles
216           that are exactly equal.  "anglev2_distance"  in  addition  to  that
217           takes  the  zenith/nadir distances into account when the angles are
218           exactly equal.
219
220       forms
221           Returns geomorphic map with 10 most popular terrestrial forms. Leg‐
222           end for forms, its definition by the number of + and - and its ide‐
223           alized  visualisation are presented at the image.
224
225   Forms represented by geomorphons:
226       ternary
227           returns code of one of 498 unique ternary patterns for every  cell.
228           The  code  is  a decimal representation of 8-tuple minimalised pat‐
229           terns written in ternary system. Full list of patterns is available
230           in  source  code directory as patterns.txt. This map can be used to
231           create alternative form classification using supervised approach.
232
233       positive and negative
234           returns codes binary patterns for zenith (positive) and nadir (neg‐
235           ative)  line  of  sights.  The  code is a decimal representation of
236           8-tuple minimalised patterns written in binary system. Full list of
237           patterns is available in source code directory as patterns.txt.
238
239       coordinates
240           The  central  point  of a single geomorphon to profile. The central
241           point must be within the  computational  region,  which  should  be
242           large  enough  to accommodate the search radius. Setting the region
243           larger than that will not produce more accurate data,  but  in  the
244           current implementation will slow the computation down. For the best
245           results remember to align the region to the raster cells. Profiling
246           is mutually exclusive with any raster outputs, but other parameters
247           and flags (such as elevation, search, comparison, -m and  -e)  work
248           as usual.
249
250       profiledata
251           The  output  file  name for the complete profile data, "-" means to
252           write to the standard output. The data  is  in  a  machine-readable
253           format  and  it includes assorted values describing the computation
254           context and parameters, as well as its intermediate and  final  re‐
255           sults.
256
257       profileformat
258           Format of the profile data: "json", "yaml" or "xml".
259
260       NOTE: parameters below are experimental. The usefulness of these param‐
261       eters are currently under investigation.
262
263       intensity
264           returns avarage difference between central cell of  geomorphon  and
265           eight cells in visibility neighbourhood. This parameter shows local
266           (as is visible) exposition/abasement of the form in the terrain.
267
268       range
269           returns difference between minimum and maximum values of visibility
270           neighbourhood.
271
272       variance
273           returns  variance  (difference  between  particular values and mean
274           value) of visibility neighbourhood.
275
276       extend
277           returns  area  of  the  polygon  created  by  the  8  points  where
278           line-of-sight cuts the terrain (see image in description section).
279
280       azimuth
281           returns  orientation  of  the polygon constituting geomorphon. This
282           orientation is currently  calculated  as  a  orientation  of  least
283           square fit line to the eight verticles of this polygon.
284
285       elongation
286           returns proportion between sides of the bounding box rectangle cal‐
287           culated for geomorphon rotated to fit least square line.
288
289       width
290           returns length of the shorter side of the  bounding  box  rectangle
291           calculated for geomorphon rotated to fit least square line.
292

NOTES

294       From  computational point of view there are no limitations of input DEM
295       and free parameters used in calculation. However, in practice there are
296       some issues on DEM resolution and search radius. Low resolution DEM es‐
297       pecially above 1 km per cell requires  smaller  than  default  flatness
298       threshold. On the other hand, only forms with high local elevation dif‐
299       ference will be detected correctly. It results from fact that  on  very
300       high  distance  (of order of kilometers or higher) even relatively high
301       elevation difference will be recognized as flat.  For  example  at  the
302       distance  of 8 km (8 cells with 1 km resolution DEM) an relative eleva‐
303       tion difference of at  least  136  m  is  required  to  be  noticed  as
304       non-flat.  Flatness  distance  threshold  may  be helpful to avoid this
305       problem.
306

EXAMPLES

308   Geomorphon calculation: extraction of terrestrial landforms
309       Geomorphon calculation example using the EU DEM 25m:
310       g.region raster=eu_dem_25m -p
311       r.geomorphon elevation=eu_dem_25m forms=eu_dem_25m_geomorph
312       # verify terrestrial landforms found in DEM
313       r.category eu_dem_25m_geomorph
314        1  flat
315        2  peak
316        3  ridge
317        4  shoulder
318        5  spur
319        6  slope
320        7  hollow
321        8  footslope
322        9  valley
323        10 pit
324
325   Extraction of peaks
326       Using the resulting terrestrial landforms map, single landforms can  be
327       extracted, e.g. the peaks, and converted into a vector point map:
328       r.mapcalc expression="eu_dem_25m_peaks = if(eu_dem_25m_geomorph == 2, 1, null())"
329       r.thin input=eu_dem_25m_peaks output=eu_dem_25m_peaks_thinned
330       r.to.vect input=eu_dem_25m_peaks_thinned output=eu_dem_25m_peaks type=point
331       v.info input=eu_dem_25m_peaks
332

REFERENCES

334           •   Stepinski,  T.,  Jasiewicz,  J.,  2011, Geomorphons - a new ap‐
335               proach to classification of landform, in  :   Eds:  Hengl,  T.,
336               Evans,  I.S.,  Wilson, J.P., and Gould, M., Proceedings of Geo‐
337               morphometry 2011,  Redlands, 109-112 (PDF)
338
339           •   Jasiewicz, J., Stepinski, T.,  2013, Geomorphons  -  a  pattern
340               recognition  approach  to  classification  and mapping of land‐
341               forms, Geomorphology, vol. 182,  147-156  (DOI:  10.1016/j.geo‐
342               morph.2012.11.005)
343

SEE ALSO

345        r.param.scale
346

AUTHORS

348       Jarek Jasiewicz, Tomek Stepinski (merit contribution)
349

SOURCE CODE

351       Available at: r.geomorphon source code (history)
352
353       Accessed: Saturday Jan 21 21:14:38 2023
354
355       Main  index  | Raster index | Topics index | Keywords index | Graphical
356       index | Full index
357
358       © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
359
360
361
362GRASS 8.2.1                                                    r.geomorphon(1)
Impressum