1GDALDEM(1)                           GDAL                           GDALDEM(1)
2
3
4

NAME

6       gdaldem - Tools to analyze and visualize DEMs.
7

SYNOPSIS

9          gdaldem <mode> <input> <output> <options>
10
11       Generate a shaded relief map from any GDAL-supported elevation raster:
12
13          gdaldem hillshade input_dem output_hillshade
14                      [-z ZFactor (default=1)] [-s scale* (default=1)]
15                      [-az Azimuth (default=315)] [-alt Altitude (default=45)]
16                      [-alg Horn|ZevenbergenThorne] [-combined | -multidirectional | -igor]
17                      [-compute_edges] [-b Band (default=1)] [-of format] [-co "NAME=VALUE"]* [-q]
18
19       Generate a slope map from any GDAL-supported elevation raster:
20
21          gdaldem slope input_dem output_slope_map
22                      [-p use percent slope (default=degrees)] [-s scale* (default=1)]
23                      [-alg Horn|ZevenbergenThorne]
24                      [-compute_edges] [-b Band (default=1)] [-of format] [-co "NAME=VALUE"]* [-q]
25
26       Generate  an  aspect map from any GDAL-supported elevation raster, out‐
27       puts a 32-bit float raster with pixel values from 0-360 indicating  az‐
28       imuth:
29
30          gdaldem aspect input_dem output_aspect_map
31                      [-trigonometric] [-zero_for_flat]
32                      [-alg Horn|ZevenbergenThorne]
33                      [-compute_edges] [-b Band (default=1)] [-of format] [-co "NAME=VALUE"]* [-q]
34
35       Generate a color relief map from any GDAL-supported elevation raster:
36
37          gdaldem color-relief input_dem color_text_file output_color_relief_map
38                      [-alpha] [-exact_color_entry | -nearest_color_entry]
39                      [-b Band (default=1)] [-of format] [-co "NAME=VALUE"]* [-q]
40          where color_text_file contains lines of the format "elevation_value red green blue"
41
42       Generate  a  Terrain Ruggedness Index (TRI) map from any GDAL-supported
43       elevation raster:
44
45          gdaldem TRI input_dem output_TRI_map
46                      [-alg Wilson|Riley]
47                      [-compute_edges] [-b Band (default=1)] [-of format] [-q]
48
49       Generate a Topographic Position Index (TPI) map from any GDAL-supported
50       elevation raster:
51
52          gdaldem TPI input_dem output_TPI_map
53                      [-compute_edges] [-b Band (default=1)] [-of format] [-q]
54
55       Generate a roughness map from any GDAL-supported elevation raster:
56
57          gdaldem roughness input_dem output_roughness_map
58                      [-compute_edges] [-b Band (default=1)] [-of format] [-q]
59

DESCRIPTION

