ST_HillShade
Prev | 12.14. Raster Processing: DEM (Elevation) | Next

## Name

ST_HillShade — Returns the hypothetical illumination of an elevation raster band using provided azimuth, altitude, brightness and scale inputs.

## Synopsis

`raster ST_HillShade(`raster rast, integer band=1, text pixeltype=32BF, double precision azimuth=315, double precision altitude=45, double precision max_bright=255, double precision scale=1.0, boolean interpolate_nodata=FALSE`)`;

`raster ST_HillShade(`raster rast, integer band, raster customextent, text pixeltype=32BF, double precision azimuth=315, double precision altitude=45, double precision max_bright=255, double precision scale=1.0, boolean interpolate_nodata=FALSE`)`;

## Description

Returns the hypothetical illumination of an elevation raster band using the azimuth, altitude, brightness, and scale inputs. Utilizes map algebra and applies the hill shade equation to neighboring pixels. Return pixel values are between 0 and 255.

`azimuth` is a value between 0 and 360 degrees measured clockwise from North.

`altitude` is a value between 0 and 90 degrees where 0 degrees is at the horizon and 90 degrees is directly overhead.

`max_bright` is a value between 0 and 255 with 0 as no brightness and 255 as max brightness.

`scale` is the ratio of vertical units to horizontal. For Feet:LatLon use scale=370400, for Meters:LatLon use scale=111120.

If `interpolate_nodata` is TRUE, values for NODATA pixels from the input raster will be interpolated using ST_InvDistWeight4ma before computing the hillshade illumination.

For more information about Hillshade, please refer to How hillshade works.

Availability: 2.0.0

Enhanced: 2.1.0 Uses ST_MapAlgebra() and added optional `interpolate_nodata` function parameter

Changed: 2.1.0 In prior versions, azimuth and altitude were expressed in radians. Now, azimuth and altitude are expressed in degrees

## Examples: Variant 1

    WITH foo 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]
            ]::double precision[][]
        ) AS rast
    )
    SELECT
        ST_DumpValues(ST_Hillshade(rast, 1, '32BF'))
    FROM foo

                                                                                                                           st_dumpvalues

    ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
    -----------------------------------------------------------------------
     (1,"{{NULL,NULL,NULL,NULL,NULL},{NULL,251.32763671875,220.749786376953,147.224319458008,NULL},{NULL,220.749786376953,180.312225341797,67.7497863769531,NULL},{NULL,147.224319458008
    ,67.7497863769531,43.1210060119629,NULL},{NULL,NULL,NULL,NULL,NULL}}")
    (1 row)

## Examples: Variant 2

Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher.

    WITH foo AS (
        SELECT ST_Tile(
            ST_SetValues(
                ST_AddBand(
                    ST_MakeEmptyRaster(6, 6, 0, 0, 1, -1, 0, 0, 0),
                    1, '32BF', 0, -9999
                ),
                1, 1, 1, ARRAY[
                    [1, 1, 1, 1, 1, 1],
                    [1, 1, 1, 1, 2, 1],
                    [1, 2, 2, 3, 3, 1],
                    [1, 1, 3, 2, 1, 1],
                    [1, 2, 2, 1, 2, 1],
                    [1, 1, 1, 1, 1, 1]
                ]::double precision[]
            ),
            2, 2
        ) AS rast
    )
    SELECT
        t1.rast,
        ST_Hillshade(ST_Union(t2.rast), 1, t1.rast)
    FROM foo t1
    CROSS JOIN foo t2
    WHERE ST_Intersects(t1.rast, t2.rast)
    GROUP BY t1.rast;

## See Also

ST_MapAlgebra (callback function version), ST_TRI, ST_TPI, ST_Roughness, ST_Aspect, ST_Slope

Prev | Up | Next
ST_Aspect | Home | ST_Roughness