Added docs for ST_Covers()

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

diff --git a/NEWS b/NEWS
index 21ea5aedc45316ced9b5f54b4cc163c20bd451c2..0828590e30326bb85e4e0eddd8681d932edee7f7 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -14,7 +14,8 @@ 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_ContainsProperly, ST_Within)
+    (ST_Overlaps, ST_Touches, ST_Contains, ST_ContainsProperly, ST_Covers,
+    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 ab9b5fae80fb8ca74ab3a529522d8a87022660dd..4dac6da3d59c2ac64761d3a283f0f62f76d65950 100644 (file)
--- a/doc/reference_raster.xml
+++ b/doc/reference_raster.xml
@@ -8726,7 +8726,7 @@ a_rid | b_rid | overleft
                <refnamediv>
                        <refname>ST_Intersects</refname>
 
-                       <refpurpose>Return true if raster rastA spatially intersects raster 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>
+                       <refpurpose>Return true if raster rastA spatially intersects raster rastB.
                  </refnamediv>
 
                  <refsynopsisdiv>
@@ -8859,7 +8859,7 @@ a_rid | b_rid | overleft
                <refnamediv>
                        <refname>ST_Overlaps</refname>
                        <refpurpose>
-                               Return true if raster rastA spatially overlaps raster 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.
+                               Return true if raster rastA and rastB intersect but one does not completely contain the other.
                        </refpurpose>
                </refnamediv>
 
@@ -8941,7 +8941,7 @@ a_rid | b_rid | overleft
                <refnamediv>
                        <refname>ST_Touches</refname>
                        <refpurpose>
-                               Return true if raster rastA spatially touch raster 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.
+                               Return true if raster rastA and rastB have at least one point in common but their interiors do not intersect.
                        </refpurpose>
                </refnamediv>
 
@@ -9023,7 +9023,7 @@ a_rid | b_rid | overleft
                <refnamediv>
                        <refname>ST_Contains</refname>
                        <refpurpose>
-                               Return true if no points of raster rastB lie in the exterior of raster rastA and at least one point of the interior of rastB lies in the interior of rastA. 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.
+                               Return true if no points of raster rastB lie in the exterior of raster rastA and at least one point of the interior of rastB lies in the interior of rastA.
                        </refpurpose>
                </refnamediv>
 
@@ -9112,7 +9112,7 @@ a_rid | b_rid | overleft
                <refnamediv>
                        <refname>ST_ContainsProperly</refname>
                        <refpurpose>
-                               Return true if rastB intersects the interior of rastA but not the boundary or exterior of rastA. 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.
+                               Return true if rastB intersects the interior of rastA but not the boundary or exterior of rastA.
                        </refpurpose>
                </refnamediv>
 
@@ -9195,18 +9195,18 @@ a_rid | b_rid | overleft
                </refsection>
        </refentry>
 
-       <refentry id="RT_ST_Within">
+       <refentry id="RT_ST_Covers">
                <refnamediv>
-                       <refname>ST_Within</refname>
+                       <refname>ST_Covers</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.
+                               Return true if no points of raster rastB lie outside raster rastA.
                        </refpurpose>
                </refnamediv>
 
                <refsynopsisdiv>
                        <funcsynopsis>
                                <funcprototype>
-                                       <funcdef>boolean <function>ST_Within</function></funcdef>
+                                       <funcdef>boolean <function>ST_Covers</function></funcdef>
                                        <paramdef>
                                                <type>raster </type>
                                                <parameter>rastA</parameter>
@@ -9226,7 +9226,7 @@ a_rid | b_rid | overleft
                                </funcprototype>
 
                                <funcprototype>
-                                       <funcdef>boolean <function>ST_Within</function></funcdef>
+                                       <funcdef>boolean <function>ST_Covers</function></funcdef>
                                        <paramdef>
                                                <type>raster </type>
                                                <parameter>rastA</parameter>
@@ -9244,7 +9244,7 @@ a_rid | b_rid | overleft
                        <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.
+                               Raster rastA covers rastB if and only if no points of rastB lie in the exterior of rastA. 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>
@@ -9255,13 +9255,7 @@ a_rid | b_rid | overleft
 
                        <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).
+                                       To test the spatial relationship of a raster and a geometry, use ST_Polygon on the raster, e.g. ST_Covers(ST_Polygon(raster), geometry) or ST_Covers(geometry, ST_Polygon(raster)).
                                </para>
                        </note>
 
@@ -9278,8 +9272,7 @@ a_rid | b_rid | overleft
                <refsection>
                        <title>See Also</title>
                        <para>
-                               <xref linkend="RT_ST_Intersects" />, 
-                               <xref linkend="RT_ST_Contains" />,
+                               <xref linkend="RT_ST_Intersects" />
                        </para>
                </refsection>
        </refentry>
@@ -9414,5 +9407,95 @@ NOTICE:  The two rasters provided have different SRIDs
                                <para><xref linkend="RT_Loading_Rasters" />, <xref linkend="RT_ST_MakeEmptyRaster" /></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.
+                       </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>
+
        </sect1>
 </chapter>