61       The  gdaldem generally assumes that x, y and z units are identical.  If
62       x (east-west) and y (north-south) units are identical,  but  z  (eleva‐
63       tion) units are different, the scale (-s) option can be used to set the
64       ratio of vertical units to horizontal.  For  LatLong  projections  near
65       the  equator,  where units of latitude and units of longitude are simi‐
66       lar, elevation (z) units can be converted to  be  compatible  by  using
67       scale=370400 (if elevation is in feet) or scale=111120 (if elevation is
68       in meters).  For locations not near the equator, it would  be  best  to
69       reproject your grid using gdalwarp before using gdaldem.
70
71       <mode> Where <mode> is one of the seven available modes:
72
73hillshade
74                   Generate a shaded relief map from any GDAL-supported eleva‐
75                   tion raster.
76
77slope
78                   Generate a slope  map  from  any  GDAL-supported  elevation
79                   raster.
80
81aspect
82                   Generate  an  aspect  map from any GDAL-supported elevation
83                   raster.
84
85color-relief
86                   Generate a color relief map from any GDAL-supported  eleva‐
87                   tion raster.
88
89TRI
90                   Generate  a  map  of  Terrain  Ruggedness  Index  from  any
91                   GDAL-supported elevation raster.
92
93TPI
94                   Generate a map  of  Topographic  Position  Index  from  any
95                   GDAL-supported elevation raster.
96
97roughness
98                   Generate  a map of roughness from any GDAL-supported eleva‐
99                   tion raster.
100
101       The following general options are available:
102
103       input_dem
104              The input DEM raster to be processed
105
106       output_xxx_map
107              The output raster produced
108
109       -of <format>
110              Select the output format.
111
112              New in version 2.3.0: If not specified, the  format  is  guessed
113              from  the  extension  (previously was GTiff -- GeoTIFF File For‐
114              mat). Use the short format name.
115
116
117       -compute_edges
118              Do the computation at raster edges and near nodata values
119
120       -b <band>
121              Select an input band to be processed. Bands are numbered from 1.
122
123       -co <NAME=VALUE>
124              Many formats have one or more optional creation options that can
125              be  used  to control particulars about the file created. For in‐
126              stance, the GeoTIFF driver supports creation options to  control
127              compression, and whether the file should be tiled.
128
129              The  creation  options available vary by format driver, and some
130              simple formats have no creation options at all. A  list  of  op‐
131              tions  supported  for  a format can be listed with the --formats
132              command line option but the documentation for the format is  the
133              definitive  source  of  information  on driver creation options.
134              See Raster drivers format specific documentation for legal  cre‐
135              ation options for each format.
136
137       -q     Suppress progress monitor and other non-error output.
138
139       For  all  algorithms, except color-relief, a nodata value in the target
140       dataset will be emitted if at least one pixel set to the  nodata  value
141       is  found in the 3x3 window centered around each source pixel. The con‐
142       sequence is that there will be a 1-pixel border around each  image  set
143       with nodata value.
144          If -compute_edges is specified, gdaldem will compute values at image
145          edges or if a nodata value is found in the 3x3 window,  by  interpo‐
146          lating missing values.
147

MODES

