Calculates the hillshade of each cell in a raster surface and returns an array of hillshades. Shadow and light are represented as gray integer values from 0 (darkest) to 255 (brightest).
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 raster object. |
pyramid_level | integer | The pyramid level of the raster. |
band | integer | The band sequence number. |
extent | Box | The area to analyze. Format: '((minX,minY),(maxX,maxY))'. |
type | BoxType | The coordinate type used to identify the analysis area. Valid values: Raster (pixel coordinates), World (world coordinates). |
zfactor | float8 | The conversion factor for adjusting elevation units when they differ from the horizontal coordinate units. Default: 1. |
azimuth | float8 | The sun azimuth angle, measured clockwise from north. Unit: degrees. Valid values: 0–360. Default: 315 (northwest). |
altitude | float8 | The sun altitude angle above the horizon. Unit: degrees. Valid values: 0–90. A value of 90 means the sun is directly overhead. |
storageOption | cstring | The storage option of the output raster object. For details, see ST_ClipToRast. |
How it works
ST_Hillshade positions a hypothetical light source and computes the illumination value of each cell relative to its neighbors. The output is a grayscale raster where each cell value is an integer in the range 0–255: 0 represents full shadow and 255 represents full brightness.
The result enhances the visual representation of terrain surfaces, particularly when rendered with transparency.
Example
The following example constructs a 5×5 raster inline and computes its hillshade. It runs without any existing tables.
WITH src AS (
SELECT ST_SetValues(
ST_AddBand(
ST_MakeEmptyRaster(5, 5, 0, 0, 1, -1, 0, 0, 0),
1, '32BF', 0, -9999
),
1, 1, 1,
ARRAY[[1,1,1,1,1],
[1,2,2,2,1],
[1,2,3,2,1],
[1,2,2,2,1],
[1,1,1,1,1]]::float8[][]
) AS rast
)
SELECT st_hillshade(rast, 0, 0, '((0,0),(5,5))', 'Raster', 4, 180, 80) FROM src;The function returns the hillshade raster. Each cell value is an integer in the range 0–255.