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

## Name

ST_Neighborhood — Returns a 2-D double precision array of the non-`NODATA` values around a given band's pixel specified by either a columnX and rowY or a geometric point expressed in the same spatial reference coordinate system as the raster.

## Synopsis

`double precision[][] ST_Neighborhood(`raster rast, integer bandnum, integer columnX, integer rowY, integer distanceX, integer distanceY, boolean exclude_nodata_value=true`)`;

`double precision[][] ST_Neighborhood(`raster rast, integer columnX, integer rowY, integer distanceX, integer distanceY, boolean exclude_nodata_value=true`)`;

`double precision[][] ST_Neighborhood(`raster rast, integer bandnum, geometry pt, integer distanceX, integer distanceY, boolean exclude_nodata_value=true`)`;

`double precision[][] ST_Neighborhood(`raster rast, geometry pt, integer distanceX, integer distanceY, boolean exclude_nodata_value=true`)`;

## Description

Returns a 2-D double precision array of the non-`NODATA` values around a given band's pixel specified by either a columnX and rowY or a geometric point expressed in the same spatial reference coordinate system as the raster. The `distanceX` and `distanceY` parameters define the number of pixels around the specified pixel in the X and Y axes, e.g. I want all values within 3 pixel distance along the X axis and 2 pixel distance along the Y axis around my pixel of interest. The center value of the 2-D array will be the value at the pixel specified by the columnX and rowY or the geometric point.

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.

The number of elements along each axis of the returning 2-D array is 2 * (`distanceX`|`distanceY`) + 1. So for a `distanceX` and `distanceY` of 1, the returning array will be 3x3.

The 2-D array output can be passed to any of the raster processing builtin functions, e.g. ST_Min4ma, ST_Sum4ma, ST_Mean4ma.

Availability: 2.1.0

## Examples

    -- pixel 2x2 has value
    SELECT
        ST_Neighborhood(rast, 2, 2, 1, 1)
    FROM (
        SELECT
            ST_SetValues(
                ST_AddBand(
                    ST_MakeEmptyRaster(5, 5, -2, 2, 1, -1, 0, 0, 0),
                    '8BUI'::text, 1, 0
                ),
                1, 1, 1, ARRAY[
                    [0, 1, 1, 1, 1],
                    [1, 1, 1, 0, 1],
                    [1, 0, 1, 1, 1],
                    [1, 1, 1, 1, 0],
                    [1, 1, 0, 1, 1]
                ]::double precision[],
                1
            ) AS rast
    ) AS foo

             st_neighborhood
    ---------------------------------
    {{NULL,1,1},{1,1,1},{1,NULL,1}}

    -- pixel 2x3 is NODATA
    SELECT
        ST_Neighborhood(rast, 2, 3, 1, 1)
    FROM (
        SELECT
            ST_SetValues(
                ST_AddBand(
                    ST_MakeEmptyRaster(5, 5, -2, 2, 1, -1, 0, 0, 0),
                    '8BUI'::text, 1, 0
                ),
                1, 1, 1, ARRAY[
                    [0, 1, 1, 1, 1],
                    [1, 1, 1, 0, 1],
                    [1, 0, 1, 1, 1],
                    [1, 1, 1, 1, 0],
                    [1, 1, 0, 1, 1]
                ]::double precision[],
                1
            ) AS rast
    ) AS foo

           st_neighborhood
    ------------------------------
     {{1,1,1},{1,NULL,1},{1,1,1}}

    -- pixel 3x3 has value
    -- exclude_nodata_value = FALSE
    SELECT
        ST_Neighborhood(rast, 3, 3, 1, 1, false)
    FROM ST_SetValues(
                ST_AddBand(
                    ST_MakeEmptyRaster(5, 5, -2, 2, 1, -1, 0, 0, 0),
                    '8BUI'::text, 1, 0
                ),
                1, 1, 1, ARRAY[
                    [0, 1, 1, 1, 1],
                    [1, 1, 1, 0, 1],
                    [1, 0, 1, 1, 1],
                    [1, 1, 1, 1, 0],
                    [1, 1, 0, 1, 1]
                ]::double precision[],
                1
            ) AS rast

          st_neighborhood
    ---------------------------
    {{1,1,0},{0,1,1},{1,1,1}}

## See Also

ST_NearestValue, ST_Min4ma, ST_Max4ma, ST_Sum4ma, ST_Mean4ma, ST_Range4ma, ST_Distinct4ma, ST_StdDev4ma

Prev | Up | Next
ST_SetM | Home | ST_SetValue