149   hillshade
150       This  command outputs an 8-bit raster with a nice shaded relief effect.
151       It’s very useful for visualizing the terrain. You can optionally  spec‐
152       ify  the azimuth and altitude of the light source, a vertical exaggera‐
153       tion factor and a scaling factor to  account  for  differences  between
154       vertical and horizontal units.
155
156       The value 0 is used as the output nodata value.
157
158       The following specific options are available :
159
160       -alg Horn|ZevenbergenThorne
161              The  literature  suggests Zevenbergen & Thorne to be more suited
162              to smooth landscapes, whereas Horn's formula to  perform  better
163              on rougher terrain.
164
165       -z <factor>
166              Vertical exaggeration used to pre-multiply the elevations
167
168       -s <scale>
169              Ratio of vertical units to horizontal. If the horizontal unit of
170              the source DEM is degrees (e.g Lat/Long WGS84  projection),  you
171              can  use  scale=111120  if  the  vertical  units  are meters (or
172              scale=370400 if they are in feet)
173
174       -az <azimuth>
175              Azimuth of the light, in degrees. 0 if it comes from the top  of
176              the raster, 90 from the east, ... The default value, 315, should
177              rarely be changed as it is the value generally used to  generate
178              shaded maps.
179
180       -alt <altitude>
181              Altitude  of  the  light, in degrees. 90 if the light comes from
182              above the DEM, 0 if it is raking light.
183
184       -combined
185              combined shading, a combination of slope and oblique shading.
186
187       -multidirectional
188              multidirectional shading, a combination of  hillshading  illumi‐
189              nated from 225 deg, 270 deg, 315 deg, and 360 deg azimuth.
190
191              New in version 2.2.
192
193
194       -igor  shading  which  tries  to minimize effects on other map features
195              beneath. Can't be used with -alt option.
196
197              New in version 3.0.
198
199
200       Multidirectional     hillshading     applies     the     formula     of
201       http://pubs.usgs.gov/of/1992/of92-422/of92-422.pdf.
202
203       Igor's      hillshading      uses      formula      from     Maperitive
204       http://maperitive.net/docs/Commands/GenerateReliefImageIgor.html.
205
206   slope
207       This command will take a DEM raster and output a  32-bit  float  raster
208       with  slope values. You have the option of specifying the type of slope
209       value you want: degrees or percent slope. In cases where the horizontal
210       units  differ  from  the  vertical units, you can also supply a scaling
211       factor.
212
213       The value -9999 is used as the output nodata value.
214
215       The following specific options are available :
216
217       -alg Horn|ZevenbergenThorne
218              The literature suggests Zevenbergen & Thorne to be  more  suited
219              to  smooth  landscapes, whereas Horn's formula to perform better
220              on rougher terrain.
221
222       -p     If specified, the slope will be expressed as percent slope. Oth‐
223              erwise, it is expressed as degrees
224
225       -s
226          Ratio of vertical units to horizontal. If the horizontal unit of the
227          source DEM is degrees (e.g Lat/Long WGS84 projection), you  can  use
228          scale=111120  if  the  vertical units are meters (or scale=370400 if
229          they are in feet).
230
231   aspect
232       This command outputs a 32-bit float raster with values between  0°  and
233       360° representing the azimuth that slopes are facing. The definition of
234       the azimuth is such that : 0° means that the slope is facing the North,
235       90° it's facing the East, 180° it's facing the South and 270° it's fac‐
236       ing the West (provided that the top of your input raster is north  ori‐
237       ented).  The aspect value -9999 is used as the nodata value to indicate
238       undefined aspect in flat areas with slope=0.
239
240       The following specifics options are available :
241
242       -alg Horn|ZevenbergenThorne
243              The literature suggests Zevenbergen & Thorne to be  more  suited
244              to  smooth  landscapes, whereas Horn's formula to perform better
245              on rougher terrain.
246
247       -trigonometric
248              Return trigonometric angle instead of  azimuth.  Thus  0°  means
249              East, 90° North, 180° West, 270° South.
250
251       -zero_for_flat
252              Return 0 for flat areas with slope=0, instead of -9999.
253
254       By  using those 2 options, the aspect returned by gdaldem aspect should
255       be identical to the one of GRASS r.slope.aspect. Otherwise, it's  iden‐
256       tical to the one of Matthew Perry's aspect.cpp utility.
257
258   color-relief
259       This command outputs a 3-band (RGB) or 4-band (RGBA) raster with values
260       are computed from the elevation and a  text-based  color  configuration
261       file,  containing  the association between various elevation values and
262       the corresponding wished color. By  default,  the  colors  between  the
263       given  elevation  values  are blended smoothly and the result is a nice
264       colorized DEM. The -exact_color_entry or  -nearest_color_entry  options
265       can  be  used  to avoid that linear interpolation for values that don't
266       match an index of the color configuration file.
267
268       The following specifics options are available :
269
270       color_text_file
271              Text-based color configuration file
272
273       -alpha Add an alpha channel to the output raster
274
275       -exact_color_entry
276              Use strict matching when searching in  the  color  configuration
277              file.  If none matching color entry is found, the "0,0,0,0" RGBA
278              quadruplet will be used
279
280       -nearest_color_entry
281              Use the RGBA quadruplet corresponding to the  closest  entry  in
282              the color configuration file.
283
284       The color-relief mode is the only mode that supports VRT as output for‐
285       mat.  In that case, it will translate the color configuration file into
286       appropriate  LUT elements. Note that elevations specified as percentage
287       will be translated as absolute values, which must be taken into account
288       when  the  statistics of the source raster differ from the one that was
289       used when building the VRT.
290
291       The text-based color configuration file generally  contains  4  columns
292       per  line:  the  elevation value and the corresponding Red, Green, Blue
293       component (between 0 and 255). The elevation value can be any  floating
294       point value, or the nv keyword for the nodata value.  The elevation can
295       also be expressed as a percentage: 0% being the minimum value found  in
296       the raster, 100% the maximum value.
297
298       An extra column can be optionally added for the alpha component.  If it
299       is not specified, full opacity (255) is assumed.
300
301       Various field separators are accepted: comma, tabulation, spaces, ':'.
302
303       Common colors used by GRASS can also be specified by using their  name,
304       instead  of  the RGB triplet. The supported list is: white, black, red,
305       green, blue, yellow, magenta, cyan,  aqua,  grey/gray,  orange,  brown,
306       purple/violet and indigo.
307          GMT .cpt palette files are also supported (COLOR_MODEL = RGB only).
308
309       Note:  the  syntax  of the color configuration file is derived from the
310       one supported by GRASS r.colors utility. ESRI  HDR  color  table  files
311       (.clr)  also  match that syntax. The alpha component and the support of
312       tab and comma as separators are GDAL specific extensions.
313
314       For example:
315
316          3500   white
317          2500   235:220:175
318          50%   190 185 135
319          700    240 250 150
320          0      50  180  50
321          nv     0   0   0   0
322
323       To implement a "round to the floor value" mode, the elevation value can
324       be  duplicate with a new value being slightly above the threshold.  For
325       example to have red in [0,10], green in ]10,20] and blue in ]20,30]:
326
327          0       red
328          10      red
329          10.001  green
330          20      green
331          20.001  blue
332          30      blue
333
334   TRI
335       This command outputs a single-band raster with values computed from the
336       elevation.  TRI stands for Terrain Ruggedness Index, which measures the
337       difference between a central pixel and its surrounding cells.
338
339       The value -9999 is used as the output nodata value.
340
341       The following option is available:
342
343       -alg Wilson|Riley
344              Starting with GDAL 3.3, the Riley algorithm (see Riley, S.J., De
345              Gloria, S.D., Elliot, R. (1999): A Terrain Ruggedness that Quan‐
346              tifies Topographic Heterogeneity.  Intermountain Journal of Sci‐
347              ence,  Vol.5, No.1-4, pp.23-27) is available and the new default
348              value. This algorithm uses the square root of  the  sum  of  the
349              square  of  the  difference between a central pixel and its sur‐
350              rounding cells. This is recommended for terrestrial use cases.
351
352              The Wilson (see Wilson et al 2007, Marine Geodesy 30:3-35) algo‐
353              rithm  uses  the mean difference between a central pixel and its
354              surrounding cells.  This  is  recommended  for  bathymetric  use
355              cases.
356
357   TPI
358       This command outputs a single-band raster with values computed from the
359       elevation.  TPI stands for Topographic Position Index, which is defined
360       as the difference between a central pixel and the mean of its surround‐
361       ing cells (see Wilson et al 2007, Marine Geodesy 30:3-35).
362
363       The value -9999 is used as the output nodata value.
364
365       There are no specific options.
366
367   roughness
368       This command outputs a single-band raster with values computed from the
369       elevation.  Roughness is the largest inter-cell difference of a central
370       pixel and its surrounding cell, as defined in Wilson et al  (2007,  Ma‐
371       rine Geodesy 30:3-35).
372
373       The value -9999 is used as the output nodata value.
374
375       There are no specific options.
376

