1gdaldem(1)                  General Commands Manual                 gdaldem(1)
2
3
4

NAME

6       gdaldemTools to analyze and visualize DEMs.
7

SYNOPSIS

9       - To generate a shaded relief map from any GDAL-supported elevation raster :
10           gdaldem hillshade input_dem output_hillshade
11                       [-z ZFactor (default=1)] [-s scale* (default=1)]"
12                       [-az Azimuth (default=315)] [-alt Altitude (default=45)]
13                       [-alg ZevenbergenThorne] [-combined | -multidirectional]
14                       [-compute_edges] [-b Band (default=1)] [-of format] [-co "NAME=VALUE"]* [-q]
15
16       - To generate a slope map from any GDAL-supported elevation raster :
17           gdaldem slope input_dem output_slope_map"
18                       [-p use percent slope (default=degrees)] [-s scale* (default=1)]
19                       [-alg ZevenbergenThorne]
20                       [-compute_edges] [-b Band (default=1)] [-of format] [-co "NAME=VALUE"]* [-q]
21
22       - To generate an aspect map from any GDAL-supported elevation raster
23         Outputs a 32-bit float raster with pixel values from 0-360 indicating azimuth :
24           gdaldem aspect input_dem output_aspect_map"
25                       [-trigonometric] [-zero_for_flat]
26                       [-alg ZevenbergenThorne]
27                       [-compute_edges] [-b Band (default=1)] [-of format] [-co "NAME=VALUE"]* [-q]
28
29       - To generate a color relief map from any GDAL-supported elevation raster
30           gdaldem color-relief input_dem color_text_file output_color_relief_map
31                       [-alpha] [-exact_color_entry | -nearest_color_entry]
32                       [-b Band (default=1)] [-of format] [-co "NAME=VALUE"]* [-q]
33           where color_text_file contains lines of the format "elevation_value red green blue"
34
35       - To generate a Terrain Ruggedness Index (TRI) map from any GDAL-supported elevation raster:
36           gdaldem TRI input_dem output_TRI_map
37                       [-compute_edges] [-b Band (default=1)] [-of format] [-q]
38
39       - To generate a Topographic Position Index (TPI) map from any GDAL-supported elevation raster:
40           gdaldem TPI input_dem output_TPI_map
41                       [-compute_edges] [-b Band (default=1)] [-of format] [-q]
42
43       - To generate a roughness map from any GDAL-supported elevation raster:
44           gdaldem roughness input_dem output_roughness_map
45                       [-compute_edges] [-b Band (default=1)] [-of format] [-q]
46
47       Notes :
48         gdaldem generally assumes that x, y and z units are identical.  If x (east-west)
49         and y (north-south) units are identical, but z (elevation) units are different, the
50         scale (-s) option can be used to set the ratio of vertical units to horizontal.  For
51         LatLong projections near the equator, where units of latitude and units of
52         longitude are similar, elevation (z) units can be converted to be compatible
53         by using scale=370400 (if elevation is in feet) or scale=111120 (if elevation is in
54         meters).  For locations not near the equator, it would be best to reproject your
55         grid using gdalwarp before using gdaldem..fi
56

DESCRIPTION

58       This utility has 7 different modes :
59
60       hillshade
61           to generate a shaded relief map from any GDAL-supported elevation
62           raster
63
64       slope
65           to generate a slope map from any GDAL-supported elevation raster
66
67       aspect
68           to generate an aspect map from any GDAL-supported elevation raster
69
70       color-relief
71           to generate a color relief map from any GDAL-supported elevation
72           raster
73
74       TRI
75           to generate a map of Terrain Ruggedness Index from any GDAL-
76           supported elevation raster
77
78       TPI
79           to generate a map of Topographic Position Index from any GDAL-
80           supported elevation raster
81
82       roughness
83           to generate a map of roughness from any GDAL-supported elevation
84           raster
85
86       The following general options are available :
87
88       input_dem:
89           The input DEM raster to be processed
90
91       output_xxx_map:
92           The output raster produced
93
94       -of format:
95           Select the output format. Starting with GDAL 2.3, if not specified,
96           the format is guessed from the extension (previously was GTiff).
97           Use the short format name.
98
99       -compute_edges:
100           (GDAL >= 1.8.0) Do the computation at raster edges and near nodata
101           values
102
103       -alg ZevenbergenThorne:
104           (GDAL >= 1.8.0) Use Zevenbergen & Thorne formula, instead of Horn's
105           formula, to compute slope & aspect. The literature suggests
106           Zevenbergen & Thorne to be more suited to smooth landscapes,
107           whereas Horn's formula to perform better on rougher terrain.
108
109       -b band:
110           Select an input band to be processed. Bands are numbered from 1.
111
112       -co 'NAME=VALUE':
113           Passes a creation option to the output format driver. Multiple -co
114           options may be listed. See format specific documentation for legal
115           creation options for each format
116
117       -q:
118           Suppress progress monitor and other non-error output.
119
120       For all algorithms, except color-relief, a nodata value in the target
121       dataset will be emitted if at least one pixel set to the nodata value
122       is found in the 3x3 window centered around each source pixel. The
123       consequence is that there will be a 1-pixel border around each image
124       set with nodata value. From GDAL 1.8.0, if -compute_edges is specified,
125       gdaldem will compute values at image edges or if a nodata value is
126       found in the 3x3 window, by interpolating missing values.
127

Modes

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

C API

314       Starting with GDAL 2.1, this utility is also callable from C with
315       GDALDEMProcessing().
316

AUTHORS

318       Matthew Perry perrygeo@gmail.com, Even Rouault even.rouault@mines-
319       paris.org, Howard Butler hobu.inc@gmail.com, Chris Yesson
320       chris.yesson@ioz.ac.uk
321
322       Derived from code by Michael Shapiro, Olga Waupotitsch, Marjorie
323       Larson, Jim Westervelt : U.S. Army CERL, 1993. GRASS 4.1 Reference
324       Manual. U.S. Army Corps of Engineers, Construction Engineering Research
325       Laboratories, Champaign, Illinois, 1-425.
326

See also

328       Documentation of related GRASS utilities :
329
330       http://grass.osgeo.org/grass64/manuals/html64_user/r.slope.aspect.html
331
332       http://grass.osgeo.org/grass64/manuals/html64_user/r.shaded.relief.html
333
334       http://grass.osgeo.org/grass64/manuals/html64_user/r.colors.html
335
336
337
338GDAL                            Thu Jul 25 2019                     gdaldem(1)
Impressum