Added items to NEWS and docs for ST_DumpValues

git-svn-id: http://svn.osgeo.org/postgis/trunk@10458 b70326c6-7e19-0410-871a-916f4a2858ee

diff --git a/NEWS b/NEWS
index 01830144510e29d90a81b3900a531d2248c50ebc..17272ed5664520c1597dbbc6880819001a60065b 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -34,6 +34,7 @@ PostGIS 2.1.0
   - GEOMETRYCOLLECTION support for ST_MakeValid (Sandro Santilli / Vizzuality)
   - ST_PixelOfValue (Bborie Park / UC Davis)
   - Casts to/from PostgreSQL geotypes (point/path/polygon).
+  - #2011, ST_DumpValues to output raster as array (Bborie Park / UC Davis)
   - #2030, n-raster (and n-band) ST_MapAlgebra (Bborie Park / UC Davis)
 
 * Enhancements *

diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml
index c15b06aad47d938ef1ed97c1eb7d9a8bfb12ff57..299d72b55826e591ea0619d81c8af4b55bfc7fc0 100644 (file)
--- a/doc/reference_raster.xml
+++ b/doc/reference_raster.xml
@@ -4581,6 +4581,99 @@ ORDER BY 1, 2;
                        </refsection>
                </refentry>
 
+               <refentry id="RT_ST_DumpValues">
+                       <refnamediv>
+                               <refname>ST_DumpValues</refname>
+                               <refpurpose>
+                                       Get the values of the specified band as a 2-dimension array.
+                               </refpurpose>
+                       </refnamediv>
+
+                       <refsynopsisdiv>
+                               <funcsynopsis>
+                                       <funcprototype>
+                                               <funcdef>setof record <function>ST_DumpValues</function></funcdef>
+                                               <paramdef>
+                                                       <type>raster </type> <parameter>rast</parameter>
+                                               </paramdef>
+                                               <paramdef>
+                                                       <type>integer[] </type> <parameter>nband</parameter>
+                                               </paramdef>
+                                               <paramdef>
+                                                       <type>boolean </type> <parameter>exclude_nodata_value=true</parameter>
+                                               </paramdef>
+                                       </funcprototype>
+                                       <funcprototype>
+                                               <funcdef>double precision[][] <function>ST_DumpValues</function></funcdef>
+                                               <paramdef>
+                                                       <type>raster </type> <parameter>rast</parameter>
+                                               </paramdef>
+                                               <paramdef>
+                                                       <type>integer </type> <parameter>nband</parameter>
+                                               </paramdef>
+                                               <paramdef>
+                                                       <type>boolean </type> <parameter>exclude_nodata_value=true</parameter>
+                                               </paramdef>
+                                       </funcprototype>
+                               </funcsynopsis>
+                       </refsynopsisdiv>
+
+                       <refsection>
+                               <title>Description</title>
+
+                               <para>
+                                       Get the values of the specified band as a 2-dimension array.  If <varname>nband</varname> is NULL or not provided, all raster bands are processed.
+                               </para>
+
+                               <para>Availability: 2.1.0</para>
+                       </refsection>
+
+                       <refsection>
+                               <title>Examples</title>
+
+                               <programlisting>
+WITH foo AS (
+       SELECT ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(3, 3, 0, 0, 1, -1, 0, 0, 0), 1, '8BUI', 1, 0), 2, '32BF', 3, -9999), 3, '16BSI', 0, 0) AS rast
+)
+SELECT
+       (ST_DumpValues(rast)).*
+FROM foo;
+
+ nband |                       valarray                       
+-------+------------------------------------------------------
+     1 | {{1,1,1},{1,1,1},{1,1,1}}
+     2 | {{3,3,3},{3,3,3},{3,3,3}}
+     3 | {{NULL,NULL,NULL},{NULL,NULL,NULL},{NULL,NULL,NULL}}
+(3 rows)
+                               </programlisting>
+
+                               <programlisting>
+WITH foo AS (
+       SELECT ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(3, 3, 0, 0, 1, -1, 0, 0, 0), 1, '8BUI', 1, 0), 2, '32BF', 3, -9999), 3, '16BSI', 0, 0) AS rast
+)
+SELECT
+       (ST_DumpValues(rast, ARRAY[3, 1])).*
+FROM foo;
+
+ nband |                       valarray                       
+-------+------------------------------------------------------
+     3 | {{NULL,NULL,NULL},{NULL,NULL,NULL},{NULL,NULL,NULL}}
+     1 | {{1,1,1},{1,1,1},{1,1,1}}
+(2 rows)
+                               </programlisting>
+                       </refsection>
+
+                       <refsection>
+                               <title>See Also</title>
+                               <para>
+                                       <xref linkend="RT_ST_Value" />, 
+                                       <xref linkend="RT_ST_SetValue" />, 
+                                       <xref linkend="RT_ST_SetValues" />
+                               </para>
+                       </refsection>
+
+               </refentry>
+
                <refentry id="RT_ST_PixelOfValue">
                        <refnamediv>
                                <refname>ST_PixelOfValue</refname>