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 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 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 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                      [-compute_edges] [-b Band (default=1)] [-of format] [-q]
47
48       Generate a Topographic Position Index (TPI) map from any GDAL-supported
49       elevation raster:
50
51          gdaldem TPI input_dem output_TPI_map
52                      [-compute_edges] [-b Band (default=1)] [-of format] [-q]
53
54       Generate a roughness map from any GDAL-supported elevation raster:
55
56          gdaldem roughness input_dem output_roughness_map
57                      [-compute_edges] [-b Band (default=1)] [-of format] [-q]
58

DESCRIPTION

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

MODES

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

C API

348       This utility is also callable from C with GDALDEMProcessing().
349
350       New in version 2.1.
351
352

AUTHORS

354       Matthew        Perry       perrygeo@gmail.com,       Even       Rouault
355       even.rouault@spatialys.com,  Howard  Butler  hobu.inc@gmail.com,  Chris
356       Yesson chris.yesson@ioz.ac.uk
357
358       Derived  from  code by Michael Shapiro, Olga Waupotitsch, Marjorie Lar‐
359       son, Jim Westervelt: U.S. Army CERL, 1993. GRASS 4.1 Reference  Manual.
360       U.S. Army Corps of Engineers, Construction Engineering Research Labora‐
361       tories, Champaign, Illinois, 1-425.
362

SEE ALSO

364       Documentation of related GRASS utilities:
365
366       http://grass.osgeo.org/grass64/manuals/html64_user/r.slope.aspect.html
367
368       http://grass.osgeo.org/grass64/manuals/html64_user/r.shaded.relief.html
369
370       http://grass.osgeo.org/grass64/manuals/html64_user/r.colors.html
371

AUTHOR

373       Matthew Perry  <perrygeo@gmail.com>,  Even  Rouault  <even.rouault@spa‐
374       tialys.com>,   Howard   Butler   <hobu.inc@gmail.com>,   Chris   Yesson
375       <chris.yesson@ioz.ac.uk>
376
378       1998-2021
379
380
381
382
383                                 Mar 24, 2021                       GDALDEM(1)
Impressum