From: Bborie Park <bkpark at ucdavis.edu>
Date: Fri, 13 Jul 2012 23:29:02 +0000 (+0000)
Subject: Added docs and updated NEWS for ST_BandSurface
X-Git-Tag: 2.1.0beta2~801
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=3ad36df2958a6de2005010e09a0edf2738413450;p=postgis

Added docs and updated NEWS for ST_BandSurface

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

diff --git a/NEWS b/NEWS
index bd6ec7cfc..450a6cdb8 100644
--- a/NEWS
+++ b/NEWS
@@ -8,6 +8,7 @@ PostGIS 2.1.0
 	- ST_PixelAsPoint, ST_PixelAsPoints (Bborie Park / UC Davis)
 	- ST_PixelAsCentroid, ST_PixelAsCentroids (Bborie Park / UC Davis)
   - ST_Raster2WorldCoord, ST_World2RasterCoord (Bborie Park / UC Davis)
+	- ST_BandSurface (Bborie Park / UC Davis)
   - #1643, Tiger Geocoder - Tiger 2011 loader (Regina Obe / Paragon Corporation) 
     Funded by Hunter Systems Group
   - GEOMETRYCOLLECTION support for ST_MakeValid (Sandro Santilli / Vizzuality)
diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml
index a31e71287..bf819b65c 100644
--- a/doc/reference_raster.xml
+++ b/doc/reference_raster.xml
@@ -2973,6 +2973,93 @@ rid | hb1 | hb2 | hb4 | numbands
 				<para><xref linkend="RT_ST_NumBands" /></para>
 			</refsection>
 		</refentry>
+
+		<refentry id="RT_ST_BandSurface">
+			<refnamediv>
+				<refname>ST_BandSurface</refname>
+				<refpurpose>
+					Returns the surface (multipolygon) of the area represented by a raster's band.
+				</refpurpose>
+			</refnamediv>
+			<refsynopsisdiv>
+				<funcsynopsis>
+					<funcprototype>
+						<funcdef>geometry <function>ST_BandSurface</function></funcdef>
+						<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+						<paramdef choice='opt'><type>integer </type> <parameter>band=1</parameter></paramdef>
+					</funcprototype>
+				</funcsynopsis>
+			</refsynopsisdiv>
+
+			<refsection>
+				<title>Description</title>
+				<para>
+					Returns the surface (multipolygon) of the area represented by a raster's band.  The area represented by a raster's band is built using those pixels whose values are not NODATA.
+				</para>
+			</refsection>
+
+			<refsection>
+				<title>Examples</title>
+				<programlisting>
+SELECT
+	ST_AsText(ST_BandSurface(rast))
+FROM (
+	SELECT
+		ST_SetValue(
+			ST_SetValue(
+				ST_SetValue(
+					ST_SetValue(
+						ST_SetValue(
+							ST_SetValue(
+								ST_SetValue(
+									ST_SetValue(
+										ST_SetValue(
+											ST_AddBand(
+												ST_MakeEmptyRaster(5, 5, 0, 0, 1, -1, 0, 0, 0),
+												1, '32BUI', 1, 0
+											),
+											1, 1, 1, 0
+										),
+										1, 2, 2, 0
+									),
+									1, 3, 3, 0
+								),
+								1, 4, 4, 0
+							),
+							1, 5, 5, 0
+						),
+						1, 5, 1, 0
+					),
+					1, 4, 2, 0
+				),
+				1, 2, 4, 0
+			),
+			1, 1, 5, 0
+		) AS rast
+	FROM raster_surface
+) foo;
+
+                                                                                                                      st_astext                                                                                                                       
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ MULTIPOLYGON(((1 0,2 0,3 0,4 0,4 -1,3 -1,3 -2,2 -2,2 -1,1 -1,1 0)),((0 -1,1 -1,1 -2,2 -2,2 -3,1 -3,1 -4,0 -4,0 -3,0 -2,0 -1)),((4 -1,5 -1,5 -2,5 -3,5 -4,4 -4,4 -3,3 -3,3 -2,4 -2,4 -1)),((2 -3,3 -3,3 -4,4 -4,4 -5,3 -5,2 -5,1 -5,1 -4,2 -4,2 -3)))
+				</programlisting>
+			</refsection>
+
+			<refsection>
+				<title>See Also</title>
+				<para>
+					<xref linkend="RT_ST_DumpAsPolygons" />, 
+					<xref linkend="RT_ST_PixelAsPolygon" />, 
+					<xref linkend="RT_ST_PixelAsPolygons" />, 
+					<xref linkend="RT_ST_PixelAsPoint" />, 
+					<xref linkend="RT_ST_PixelAsPoints" />, 
+					<xref linkend="RT_ST_PixelAsCentroid" />, 
+					<xref linkend="RT_ST_PixelAsCentroids" />
+				</para>
+			</refsection>
+
+		</refentry>
+
 	</sect1>
 	
 	<sect1 id="Raster_Pixel_Accessors">
