NAME

gdal-raster-hillshade - Generate a shaded relief map

Added in version 3.11.

SYNOPSIS

Usage: gdal raster hillshade [OPTIONS] <INPUT> <OUTPUT>
Generate a shaded relief map
Positional arguments:


  -i, --input <INPUT>                                  Input raster dataset [required]


  -o, --output <OUTPUT>                                Output raster dataset [required]
Common Options:


  -h, --help                                           Display help message and exit


  --json-usage                                         Display usage as JSON document and exit


  --config <KEY>=<VALUE>                               Configuration option [may be repeated]


  --progress                                           Display progress bar
Options:


  -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format ("GDALG" allowed)


  --co, --creation-option <KEY>=<VALUE>                Creation option [may be repeated]


  --overwrite                                          Whether overwriting existing output is allowed


  -b, --band <BAND>                                    Input band (1-based index) (default: 1)


  -z, --zfactor <ZFACTOR>                              Vertical exaggeration used to pre-multiply the elevations


  --xscale <XSCALE>                                    Ratio of vertical units to horizontal X axis units


  --yscale <YSCALE>                                    Ratio of vertical units to horizontal Y axis units


  --azimuth <AZIMUTH>                                  Azimuth of the light, in degrees (default: 315)


  --altitude <ALTITUDE>                                Altitude of the light, in degrees (default: 45)


  --gradient-alg <GRADIENT-ALG>                        Algorithm used to compute terrain gradient. GRADIENT-ALG=Horn|ZevenbergenThorne (default: Horn)


  --variant <VARIANT>                                  Variant of the hillshading algorithm. VARIANT=regular|combined|multidirectional|Igor (default: regular)


  --no-edges                                           Do not try to interpolate values at dataset edges or close to nodata values
Advanced Options:


  --if, --input-format <INPUT-FORMAT>                  Input formats [may be repeated]


  --oo, --open-option <KEY>=<VALUE>                    Open options [may be repeated]

DESCRIPTION

gdal raster hillshade generates a shaded relief map, from any GDAL-supported elevation raster.

This subcommand is also available as a potential step of gdal raster pipeline

It generates an 8-bit raster with a nice shaded relief effect. It is very useful for visualizing the terrain. You can optionally specify the azimuth and altitude of the light source, a vertical exaggeration factor and scaling factors to account for differences between vertical and horizontal units.

The value 0 is used as the output nodata value. A nodata value in the target dataset will be emitted if at least one pixel set to the nodata value is found in the 3x3 window centered around each source pixel. By default, the algorithm will compute values at image edges or if a nodata value is found in the 3x3 window, by interpolating missing values, unless --no-edges is specified, in which case a 1-pixel border around the image will be set with the nodata value.

In general, it assumes that x, y and z units are identical. However, if none of --xscale and --yscale are specified, and the CRS is a geographic or projected CRS, it will automatically determine the appropriate ratio from the units of the CRS, as well as the potential value of the units of the raster band (as returned by GDALRasterBand::GetUnitsType(), if it is metre, foot international or US survey foot). Note that for geographic CRS, the result for source datasets at high latitudes may be incorrect, and prior reprojection to a polar projection might be needed using gdal raster reproject.

If x (east-west) and y (north-south) units are identical, but z (elevation) units are different, the --xscale and --yscale can be used to set the ratio of vertical units to horizontal. For geographic CRS near the equator, where units of latitude and units of longitude are similar, elevation (z) units can be converted to be compatible by using scale=370400 (if elevation is in feet) or scale=111120 (if elevation is in meters). For locations not near the equator, the --xscale value can be taken as the --yscale value multiplied by the cosine of the mean latitude of the raster.

GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET)

This program supports serializing the command line as a JSON file using the GDALG output format. The resulting file can then be opened as a raster dataset using the GDALG: GDAL Streamed Algorithm driver, and apply the specified pipeline in a on-the-fly / streamed way.

EXAMPLES

$ gdal raster hillshade --zfactor=30 n43.dt0 out.tif --overwrite

AUTHOR

Even Rouault <even.rouault@spatialys.com>

COPYRIGHT

1998-2025