ST_NearestValue
Prev | 12.6. Raster Pixel Accessors and Setters | Next

## Name

ST_NearestValue — Returns the nearest non-`NODATA` value of a given band's pixel specified by a columnx and rowy or a geometric point expressed in the same spatial reference coordinate system as the raster.

## Synopsis

`double precision ST_NearestValue(`raster rast, integer bandnum, geometry pt, boolean exclude_nodata_value=true`)`;

`double precision ST_NearestValue(`raster rast, geometry pt, boolean exclude_nodata_value=true`)`;

`double precision ST_NearestValue(`raster rast, integer bandnum, integer columnx, integer rowy, boolean exclude_nodata_value=true`)`;

`double precision ST_NearestValue(`raster rast, integer columnx, integer rowy, boolean exclude_nodata_value=true`)`;

## Description

Returns the nearest non-`NODATA` value of a given band in a given columnx, rowy pixel or at a specific geometric point. If the columnx, rowy pixel or the pixel at the specified geometric point is `NODATA`, the function will find the nearest pixel to the columnx, rowy pixel or geometric point whose value is not `NODATA`.

Band numbers start at 1 and `bandnum` is assumed to be 1 if not specified. If `exclude_nodata_value` is set to false, then all pixels include `nodata` pixels are considered to intersect and return value. If `exclude_nodata_value` is not passed in then reads it from metadata of raster.

Availability: 2.1.0

ST_NearestValue is a drop-in replacement for ST_Value.

## Examples

    -- pixel 2x2 has value
    SELECT
        ST_Value(rast, 2, 2) AS value,
        ST_NearestValue(rast, 2, 2) AS nearestvalue
    FROM (
        SELECT
            ST_SetValue(
                ST_SetValue(
                    ST_SetValue(
                        ST_SetValue(
                            ST_SetValue(
                                ST_AddBand(
                                    ST_MakeEmptyRaster(5, 5, -2, 2, 1, -1, 0, 0, 0),
                                    '8BUI'::text, 1, 0
                                ),
                                1, 1, 0.
                            ),
                            2, 3, 0.
                        ),
                        3, 5, 0.
                    ),
                    4, 2, 0.
                ),
                5, 4, 0.
            ) AS rast
    ) AS foo

     value | nearestvalue
    -------+--------------
         1 |            1

    -- pixel 2x3 is NODATA
    SELECT
        ST_Value(rast, 2, 3) AS value,
        ST_NearestValue(rast, 2, 3) AS nearestvalue
    FROM (
        SELECT
            ST_SetValue(
                ST_SetValue(
                    ST_SetValue(
                        ST_SetValue(
                            ST_SetValue(
                                ST_AddBand(
                                    ST_MakeEmptyRaster(5, 5, -2, 2, 1, -1, 0, 0, 0),
                                    '8BUI'::text, 1, 0
                                ),
                                1, 1, 0.
                            ),
                            2, 3, 0.
                        ),
                        3, 5, 0.
                    ),
                    4, 2, 0.
                ),
                5, 4, 0.
            ) AS rast
    ) AS foo

     value | nearestvalue
    -------+--------------
           |            1

## See Also

ST_Neighborhood, ST_Value

Prev | Up | Next
ST_Value | Home | ST_SetZ