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 bd6ec7cfc975859b5c43351b547b242221eb38b8..450a6cdb8ebcc6b79de6998f2c018bf402ae355f 100644 (file)
--- 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 a31e7128773e3a71fcca1a14cdb6558686f41d64..bf819b65c2cd168fb0ffeed6735030d596cd7995 100644 (file)
--- 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>