ST_NearestValue

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

[Note]

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