@@ -3021,8 +3108,16 @@ WHERE rid=2;
 
 			<refsection>
 				<title>See Also</title>
-				<para><xref linkend="RT_ST_DumpAsPolygons" />, <xref linkend="RT_ST_Intersection" />,
-							 <xref linkend="ST_AsText" />
+				<para>
+					<xref linkend="RT_ST_BandSurface" />, 
+					<xref linkend="RT_ST_DumpAsPolygons" />, 
+					<xref linkend="RT_ST_PixelAsPolygons" />, 
+					<xref linkend="RT_ST_PixelAsPoint" />, 
+					<xref linkend="RT_ST_PixelAsPoints" />, 
+					<xref linkend="RT_ST_PixelAsCentroid" />, 
+					<xref linkend="RT_ST_PixelAsCentroids" />, 
+					<xref linkend="RT_ST_Intersection" />, 
+					<xref linkend="ST_AsText" />
 				</para>
 			</refsection>
 		</refentry>
@@ -3083,7 +3178,12 @@ FROM (SELECT ST_PixelAsPolygons(
 				<title>See Also</title>
 				<para>
 					<xref linkend="RT_ST_DumpAsPolygons" />, 
+					<xref linkend="RT_ST_BandSurface" />, 
 					<xref linkend="RT_ST_PixelAsPolygon" />, 
+					<xref linkend="RT_ST_PixelAsPoint" />, 
+					<xref linkend="RT_ST_PixelAsPoints" />, 
+					<xref linkend="RT_ST_PixelAsCentroid" />, 
+					<xref linkend="RT_ST_PixelAsCentroids" />, 
 					<xref linkend="ST_AsText" />
 				</para>
 			</refsection>
@@ -3127,7 +3227,8 @@ FROM (SELECT ST_PixelAsPolygons(
 					<xref linkend="RT_ST_PixelAsPolygons" />, 
 					<xref linkend="RT_ST_PixelAsPoints" />, 
 					<xref linkend="RT_ST_PixelAsCentroid" />, 
-					<xref linkend="RT_ST_PixelAsCentroids" />
+					<xref linkend="RT_ST_PixelAsCentroids" />, 
+					<xref linkend="RT_ST_BandSurface" />
 				</para>
 			</refsection>
 
@@ -3173,7 +3274,8 @@ FROM (SELECT ST_PixelAsPolygons(
 					<xref linkend="RT_ST_PixelAsPolygons" />, 
 					<xref linkend="RT_ST_PixelAsPoint" />, 
 					<xref linkend="RT_ST_PixelAsCentroid" />, 
-					<xref linkend="RT_ST_PixelAsCentroids" />
+					<xref linkend="RT_ST_PixelAsCentroids" />, 
+					<xref linkend="RT_ST_BandSurface" />
 				</para>
 			</refsection>
 
@@ -3217,7 +3319,8 @@ FROM (SELECT ST_PixelAsPolygons(
 					<xref linkend="RT_ST_PixelAsPolygons" />, 
 					<xref linkend="RT_ST_PixelAsPoint" />, 
 					<xref linkend="RT_ST_PixelAsPoints" />, 
-					<xref linkend="RT_ST_PixelAsCentroids" />
+					<xref linkend="RT_ST_PixelAsCentroids" />, 
+					<xref linkend="RT_ST_BandSurface" />
 				</para>
 			</refsection>
 
@@ -3263,7 +3366,8 @@ FROM (SELECT ST_PixelAsPolygons(
 					<xref linkend="RT_ST_PixelAsPolygons" />, 
 					<xref linkend="RT_ST_PixelAsPoint" />, 
 					<xref linkend="RT_ST_PixelAsPoints" />, 
-					<xref linkend="RT_ST_PixelAsCentroid" />
+					<xref linkend="RT_ST_PixelAsCentroid" />, 
+					<xref linkend="RT_ST_BandSurface" />
 				</para>
 			</refsection>