From: Bborie Park <bkpark at ucdavis.edu>
Date: Mon, 23 Jul 2012 18:58:21 +0000 (+0000)
Subject: Added docs for ST_ContainsProperly(raster, raster) and minor tweaking of
X-Git-Tag: 2.1.0beta2~762
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=462d4c95c3cc1459522d35712f4dea761a30e484;p=postgis

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 5cde4a7d0..21ea5aedc 100644
--- 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 1dc795956..ab9b5fae8 100644
--- 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 8f718e8c6..0771cb0f7 100644
--- 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 873fb2c2c..ba9858be4 100644
--- 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
  */