From: Bborie Park <bkpark at ucdavis.edu>
Date: Wed, 17 Oct 2012 16:08:22 +0000 (+0000)
Subject: Added items to NEWS and docs for ST_DumpValues
X-Git-Tag: 2.1.0beta2~515
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=7df57e61b8255199fee2725bd594680143b113e3;p=postgis

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 018301445..17272ed56 100644
--- 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 c15b06aad..299d72b55 100644
--- 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>