Calculates the hillshade value for each cell of a raster surface and returns an array of hillshades.
Syntax
raster ST_Hillshade(raster rast, integer pyramid_level, integer band, Box extent, BoxType type, float8 zfactor, float8 azimuth, float8 altitude, cstring storageOption);Parameters
| Parameter | Type | Description |
|---|---|---|
rast | raster | The source raster object. |
pyramid_level | integer | The pyramid level of the raster. |
band | integer | The band index (sequence number) to use for the calculation. |
extent | Box | The area to analyze. Format: '((minX,minY),(maxX,maxY))'. |
type | BoxType | The coordinate system used to interpret extent. Valid values: Raster (pixel coordinates) or World (world coordinates). |
zfactor | float8 | The conversion factor that scales elevation units to match the horizontal coordinate units. Set this when your elevation data and horizontal coordinates use different units — for example, when x,y units are decimal degrees and z units are meters. Default value: 1. |
azimuth | float8 | The sun's azimuth angle, measured clockwise from north. Valid values: 0–360. Default value: 315 (northwest). |
altitude | float8 | The sun's altitude angle above the horizon. A value of 90 places it directly overhead. Valid values: 0–90. |
storageOption | cstring | The storage option for the output raster. For details, see ST_ClipToRast. |
Description
ST_Hillshade models the hypothetical illumination of a raster surface. It assigns a position to an imaginary light source, then computes the illumination value of each cell relative to its neighbors — capturing both the angle of the sun and the local slope and aspect of the terrain.
The output is a raster where each cell contains an integer from 0 to 255. 0 represents the darkest shade (no illumination); 255 represents the brightest shade (maximum illumination). Applying transparency to the hillshade layer enhances the visual quality of terrain analysis and 3D-style map rendering.
When the elevation units differ from the horizontal units (for example, meters vs. decimal degrees), set zfactor to convert them to a common scale.For a detailed explanation of the hillshade algorithm, see How Hillshade works.
Example
The following example calculates hillshade over a 5×5-pixel extent of a raster at pyramid level 0, band 0, using a z-factor of 4, sun azimuth of 180° (south), and sun altitude of 80°.
SELECT st_hillshade(rast, 0, 0, '(0,0), (5,5)', 'Raster', 4, 180, 80)
FROM t_surface
WHERE id = 1;