Addition of docs for ST_Within(raster, raster)

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

diff --git a/NEWS b/NEWS
index 3c629c1971c5e6a7a4be54802df155f04ee87bd4..5cde4a7d0666282afa5c43e64136cc70a8934618 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -3,9 +3,8 @@ PostGIS 2.1.0
 
 * Important / Breaking Changes  *
 
-  - ST_Intersects(raster, geometry) and ST_Intersects(geometry, raster)
-    has been removed.  Use ST_Intersects(ST_Polygon(raster), geometry)
-    instead.
+  - ST_Intersects(raster, geometry) behaves in the same manner as
+    ST_Intersects(geometry, raster).
 
 * New Features *
 
@@ -15,7 +14,7 @@ PostGIS 2.1.0
   - ST_PixelAsCentroid, ST_PixelAsCentroids (Bborie Park / UC Davis)
   - ST_Raster2WorldCoord, ST_World2RasterCoord (Bborie Park / UC Davis)
   - Additional raster/raster spatial relationship functions
-    (ST_Overlaps, ST_Touches, ST_Contains)
+    (ST_Overlaps, ST_Touches, ST_Contains, ST_Within)
     (Bborie Park / UC Davis)
   - #1643, Tiger Geocoder - Tiger 2011 loader (Regina Obe / Paragon Corporation) 
     Funded by Hunter Systems Group

diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml
index 6be05c376a733fc1adcc983f2f30a856ddf3d399..6fc99bd375799a04324a605ce17ad9f7d5792e52 100644 (file)
--- a/doc/reference_raster.xml
+++ b/doc/reference_raster.xml
@@ -9083,6 +9083,12 @@ a_rid | b_rid | overleft
                                </para>
                        </note>
 
+                       <note>
+                               <para>
+                                       ST_Contains() is the inverse of ST_Within().  So, ST_Contains(rastA, rastB) implies ST_Within(rastB, rastA).
+                               </para>
+                       </note>
+
                        <para>Availability: 2.1.0</para>
                </refsection>
 
@@ -9096,7 +9102,97 @@ a_rid | b_rid | overleft
                <refsection>
                        <title>See Also</title>
                        <para>
-                               <xref linkend="RT_ST_Intersects" />
+                               <xref linkend="RT_ST_Intersects" />, 
+                               <xref linkend="RT_ST_Within" />
+                       </para>
+               </refsection>
+       </refentry>
+
+       <refentry id="RT_ST_Within">
+               <refnamediv>
+                       <refname>ST_Within</refname>
+                       <refpurpose>
+                               Return true if no points of raster rastA lie in the exterior of raster rastB and at least one point of the interior of rastA lies in the interior of rastB. If the band number is not provided (or set to NULL), only the convex hull of the raster is considered in the test. If the band number is provided, only those pixels with value (not NODATA) are considered in the test.
+                       </refpurpose>
+               </refnamediv>
+
+               <refsynopsisdiv>
+                       <funcsynopsis>
+                               <funcprototype>
+                                       <funcdef>boolean <function>ST_Within</function></funcdef>
+                                       <paramdef>
+                                               <type>raster </type>
+                                               <parameter>rastA</parameter>
+                                       </paramdef>
+                                       <paramdef>
+                                               <type>integer </type>
+                                               <parameter>nbandA</parameter>
+                                       </paramdef>
+                                       <paramdef>
+                                               <type>raster </type>
+                                               <parameter>rastB</parameter>
+                                       </paramdef>
+                                       <paramdef>
+                                               <type>integer </type>
+                                               <parameter>nbandB</parameter>
+                                       </paramdef>
+                               </funcprototype>
+
+                               <funcprototype>
+                                       <funcdef>boolean <function>ST_Within</function></funcdef>
+                                       <paramdef>
+                                               <type>raster </type>
+                                               <parameter>rastA</parameter>
+                                       </paramdef>
+                                       <paramdef>
+                                               <type>raster </type>
+                                               <parameter>rastB</parameter>
+                                       </paramdef>
+                               </funcprototype>
+
+                       </funcsynopsis>
+               </refsynopsisdiv>
+
+               <refsection>
+                       <title>Description</title>
+
+                       <para>
+                               Raster rastA is within rastB if and only if no points of rastA lie in the exterior of rastB and at least one point of the interior of rastA lies in the interior of rastB. If the band number is not provided (or set to NULL), only the convex hull of the raster is considered in the test. If the band number is provided, only those pixels with value (not NODATA) are considered in the test.
+                       </para>
+
+                       <note>
+                               <para>
+                                       This operand will make use of any indexes that may be available on the rasters.
+                               </para>
+                       </note>
+
+                       <note>
+                               <para>
+                                       To test the spatial relationship of a raster and a geometry, use ST_Polygon on the raster, e.g. ST_Within(ST_Polygon(raster), geometry) or ST_Within(geometry, ST_Polygon(raster)).
+                               </para>
+                       </note>
+
+                       <note>
+                               <para>
+                                       ST_Within() is the inverse of ST_Contains().  So, ST_Within(rastA, rastB) implies ST_Contains(rastB, rastA).
+                               </para>
+                       </note>
+
+                       <para>Availability: 2.1.0</para>
+               </refsection>
+
+               <refsection>
+                       <title>Examples</title>
+
+                       <programlisting>
+-- needs an example
+                       </programlisting>
+               </refsection>
+               <refsection>
+                       <title>See Also</title>
+                       <para>
+                               <xref linkend="RT_ST_Intersects" />, 
+                               <xref linkend="RT_ST_Contains" />,
                        </para>
                </refsection>
        </refentry>