C API

378       This utility is also callable from C with GDALDEMProcessing().
379
380       New in version 2.1.
381
382

AUTHORS

384       Matthew        Perry       perrygeo@gmail.com,       Even       Rouault
385       even.rouault@spatialys.com,  Howard  Butler  hobu.inc@gmail.com,  Chris
386       Yesson chris.yesson@ioz.ac.uk
387
388       Derived  from  code by Michael Shapiro, Olga Waupotitsch, Marjorie Lar‐
389       son, Jim Westervelt: U.S. Army CERL, 1993. GRASS 4.1 Reference  Manual.
390       U.S. Army Corps of Engineers, Construction Engineering Research Labora‐
391       tories, Champaign, Illinois, 1-425.
392

SEE ALSO

394       Documentation of related GRASS utilities:
395
396       https://grass.osgeo.org/grass79/manuals/r.slope.aspect.html
397
398       https://grass.osgeo.org/grass79/manuals/r.relief.html
399
400       https://grass.osgeo.org/grass79/manuals/r.colors.html
401

AUTHOR

403       Matthew Perry  <perrygeo@gmail.com>,  Even  Rouault  <even.rouault@spa‐
404       tialys.com>,   Howard   Butler   <hobu.inc@gmail.com>,   Chris   Yesson
405       <chris.yesson@ioz.ac.uk>
406
408       1998-2023
409
410
411
412
413                                 Apr 17, 2023                       GDALDEM(1)
Impressum