Calculates the hillshade value for each cell of a raster object's surface and returns the result as a raster.
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 | Required | Description |
|---|---|---|---|
rast | raster | Yes | The raster object. |
pyramid_level | integer | Yes | The pyramid level. |
band | integer | Yes | The band number. |
extent | Box | Yes | The area to analyze. Format: '((minX,minY),(maxX,maxY))'. |
type | BoxType | Yes | The coordinate type used to define the extent. Valid values: Raster (pixel coordinates), World (world coordinates). |
zfactor | float8 | No | A scaling factor applied to elevation values when the elevation unit differs from the horizontal coordinate unit. Default: 1. |
azimuth | float8 | No | The sun's azimuth angle, measured clockwise from north. Unit: degrees. Valid values: 0–360. Default: 315 (northwest). |
altitude | float8 | No | The sun's altitude angle above the horizon. Unit: degrees. Valid values: 0–90. A value of 90 means the sun is directly overhead. |
storageOption | cstring | No | Storage options for the output raster object. For details, see ST_ClipToRast. |
How it works
ST_Hillshade places a hypothetical light source at the position defined by azimuth and altitude, then computes the illumination value of each cell relative to its neighbors. By default, the output raster represents each cell value as an integer between 0 and 255: 0 is the darkest shade (no illumination) and 255 is the brightest (full illumination).
Hillshade rasters improve terrain visualization, especially when rendered with transparency over an elevation map.
Example
select st_hillshade(rast, 0, 0, '(0,0), (5,5)', 'Raster', 4, 180, 80) from t_surface where id=1;This example calculates the hillshade for band 0 of the raster at pyramid level 0, over a pixel extent from (0,0) to (5,5). The sun is positioned at azimuth 180° (south) and altitude 80°, with a zfactor of 4.