1GDALDEM(1) GDAL GDALDEM(1)
2
6 gdaldem - Tools to analyze and visualize DEMs.
7
9 gdaldem <mode> <input> <output> <options>
10 Generate a shaded relief map from any GDAL-supported elevation raster:
12 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 Generate a slope map from any GDAL-supported elevation raster:
20 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 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 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 Generate a color relief map from any GDAL-supported elevation raster:
36 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 Generate a Terrain Ruggedness Index (TRI) map from any GDAL-supported
43 elevation raster:
44 gdaldem TRI input_dem output_TRI_map
46 [-alg Wilson|Riley]
47 [-compute_edges] [-b Band (default=1)] [-of format] [-q]
48 Generate a Topographic Position Index (TPI) map from any GDAL-supported
50 elevation raster:
51 gdaldem TPI input_dem output_TPI_map
53 [-compute_edges] [-b Band (default=1)] [-of format] [-q]
54 Generate a roughness map from any GDAL-supported elevation raster:
56 gdaldem roughness input_dem output_roughness_map
58 [-compute_edges] [-b Band (default=1)] [-of format] [-q]
59
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 <mode> Where <mode> is one of the seven available modes:
72 • hillshade
74 Generate a shaded relief map from any GDAL-supported eleva‐
75 tion raster
76 • slope
78 Generate a slope map from any GDAL-supported elevation
79 raster aspect to generate an aspect map from any GDAL-sup‐
80 ported elevation raster
81 • color-relief
83 Generate a color relief map from any GDAL-supported eleva‐
84 tion raster.
85 • TRI
87 Generate a map of Terrain Ruggedness Index from any
88 GDAL-supported elevation raster.
89 • TPI
91 Generate a map of Topographic Position Index from any
92 GDAL-supported elevation raster.
93 • roughness
95 Generate a map of roughness from any GDAL-supported eleva‐
96 tion raster.
97 The following general options are available:
99 input_dem
101 The input DEM raster to be processed
102 output_xxx_map
104 The output raster produced
105 -of <format>
107 Select the output format.
108 New in version 2.3.0: If not specified, the format is guessed
110 from the extension (previously was raster.gtiff). Use the short
111 format name.
112 -compute_edges
115 Do the computation at raster edges and near nodata values
116 -b <band>
118 Select an input band to be processed. Bands are numbered from 1.
119 -co <NAME=VALUE>
121 Many formats have one or more optional creation options that can
122 be used to control particulars about the file created. For in‐
123 stance, the GeoTIFF driver supports creation options to control
124 compression, and whether the file should be tiled.
125 The creation options available vary by format driver, and some
127 simple formats have no creation options at all. A list of op‐
128 tions supported for a format can be listed with the --formats
129 command line option but the documentation for the format is the
130 definitive source of information on driver creation options.
131 See raster_drivers format specific documentation for legal cre‐
132 ation options for each format.
133 -q Suppress progress monitor and other non-error output.
135 For all algorithms, except color-relief, a nodata value in the target
137 dataset will be emitted if at least one pixel set to the nodata value
138 is found in the 3x3 window centered around each source pixel. The con‐
139 sequence is that there will be a 1-pixel border around each image set
140 with nodata value.
141 If -compute_edges is specified, gdaldem will compute values at image
142 edges or if a nodata value is found in the 3x3 window, by interpo‐
143 lating missing values.
144
146 hillshade
147 This command outputs an 8-bit raster with a nice shaded relief effect.
148 It’s very useful for visualizing the terrain. You can optionally spec‐
149 ify the azimuth and altitude of the light source, a vertical exaggera‐
150 tion factor and a scaling factor to account for differences between
151 vertical and horizontal units.
152 The value 0 is used as the output nodata value.
154 The following specific options are available :
156 -alg Horn|ZevenbergenThorne
158 The literature suggests Zevenbergen & Thorne to be more suited
159 to smooth landscapes, whereas Horn's formula to perform better
160 on rougher terrain.
161 -z <factor>
163 Vertical exaggeration used to pre-multiply the elevations
164 -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 -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 -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 -combined
182 combined shading, a combination of slope and oblique shading.
183 -multidirectional
185 multidirectional shading, a combination of hillshading illumi‐
186 nated from 225 deg, 270 deg, 315 deg, and 360 deg azimuth.
187 New in version 2.2.
189 -igor shading which tries to minimize effects on other map features
192 beneath. Can't be used with -alt option.
193 New in version 3.0.
195 Multidirectional hillshading applies the formula of
198 http://pubs.usgs.gov/of/1992/of92-422/of92-422.pdf.
199 Igor's hillshading uses formula from Maperitive
201 http://maperitive.net/docs/Commands/GenerateReliefImageIgor.html.
202 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 The value -9999 is used as the output nodata value.
211 The following specific options are available :
213 -alg Horn|ZevenbergenThorne
215 The literature suggests Zevenbergen & Thorne to be more suited
216 to smooth landscapes, whereas Horn's formula to perform better
217 on rougher terrain.
218 -p If specified, the slope will be expressed as percent slope. Oth‐
220 erwise, it is expressed as degrees
221 -s
223 Ratio of vertical units to horizontal. If the horizontal unit of the
224 source DEM is degrees (e.g Lat/Long WGS84 projection), you can use
225 scale=111120 if the vertical units are meters (or scale=370400 if
226 they are in feet).
227 aspect
229 This command outputs a 32-bit float raster with values between 0° and
230 360° representing the azimuth that slopes are facing. The definition of
231 the azimuth is such that : 0° means that the slope is facing the North,
232 90° it's facing the East, 180° it's facing the South and 270° it's fac‐
233 ing the West (provided that the top of your input raster is north ori‐
234 ented). The aspect value -9999 is used as the nodata value to indicate
235 undefined aspect in flat areas with slope=0.
236 The following specifics options are available :
238 -alg Horn|ZevenbergenThorne
240 The literature suggests Zevenbergen & Thorne to be more suited
241 to smooth landscapes, whereas Horn's formula to perform better
242 on rougher terrain.
243 -trigonometric
245 Return trigonometric angle instead of azimuth. Thus 0° means
246 East, 90° North, 180° West, 270° South.
247 -zero_for_flat
249 Return 0 for flat areas with slope=0, instead of -9999.
250 By using those 2 options, the aspect returned by gdaldem aspect should
252 be identical to the one of GRASS r.slope.aspect. Otherwise, it's iden‐
253 tical to the one of Matthew Perry's aspect.cpp utility.
254 color-relief
256 This command outputs a 3-band (RGB) or 4-band (RGBA) raster with values
257 are computed from the elevation and a text-based color configuration
258 file, containing the association between various elevation values and
259 the corresponding wished color. By default, the colors between the
260 given elevation values are blended smoothly and the result is a nice
261 colorized DEM. The -exact_color_entry or -nearest_color_entry options
262 can be used to avoid that linear interpolation for values that don't
263 match an index of the color configuration file.
264 The following specifics options are available :
266 color_text_file
268 Text-based color configuration file
269 -alpha Add an alpha channel to the output raster
271 -exact_color_entry
273 Use strict matching when searching in the color configuration
274 file. If none matching color entry is found, the "0,0,0,0" RGBA
275 quadruplet will be used
276 -nearest_color_entry
278 Use the RGBA quadruplet corresponding to the closest entry in
279 the color configuration file.
280 The color-relief mode is the only mode that supports VRT as output for‐
282 mat. In that case, it will translate the color configuration file into
283 appropriate LUT elements. Note that elevations specified as percentage
284 will be translated as absolute values, which must be taken into account
285 when the statistics of the source raster differ from the one that was
286 used when building the VRT.
287 The text-based color configuration file generally contains 4 columns
289 per line: the elevation value and the corresponding Red, Green, Blue
290 component (between 0 and 255). The elevation value can be any floating
291 point value, or the nv keyword for the nodata value. The elevation can
292 also be expressed as a percentage: 0% being the minimum value found in
293 the raster, 100% the maximum value.
294 An extra column can be optionally added for the alpha component. If it
296 is not specified, full opacity (255) is assumed.
297 Various field separators are accepted: comma, tabulation, spaces, ':'.
299 Common colors used by GRASS can also be specified by using their name,
301 instead of the RGB triplet. The supported list is: white, black, red,
302 green, blue, yellow, magenta, cyan, aqua, grey/gray, orange, brown,
303 purple/violet and indigo.
304 GMT .cpt palette files are also supported (COLOR_MODEL = RGB only).
305 Note: the syntax of the color configuration file is derived from the
307 one supported by GRASS r.colors utility. ESRI HDR color table files
308 (.clr) also match that syntax. The alpha component and the support of
309 tab and comma as separators are GDAL specific extensions.
310 For example:
312 3500 white
314 2500 235:220:175
315 50% 190 185 135
316 700 240 250 150
317 0 50 180 50
318 nv 0 0 0 0
319 To implement a "round to the floor value" mode, the elevation value can
321 be duplicate with a new value being slightly above the threshold. For
322 example to have red in [0,10], green in ]10,20] and blue in ]20,30]:
323 0 red
325 10 red
326 10.001 green
327 20 green
328 20.001 blue
329 30 blue
330 TRI
332 This command outputs a single-band raster with values computed from the
333 elevation. TRI stands for Terrain Ruggedness Index, which measures the
334 difference between a central pixel and its surrounding cells.
335 The value -9999 is used as the output nodata value.
337 The following option is available:
339 -alg Wilson|Riley
341 Starting with GDAL 3.3, the Riley algorithm (see Riley, S.J., De
342 Gloria, S.D., Elliot, R. (1999): A Terrain Ruggedness that Quan‐
343 tifies Topographic Heterogeneity. Intermountain Journal of Sci‐
344 ence, Vol.5, No.1-4, pp.23-27) is available and the new default
345 value. This algorithm uses the square root of the sum of the
346 square of the difference between a central pixel and its sur‐
347 rounding cells. This is recommended for terrestrial use cases.
348 The Wilson (see Wilson et al 2007, Marine Geodesy 30:3-35) algo‐
350 rithm uses the mean difference between a central pixel and its
351 surrounding cells. This is recommended for bathymetric use
352 cases.
353 TPI
355 This command outputs a single-band raster with values computed from the
356 elevation. TPI stands for Topographic Position Index, which is defined
357 as the difference between a central pixel and the mean of its surround‐
358 ing cells (see Wilson et al 2007, Marine Geodesy 30:3-35).
359 The value -9999 is used as the output nodata value.
361 There are no specific options.
363 roughness
365 This command outputs a single-band raster with values computed from the
366 elevation. Roughness is the largest inter-cell difference of a central
367 pixel and its surrounding cell, as defined in Wilson et al (2007, Ma‐
368 rine Geodesy 30:3-35).
369 The value -9999 is used as the output nodata value.
371 There are no specific options.
373
375 This utility is also callable from C with GDALDEMProcessing().
376 New in version 2.1.
378
381 Matthew Perry perrygeo@gmail.com, Even Rouault
382 even.rouault@spatialys.com, Howard Butler hobu.inc@gmail.com, Chris
383 Yesson chris.yesson@ioz.ac.uk
384 Derived from code by Michael Shapiro, Olga Waupotitsch, Marjorie Lar‐
386 son, Jim Westervelt: U.S. Army CERL, 1993. GRASS 4.1 Reference Manual.
387 U.S. Army Corps of Engineers, Construction Engineering Research Labora‐
388 tories, Champaign, Illinois, 1-425.
389
391 Documentation of related GRASS utilities:
392 https://grass.osgeo.org/grass79/manuals/r.slope.aspect.html
394 https://grass.osgeo.org/grass79/manuals/r.relief.html
396 https://grass.osgeo.org/grass79/manuals/r.colors.html
398
400 Matthew Perry <perrygeo@gmail.com>, Even Rouault <even.rouault@spa‐
401 tialys.com>, Howard Butler <hobu.inc@gmail.com>, Chris Yesson
402 <chris.yesson@ioz.ac.uk>
403
405 1998-2021
406 Sep 07, 2021 GDALDEM(1)