From: Bborie Park Date: Tue, 22 May 2012 17:06:52 +0000 (+0000) Subject: Added docs for ST_NearestValue and ST_Neighborhood X-Git-Tag: 2.1.0beta2~985 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=2815c0fc34e14a3543440cd4653453a35329818d;p=postgis Added docs for ST_NearestValue and ST_Neighborhood git-svn-id: http://svn.osgeo.org/postgis/trunk@9798 b70326c6-7e19-0410-871a-916f4a2858ee --- diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml index 5c8eec6f0..cacb1e755 100644 --- a/doc/reference_raster.xml +++ b/doc/reference_raster.xml @@ -3271,6 +3271,309 @@ WHERE , + + + + 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. + + + + + + + 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. + + + + 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 + + + + + + + + + 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. + + + + + + + double precision[][] ST_Neighborhood + raster rast + integer bandnum + integer columnx + integer rowy + integer distance + boolean exclude_nodata_value=true + + + + double precision[][] ST_Neighborhood + raster rast + integer columnx + integer rowy + integer distance + boolean exclude_nodata_value=true + + + + double precision[][] ST_Neighborhood + raster rast + integer bandnum + geometry pt + integer distance + boolean exclude_nodata_value=true + + + + double precision[][] ST_Neighborhood + raster rast + geometry pt + integer distance + 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 distance parameter defines the number of pixels around the specified pixel, e.g. I want all values within 3 pixel distance 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 * distance + 1. So for a distance of 1, the returning array will be 3x3. + + + + + The 2-D array output can be passed along to any of the raster processing builtin functions, e.g. ST_Min4ma, ST_Sum4ma, ST_Mean4ma. + + + + + + Examples + + +-- pixel 2x2 has value +SELECT + ST_Neighborhood(rast, 2, 2, 1) +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 + + st_neighborhood +--------------------------------- + {{NULL,1,1},{1,1,NULL},{1,1,1}} + + + +-- pixel 2x3 is NODATA +SELECT + ST_Neighborhood(rast, 2, 3, 1) +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 + + 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, false) +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 + + st_neighborhood +--------------------------- + {{1,0,1},{1,1,1},{0,1,1}} + + + + + +