Added docs for ST_ContainsProperly(raster, raster) and minor tweaking of

comments

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

diff --git a/NEWS b/NEWS
index 5cde4a7d0666282afa5c43e64136cc70a8934618..21ea5aedc45316ced9b5f54b4cc163c20bd451c2 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -14,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_Within)
+    (ST_Overlaps, ST_Touches, ST_Contains, ST_ContainsProperly, 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 1dc79595616075427e5dfeab1a6354520e2bf4dc..ab9b5fae80fb8ca74ab3a529522d8a87022660dd 100644 (file)
--- a/doc/reference_raster.xml
+++ b/doc/reference_raster.xml
@@ -9108,6 +9108,93 @@ a_rid | b_rid | overleft
                </refsection>
        </refentry>
 
+       <refentry id="RT_ST_ContainsProperly">
+               <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.
+                       </refpurpose>
+               </refnamediv>
+
+               <refsynopsisdiv>
+                       <funcsynopsis>
+                               <funcprototype>
+                                       <funcdef>boolean <function>ST_ContainsProperly</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_ContainsProperly</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 contains properly rastB 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.
+                       </para>
+
+                       <para>
+                               Raster rastA does not contain properly itself but does contain itself.
+                       </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_ContainsProperly(ST_Polygon(raster), geometry) or ST_ContainsProperly(geometry, ST_Polygon(raster)).
+                               </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>
+
        <refentry id="RT_ST_Within">
                <refnamediv>
                        <refname>ST_Within</refname>

diff --git a/raster/rt_core/rt_api.c b/raster/rt_core/rt_api.c
index 8f718e8c6109846356aeb3bd07f4e94ed3414425..0771cb0f7e816c135bf7aa7cc2fab9e2fb81363c 100644 (file)
--- a/raster/rt_core/rt_api.c
+++ b/raster/rt_core/rt_api.c
@@ -11683,7 +11683,7 @@ int rt_raster_contains(
 
 /**
  * Return zero if error occurred in function.
- * Parameter contains returns non-zero if rast1 properly contains rast2
+ * Parameter contains returns non-zero if rast1 contains properly rast2
  *
  * @param rast1 : the first raster whose band will be tested
  * @param nband1 : the 0-based band of raster rast1 to use
@@ -11693,7 +11693,7 @@ int rt_raster_contains(
  * @param nband2 : the 0-based band of raster rast2 to use
  *   if value is less than zero, bands are ignored
  *   if nband2 gte zero, nband1 must be gte zero
- * @param touches : non-zero value if rast1 properly contains rast2
+ * @param touches : non-zero value if rast1 contains properly rast2
  *
  * @return if zero, an error occurred in function
  */

diff --git a/raster/rt_core/rt_api.h b/raster/rt_core/rt_api.h
index 873fb2c2c87eefac9338a55ba527ed7ad1b02b1e..ba9858be4d9a7266ba8d1a43eff5687e2cca7003 100644 (file)
--- a/raster/rt_core/rt_api.h
+++ b/raster/rt_core/rt_api.h
@@ -1503,7 +1503,7 @@ int rt_raster_contains(
 
 /**
  * Return zero if error occurred in function.
- * Parameter contains returns non-zero if rast1 properly contains rast2
+ * Parameter contains returns non-zero if rast1 contains properly rast2
  *
  * @param rast1 : the first raster whose band will be tested
  * @param nband1 : the 0-based band of raster rast1 to use
@@ -1513,7 +1513,7 @@ int rt_raster_contains(
  * @param nband2 : the 0-based band of raster rast2 to use
  *   if value is less than zero, bands are ignored
  *   if nband2 gte zero, nband1 must be gte zero
- * @param touches : non-zero value if rast1 properly contains rast2
+ * @param touches : non-zero value if rast1 contains properly rast2
  *
  * @return if zero, an error occurred in function
  */