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.
80 • aspect
82 Generate an aspect map from any GDAL-supported elevation
83 raster.
84 • color-relief
86 Generate a color relief map from any GDAL-supported eleva‐
87 tion raster.
88 • TRI
90 Generate a map of Terrain Ruggedness Index from any
91 GDAL-supported elevation raster.
92 • TPI
94 Generate a map of Topographic Position Index from any
95 GDAL-supported elevation raster.
96 • roughness
98 Generate a map of roughness from any GDAL-supported eleva‐
99 tion raster.
100 The following general options are available:
102 input_dem
104 The input DEM raster to be processed
105 output_xxx_map
107 The output raster produced
108 -of <format>
110 Select the output format.
111 New in version 2.3.0: If not specified, the format is guessed
113 from the extension (previously was raster.gtiff). Use the short
114 format name.
115 -compute_edges
118 Do the computation at raster edges and near nodata values
119 -b <band>
121 Select an input band to be processed. Bands are numbered from 1.
122 -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 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 -q Suppress progress monitor and other non-error output.
138 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
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 The value 0 is used as the output nodata value.
157 The following specific options are available :
159 -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 -z <factor>
166 Vertical exaggeration used to pre-multiply the elevations
167 -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 -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 -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 -combined
185 combined shading, a combination of slope and oblique shading.
186 -multidirectional
188 multidirectional shading, a combination of hillshading illumi‐
189 nated from 225 deg, 270 deg, 315 deg, and 360 deg azimuth.
190 New in version 2.2.
192 -igor shading which tries to minimize effects on other map features
195 beneath. Can't be used with -alt option.
196 New in version 3.0.
198 Multidirectional hillshading applies the formula of
201 http://pubs.usgs.gov/of/1992/of92-422/of92-422.pdf.
202 Igor's hillshading uses formula from Maperitive
204 http://maperitive.net/docs/Commands/GenerateReliefImageIgor.html.
205 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 The value -9999 is used as the output nodata value.
214 The following specific options are available :
216 -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 -p If specified, the slope will be expressed as percent slope. Oth‐
223 erwise, it is expressed as degrees
224 -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 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 The following specifics options are available :
241 -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 -trigonometric
248 Return trigonometric angle instead of azimuth. Thus 0° means
249 East, 90° North, 180° West, 270° South.
250 -zero_for_flat
252 Return 0 for flat areas with slope=0, instead of -9999.
253 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 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 The following specifics options are available :
269 color_text_file
271 Text-based color configuration file
272 -alpha Add an alpha channel to the output raster
274 -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 -nearest_color_entry
281 Use the RGBA quadruplet corresponding to the closest entry in
282 the color configuration file.
283 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 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 An extra column can be optionally added for the alpha component. If it
299 is not specified, full opacity (255) is assumed.
300 Various field separators are accepted: comma, tabulation, spaces, ':'.
302 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 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 For example:
315 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 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 0 red
328 10 red
329 10.001 green
330 20 green
331 20.001 blue
332 30 blue
333 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 The value -9999 is used as the output nodata value.
340 The following option is available:
342 -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 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 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 The value -9999 is used as the output nodata value.
364 There are no specific options.
366 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 The value -9999 is used as the output nodata value.
374 There are no specific options.
376
378 This utility is also callable from C with GDALDEMProcessing().
379 New in version 2.1.
381
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 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
394 Documentation of related GRASS utilities:
395 https://grass.osgeo.org/grass79/manuals/r.slope.aspect.html
397 https://grass.osgeo.org/grass79/manuals/r.relief.html
399 https://grass.osgeo.org/grass79/manuals/r.colors.html
401
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-2022
409 May 04, 2022 GDALDEM(1)