<xref linkend="ST_Intersects" />, <xref linkend="ST_Intersection" /></para>
</refsection>
</refentry>
+
+ <refentry id="RT_ST_NearestValue">
+ <refnamediv>
+ <refname>ST_NearestValue</refname>
+ <refpurpose>
+ Returns the nearest non-<varname>NODATA</varname> 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.
+ </refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>double precision <function>ST_NearestValue</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>bandnum</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>pt</parameter></paramdef>
+ <paramdef choice='opt'><type>boolean </type> <parameter>exclude_nodata_value=true</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>double precision <function>ST_NearestValue</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>pt</parameter></paramdef>
+ <paramdef choice='opt'><type>boolean </type> <parameter>exclude_nodata_value=true</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>double precision <function>ST_NearestValue</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>bandnum</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>columnx</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>rowy</parameter></paramdef>
+ <paramdef choice='opt'><type>boolean </type> <parameter>exclude_nodata_value=true</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>double precision <function>ST_NearestValue</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>columnx</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>rowy</parameter></paramdef>
+ <paramdef choice='opt'><type>boolean </type> <parameter>exclude_nodata_value=true</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+ <para>
+ Returns the nearest non-<varname>NODATA</varname> 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 <varname>NODATA</varname>, the function will find the nearest pixel to the columnx, rowy pixel or geometric point whose value is not <varname>NODATA</varname>.
+ <para>
+ Band numbers start at 1 and <varname>bandnum</varname> is assumed to be 1 if not specified. If <varname>exclude_nodata_value</varname> is set to false, then all pixels include <varname>nodata</varname> pixels are considered to intersect and return value. If <varname>exclude_nodata_value</varname> is not passed in then reads it from metadata of raster.
+ </para>
+ <note>
+ <para>
+ ST_NearestValue is a drop-in replacement for ST_Value.
+ </para>
+ </note>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>
+-- 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
+ </programlisting>
+
+ <programlisting>
+-- 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
+ </programlisting>
+
+ </refsection>
+
+ </refentry>
+
+ <refentry id="RT_ST_Neighborhood">
+ <refnamediv>
+ <refname>ST_Neighborhood</refname>
+ <refpurpose>
+ Returns a 2-D double precision array of the non-<varname>NODATA</varname> 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.
+ </refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>double precision[][] <function>ST_Neighborhood</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>bandnum</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>columnx</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>rowy</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>distance</parameter></paramdef>
+ <paramdef choice='opt'><type>boolean </type> <parameter>exclude_nodata_value=true</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>double precision[][] <function>ST_Neighborhood</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>columnx</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>rowy</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>distance</parameter></paramdef>
+ <paramdef choice='opt'><type>boolean </type> <parameter>exclude_nodata_value=true</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>double precision[][] <function>ST_Neighborhood</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>bandnum</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>pt</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>distance</parameter></paramdef>
+ <paramdef choice='opt'><type>boolean </type> <parameter>exclude_nodata_value=true</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>double precision[][] <function>ST_Neighborhood</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>pt</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>distance</parameter></paramdef>
+ <paramdef choice='opt'><type>boolean </type> <parameter>exclude_nodata_value=true</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+ <para>
+ Returns a 2-D double precision array of the non-<varname>NODATA</varname> 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 <varname>distance</varname> 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.
+ <para>
+ Band numbers start at 1 and <varname>bandnum</varname> is assumed to be 1 if not specified. If <varname>exclude_nodata_value</varname> is set to false, then all pixels include <varname>nodata</varname> pixels are considered to intersect and return value. If <varname>exclude_nodata_value</varname> is not passed in then reads it from metadata of raster.
+ </para>
+ <note>
+ <para>
+ The number of elements along each axis of the returning 2-D array is 2 * <varname>distance</varname> + 1. So for a <varname>distance</varname> of 1, the returning array will be 3x3.
+ </para>
+ </note>
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>
+-- 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}}
+ </programlisting>
+
+ <programlisting>
+-- 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}}
+ </programlisting>
+
+ <programlisting>
+-- 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}}
+ </programlisting>
+
+ </refsection>
+
+ </refentry>
+
<refentry id="RT_ST_SetValue">
<refnamediv>
projects / postgis / commitdiff