1.. _gdaldem: 2 3================================================================================ 4gdaldem 5================================================================================ 6 7.. only:: html 8 9 Tools to analyze and visualize DEMs. 10 11.. Index:: gdaldem 12 13Synopsis 14-------- 15 16.. code-block:: 17 18 gdaldem <mode> <input> <output> <options> 19 20Generate a shaded relief map from any GDAL-supported elevation raster: 21 22.. code-block:: 23 24 gdaldem hillshade input_dem output_hillshade 25 [-z ZFactor (default=1)] [-s scale* (default=1)] 26 [-az Azimuth (default=315)] [-alt Altitude (default=45)] 27 [-alg Horn|ZevenbergenThorne] [-combined | -multidirectional | -igor] 28 [-compute_edges] [-b Band (default=1)] [-of format] [-co "NAME=VALUE"]* [-q] 29 30Generate a slope map from any GDAL-supported elevation raster: 31 32.. code-block:: 33 34 gdaldem slope input_dem output_slope_map 35 [-p use percent slope (default=degrees)] [-s scale* (default=1)] 36 [-alg Horn|ZevenbergenThorne] 37 [-compute_edges] [-b Band (default=1)] [-of format] [-co "NAME=VALUE"]* [-q] 38 39Generate an aspect map from any GDAL-supported elevation raster, 40outputs a 32-bit float raster with pixel values from 0-360 indicating azimuth: 41 42.. code-block:: 43 44 gdaldem aspect input_dem output_aspect_map 45 [-trigonometric] [-zero_for_flat] 46 [-alg Horn|ZevenbergenThorne] 47 [-compute_edges] [-b Band (default=1)] [-of format] [-co "NAME=VALUE"]* [-q] 48 49Generate a color relief map from any GDAL-supported elevation raster: 50 51.. code-block:: 52 53 gdaldem color-relief input_dem color_text_file output_color_relief_map 54 [-alpha] [-exact_color_entry | -nearest_color_entry] 55 [-b Band (default=1)] [-of format] [-co "NAME=VALUE"]* [-q] 56 where color_text_file contains lines of the format "elevation_value red green blue" 57 58Generate a Terrain Ruggedness Index (TRI) map from any GDAL-supported elevation raster: 59 60.. code-block:: 61 62 gdaldem TRI input_dem output_TRI_map 63 [-alg Wilson|Riley] 64 [-compute_edges] [-b Band (default=1)] [-of format] [-q] 65 66Generate a Topographic Position Index (TPI) map from any GDAL-supported elevation raster: 67 68.. code-block:: 69 70 gdaldem TPI input_dem output_TPI_map 71 [-compute_edges] [-b Band (default=1)] [-of format] [-q] 72 73Generate a roughness map from any GDAL-supported elevation raster: 74 75.. code-block:: 76 77 gdaldem roughness input_dem output_roughness_map 78 [-compute_edges] [-b Band (default=1)] [-of format] [-q] 79 80Description 81----------- 82 83The :program:`gdaldem` generally assumes that x, y and z units are identical. 84If x (east-west) and y (north-south) units are identical, but z (elevation) 85units are different, the scale (-s) option can be used to set the ratio of 86vertical units to horizontal. 87For LatLong projections near the equator, where units of latitude and units of 88longitude are similar, elevation (z) units can be converted to be compatible 89by using scale=370400 (if elevation is in feet) or scale=111120 (if elevation is in 90meters). For locations not near the equator, it would be best to reproject your 91grid using gdalwarp before using gdaldem. 92 93.. option:: <mode> 94 95 Where <mode> is one of the seven available modes: 96 97 * ``hillshade`` 98 99 Generate a shaded relief map from any GDAL-supported elevation raster 100 101 * ``slope`` 102 103 Generate a slope map from any GDAL-supported elevation raster aspect to 104 generate an aspect map from any GDAL-supported elevation raster 105 106 * ``color-relief`` 107 108 Generate a color relief map from any GDAL-supported elevation raster. 109 110 * ``TRI`` 111 112 Generate a map of Terrain Ruggedness Index from any GDAL-supported elevation raster. 113 114 * ``TPI`` 115 116 Generate a map of Topographic Position Index from any GDAL-supported elevation raster. 117 118 * ``roughness`` 119 120 Generate a map of roughness from any GDAL-supported elevation raster. 121 122The following general options are available: 123 124.. option:: input_dem 125 126 The input DEM raster to be processed 127 128.. option:: output_xxx_map 129 130 The output raster produced 131 132.. option:: -of <format> 133 134 Select the output format. 135 136 .. versionadded:: 2.3.0 137 138 If not specified, the format is guessed from the extension 139 (previously was :ref:`raster.gtiff`). Use the short format name. 140 141.. option:: -compute_edges 142 143 Do the computation at raster edges and near nodata values 144 145.. option:: -b <band> 146 147 Select an input band to be processed. Bands are numbered from 1. 148 149.. include:: options/co.rst 150 151.. option:: -q 152 153 Suppress progress monitor and other non-error output. 154 155For all algorithms, except color-relief, a nodata value in the target dataset 156will be emitted if at least one pixel set to the nodata value is found in the 1573x3 window centered around each source pixel. The consequence is that there 158will be a 1-pixel border around each image set with nodata value. 159 160 If :option:`-compute_edges` is specified, gdaldem will compute values 161 at image edges or if a nodata value is found in the 3x3 window, 162 by interpolating missing values. 163 164Modes 165----- 166 167hillshade 168^^^^^^^^^ 169 170This command outputs an 8-bit raster with a nice shaded relief effect. It’s very useful for visualizing the terrain. You can optionally specify the azimuth and altitude of the light source, a vertical exaggeration factor and a scaling factor to account for differences between vertical and horizontal units. 171 172The value 0 is used as the output nodata value. 173 174The following specific options are available : 175 176.. option:: -alg Horn|ZevenbergenThorne 177 178 The literature suggests Zevenbergen & Thorne to be more suited to smooth landscapes, whereas Horn's formula to perform better on rougher terrain. 179 180.. option:: -z <factor> 181 182 Vertical exaggeration used to pre-multiply the elevations 183 184.. option:: -s <scale> 185 186 Ratio of vertical units to horizontal. If the horizontal unit of the source DEM is degrees (e.g Lat/Long WGS84 projection), you can use scale=111120 if the vertical units are meters (or scale=370400 if they are in feet) 187 188.. option:: -az <azimuth> 189 190 Azimuth of the light, in degrees. 0 if it comes from the top of the raster, 90 from the east, ... The default value, 315, should rarely be changed as it is the value generally used to generate shaded maps. 191 192.. option:: -alt <altitude> 193 194 Altitude of the light, in degrees. 90 if the light comes from above the DEM, 0 if it is raking light. 195 196.. option:: -combined 197 198 combined shading, a combination of slope and oblique shading. 199 200.. option:: -multidirectional 201 202 multidirectional shading, a combination of hillshading illuminated from 225 deg, 270 deg, 315 deg, and 360 deg azimuth. 203 204 .. versionadded:: 2.2 205 206.. option:: -igor 207 208 shading which tries to minimize effects on other map features beneath. Can't be used with -alt option. 209 210 .. versionadded:: 3.0 211 212Multidirectional hillshading applies the formula of http://pubs.usgs.gov/of/1992/of92-422/of92-422.pdf. 213 214Igor's hillshading uses formula from Maperitive http://maperitive.net/docs/Commands/GenerateReliefImageIgor.html. 215 216slope 217^^^^^ 218 219This command will take a DEM raster and output a 32-bit float raster with slope values. You have the option of specifying the type of slope value you want: degrees or percent slope. In cases where the horizontal units differ from the vertical units, you can also supply a scaling factor. 220 221The value `-9999` is used as the output nodata value. 222 223The following specific options are available : 224 225.. option:: -alg Horn|ZevenbergenThorne 226 227 The literature suggests Zevenbergen & Thorne to be more suited to smooth landscapes, whereas Horn's formula to perform better on rougher terrain. 228 229.. option:: -p 230 231 If specified, the slope will be expressed as percent slope. Otherwise, it is expressed as degrees 232 233:option:`-s` 234 235 Ratio of vertical units to horizontal. If the horizontal unit of the source DEM is degrees (e.g Lat/Long WGS84 projection), you can use scale=111120 if the vertical units are meters (or scale=370400 if they are in feet). 236 237aspect 238^^^^^^ 239 240This command outputs a 32-bit float raster with values between 0° and 360° representing the azimuth that slopes are facing. The definition of the azimuth is such that : 0° means that the slope is facing the North, 90° it's facing the East, 180° it's facing the South and 270° it's facing the West (provided that the top of your input raster is north oriented). The aspect value -9999 is used as the nodata value to indicate undefined aspect in flat areas with slope=0. 241 242The following specifics options are available : 243 244.. option:: -alg Horn|ZevenbergenThorne 245 246 The literature suggests Zevenbergen & Thorne to be more suited to smooth landscapes, whereas Horn's formula to perform better on rougher terrain. 247 248.. option:: -trigonometric 249 250 Return trigonometric angle instead of azimuth. Thus 0° means East, 90° North, 180° West, 270° South. 251 252.. option:: -zero_for_flat 253 254 Return 0 for flat areas with slope=0, instead of -9999. 255 256By using those 2 options, the aspect returned by gdaldem aspect should be 257identical to the one of GRASS r.slope.aspect. Otherwise, it's identical to 258the one of Matthew Perry's :file:`aspect.cpp` utility. 259 260color-relief 261^^^^^^^^^^^^ 262 263This command outputs a 3-band (RGB) or 4-band (RGBA) raster with values are computed from the elevation and a text-based color configuration file, containing the association between various elevation values and the corresponding wished color. By default, the colors between the given elevation values are blended smoothly and the result is a nice colorized DEM. The -exact_color_entry or -nearest_color_entry options can be used to avoid that linear interpolation for values that don't match an index of the color configuration file. 264 265The following specifics options are available : 266 267.. option:: color_text_file 268 269 Text-based color configuration file 270 271.. option:: -alpha 272 273 Add an alpha channel to the output raster 274 275.. option:: -exact_color_entry 276 277 Use strict matching when searching in the color configuration file. 278 If none matching color entry is found, the "0,0,0,0" RGBA quadruplet will be used 279 280.. option:: -nearest_color_entry 281 282 Use the RGBA quadruplet corresponding to the closest entry in the color configuration file. 283 284The color-relief mode is the only mode that supports VRT as output format. 285In that case, it will translate the color configuration file into appropriate 286LUT elements. Note that elevations specified as percentage will be translated 287as absolute values, which must be taken into account when the statistics of 288the source raster differ from the one that was used when building the VRT. 289 290The text-based color configuration file generally contains 4 columns 291per line: the elevation value and the corresponding Red, Green, Blue 292component (between 0 and 255). The elevation value can be any floating 293point value, or the nv keyword for the nodata value. 294The elevation can also be expressed as a percentage: 0% being the minimum 295value found in the raster, 100% the maximum value. 296 297An extra column can be optionally added for the alpha component. 298If it is not specified, full opacity (255) is assumed. 299 300Various field separators are accepted: comma, tabulation, spaces, ':'. 301 302Common colors used by GRASS can also be specified by using their name, 303instead of the RGB triplet. The supported list is: white, black, red, 304green, blue, yellow, magenta, cyan, aqua, grey/gray, orange, brown, 305purple/violet and indigo. 306 307 GMT :file:`.cpt` palette files are also supported (COLOR_MODEL = RGB only). 308 309Note: the syntax of the color configuration file is derived from the one 310supported by GRASS r.colors utility. ESRI HDR color table files (.clr) 311also match that syntax. The alpha component and the support of tab and 312comma as separators are GDAL specific extensions. 313 314For example: 315 316:: 317 318 3500 white 319 2500 235:220:175 320 50% 190 185 135 321 700 240 250 150 322 0 50 180 50 323 nv 0 0 0 0 324 325 326To implement a "round to the floor value" mode, the elevation value can be 327duplicate with a new value being slightly above the threshold. 328For example to have red in [0,10], green in ]10,20] and blue in ]20,30]: 329 330:: 331 332 0 red 333 10 red 334 10.001 green 335 20 green 336 20.001 blue 337 30 blue 338 339TRI 340^^^ 341 342This command outputs a single-band raster with values computed from the elevation. 343`TRI` stands for Terrain Ruggedness Index, which measures the difference 344between a central pixel and its surrounding cells. 345 346The value -9999 is used as the output nodata value. 347 348The following option is available: 349 350.. option:: -alg Wilson|Riley 351 352 Starting with GDAL 3.3, the Riley algorithm (see Riley, S.J., 353 De Gloria, S.D., Elliot, R. (1999): A Terrain Ruggedness that Quantifies Topographic Heterogeneity. 354 Intermountain Journal of Science, Vol.5, No.1-4, pp.23-27) is available and 355 the new default value. This algorithm uses the 356 square root of the sum of the square of the difference between a central pixel 357 and its surrounding cells. This is recommended for terrestrial use cases. 358 359 The Wilson (see Wilson et al 2007, Marine Geodesy 30:3-35) algorithm 360 uses the mean difference between a central pixel and its surrounding cells. 361 This is recommended for bathymetric use cases. 362 363TPI 364^^^ 365 366This command outputs a single-band raster with values computed from the elevation. 367`TPI` stands for Topographic Position Index, which is defined as the difference 368between a central pixel and the mean of its surrounding cells (see Wilson et al 3692007, Marine Geodesy 30:3-35). 370 371The value -9999 is used as the output nodata value. 372 373There are no specific options. 374 375roughness 376^^^^^^^^^ 377 378This command outputs a single-band raster with values computed from the elevation. 379Roughness is the largest inter-cell difference of a central pixel and its surrounding 380cell, as defined in Wilson et al (2007, Marine Geodesy 30:3-35). 381 382The value -9999 is used as the output nodata value. 383 384There are no specific options. 385 386C API 387----- 388 389This utility is also callable from C with :cpp:func:`GDALDEMProcessing`. 390 391.. versionadded:: 2.1 392 393Authors 394------- 395 396Matthew Perry perrygeo@gmail.com, Even Rouault even.rouault@spatialys.com, 397Howard Butler hobu.inc@gmail.com, Chris Yesson chris.yesson@ioz.ac.uk 398 399Derived from code by Michael Shapiro, Olga Waupotitsch, Marjorie Larson, Jim Westervelt: 400U.S. Army CERL, 1993. GRASS 4.1 Reference Manual. U.S. Army Corps of Engineers, 401Construction Engineering Research Laboratories, Champaign, Illinois, 1-425. 402 403See also 404-------- 405 406Documentation of related GRASS utilities: 407 408https://grass.osgeo.org/grass79/manuals/r.slope.aspect.html 409 410https://grass.osgeo.org/grass79/manuals/r.relief.html 411 412https://grass.osgeo.org/grass79/manuals/r.colors.html 413