# ST_Neighborhood

## 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_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_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_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}}
```