Analytical Hillshading

Author(s)	O.Conrad, V.Wichmann (c) 2003-2025
Library ID	ta_lighting
Tool ID	0
Version	1.0
Menu	Terrain Analysis \| Lighting and Visibility

Description

This tool performs an analytical hillshade computation for an elevation grid. The 'Standard' method simply calculates the angle at which light coming from the position of the light source would hit the surface. This method can produce angles greater than 90 degree. With the second method all values are kept within the range of 0-90 degree. It can be enhanced with shadowing effects, where shadowed cells will be marked with a value of exactly 90 degree. 'Shadows Only' creates a mask for the shadowed areas and sets all other cells to no-data. 'Combined Shading' takes the values of the standard method and multiplies these with the normalized slope. 'Ambient Occlusion' is based on the concepts of Tarini et al. (2006). 'Multidirectional' combines standard shadings computed for six different lighting directions to show more detail. The 'Multidirectional (USGS)' method combines four aspect weighted lighting directions.

References

Mark, R. (1992): Multidirectional, oblique-weighted, shaded-relief image of the Island of Hawaii. U.S. Geological Survey, Open-File Report 92-422. PDF

Tarini, M., Cignoni, P., Montani, C. (2006): Ambient Occlusion and Edge Cueing to Enhance Real Time Molecular Visualization. IEEE Transactions on Visualization and Computer Graphics, Vol. 12, No. 5, pp. 1237-1244. doi:10.1109/tvcg.2006.115

Parameters

	Name	Type	Identifier	Description	Constraints
Input	Elevation	grid, input	`ELEVATION`	-	-
Output	Analytical Hillshading	grid, output	`SHADE`	The angle between the surface and the incoming light beams, measured in radians.	-
Options	Grid System	grid system	`PARAMETERS_GRID_SYSTEM`	-	-
	Shading Method	choice	`METHOD`	-	Available Choices: [0] Standard [1] Limited Maximum [2] With Shadows [3] Shadows Only [4] Ambient Occlusion [5] Combined Shading [6] Multidirectional [7] Multidirectional (USGS) Default: 0
	Sun's Position	choice	`POSITION`	-	Available Choices: [0] azimuth and height [1] date and time Default: 0
	Azimuth	floating point number	`AZIMUTH`	Direction of the light source, measured in degree clockwise from the North direction.	Minimum: 0.000000 Maximum: 360.000000 Default: 315.000000
	Height	floating point number	`DECLINATION`	Height of the light source, measured in degree above the horizon.	Minimum: 0.000000 Maximum: 90.000000 Default: 45.000000
	Day	date	`DATE`	-	Default: 2026-06-03
	Hour	floating point number	`TIME`	-	Minimum: 0.000000 Maximum: 24.000000 Default: 12.000000
	Exaggeration	floating point number	`EXAGGERATION`	The terrain exaggeration factor allows one to increase the shading contrasts in flat areas.	Default: 1.000000
	Unit	choice	`UNIT`	-	Available Choices: [0] radians [1] degree Default: 0
	Shadow	choice	`SHADOW`	Choose 'slim' to trace grid node's shadow, 'fat' to trace the whole cell's shadow. The first is slightly faster but might show some artifacts.	Available Choices: [0] slim [1] fat Default: 1
	Sampling Hemisphere	choice	`SAMPLING`	Choose which hemisphere of the ambient-occlusion sampling sphere is used.	Available Choices: [0] north [1] south [2] full Default: 0
	Number of Directions	integer number	`NDIRS`	Number of sample directions for ambient occlusion. Divides azimuth range of hemisphere into sectors. Declination (0 to 90 degree) is divided in (Number of Directions / 4) sectors.	Minimum: 2 Default: 8
	Search Radius	floating point number	`RADIUS`	Radius used to trace for shadows (ambient occlusion) [map units].	Minimum: 0.001000 Default: 10.000000
	Radius Smoothing	integer number	`KERNEL_RADIUS`	The kernel radius used for DEM smoothing [cells].	Minimum: 0 Default: 3

Command Line


Usage: saga_cmd ta_lighting 0 [-ELEVATION ] [-SHADE ] [-METHOD ] [-POSITION ] [-AZIMUTH ] [-DECLINATION ] [-DATE ] [-TIME ] [-EXAGGERATION ] [-UNIT ] [-SHADOW ] [-SAMPLING ] [-NDIRS ] [-RADIUS ] [-KERNEL_RADIUS ]
  -ELEVATION:         Elevation
	grid, input
  -SHADE:             Analytical Hillshading
	grid, output
  -METHOD:
                           Shading Method
                           	choice
                           	Available Choices:
                           	[0] Standard
                           	[1] Limited Maximum
                           	[2] With Shadows
                           	[3] Shadows Only
                           	[4] Ambient Occlusion
                           	[5] Combined Shading
                           	[6] Multidirectional
                           	[7] Multidirectional (USGS)
                           	Default: 0
  -POSITION:
                           Sun's Position
                           	choice
                           	Available Choices:
                           	[0] azimuth and height
                           	[1] date and time
                           	Default: 0
  -AZIMUTH:        Azimuth
	floating point number
	Minimum: 0.000000
	Maximum: 360.000000
	Default: 315.000000
  -DECLINATION:    Height
	floating point number
	Minimum: 0.000000
	Maximum: 90.000000
	Default: 45.000000
  -DATE:             Day
	date
	Default: 2026-06-03
  -TIME:           Hour
	floating point number
	Minimum: 0.000000
	Maximum: 24.000000
	Default: 12.000000
  -EXAGGERATION:   Exaggeration
	floating point number
	Default: 1.000000
  -UNIT:              Unit
	choice
	Available Choices:
	[0] radians
	[1] degree
	Default: 0
  -SHADOW:            Shadow
	choice
	Available Choices:
	[0] slim
	[1] fat
	Default: 1
  -SAMPLING:          Sampling Hemisphere
	choice
	Available Choices:
	[0] north
	[1] south
	[2] full
	Default: 0
  -NDIRS:             Number of Directions
	integer number
	Minimum: 2
	Default: 8
  -RADIUS:         Search Radius
	floating point number
	Minimum: 0.001000
	Default: 10.000000
  -KERNEL_RADIUS:     Radius Smoothing
	integer number
	Minimum: 0
	Default: 3