From 57b4b24332507decf5ca73677ee06ead8cc3d346 Mon Sep 17 00:00:00 2001
From: Bborie Park <bkpark at ucdavis.edu>
Date: Thu, 19 Jul 2012 18:18:30 +0000
Subject: [PATCH] Added docs for ST_Overlaps

git-svn-id: http://svn.osgeo.org/postgis/trunk@10075 b70326c6-7e19-0410-871a-916f4a2858ee
---
 NEWS                     |   2 +
 doc/reference_raster.xml | 134 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 135 insertions(+), 1 deletion(-)

diff --git a/NEWS b/NEWS
index 60d4cb6e5..8a13e1ea5 100644
--- a/NEWS
+++ b/NEWS
@@ -8,6 +8,8 @@ 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)
+  - Additional raster/raster and raster/geometry spatial relationship
+    functions (ST_Overlaps) (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 62477e0d0..ddbbe8f23 100644
--- a/doc/reference_raster.xml
+++ b/doc/reference_raster.xml
@@ -8863,9 +8863,141 @@ WHERE A.rid =2 ;
 		  </refsection>	
 			<refsection>
 				<title>See Also</title>
-				<para><xref linkend="RT_ST_Intersection" /></para>
+				<para>
+					<xref linkend="RT_ST_Overlaps" />
+				</para>
 			</refsection>
 		</refentry>
+
+	<refentry id="RT_ST_Overlaps">
+		<refnamediv>
+			<refname>ST_Overlaps</refname>
+			<refpurpose>
+				Return true if the raster spatially overlaps a separate raster or geometry. 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_Overlaps</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_Overlaps</function></funcdef>
+					<paramdef>
+						<type>raster </type>
+						<parameter>rasta</parameter>
+					</paramdef>
+					<paramdef>
+						<type>raster </type>
+						<parameter>rastb</parameter>
+					</paramdef>
+				</funcprototype>
+
+				<funcprototype>
+					<funcdef>boolean <function>ST_Overlaps</function></funcdef>
+					<paramdef>
+						<type>raster </type>
+						<parameter>rast</parameter>
+					</paramdef>
+					<paramdef>
+						<type>integer </type>
+						<parameter>nband</parameter>
+					</paramdef>
+					<paramdef>
+						<type>geometry </type>
+						<parameter>geommin</parameter>
+					</paramdef>
+				</funcprototype>
+
+				<funcprototype>
+					<funcdef>boolean <function>ST_Overlaps</function></funcdef>
+					<paramdef>
+						<type>raster </type>
+						<parameter>rast</parameter>
+					</paramdef>
+					<paramdef>
+						<type>geometry </type>
+						<parameter>geommin</parameter>
+					</paramdef>
+					<paramdef choice='opt'>
+						<type>integer </type>
+						<parameter>nband=NULL</parameter>
+					</paramdef>
+				</funcprototype>
+
+				<funcprototype>
+					<funcdef>boolean <function>ST_Overlaps</function></funcdef>
+					<paramdef>
+						<type>geometry </type>
+						<parameter>geommin</parameter>
+					</paramdef>
+					<paramdef>
+						<type>raster </type>
+						<parameter>rast</parameter>
+					</paramdef>
+					<paramdef choice='opt'>
+						<type>integer </type>
+						<parameter>nband=NULL</parameter>
+					</paramdef>
+				</funcprototype>
+
+			</funcsynopsis>
+		</refsynopsisdiv>
+
+		<refsection>
+			<title>Description</title>
+
+			<para>
+				Return true if the raster spatially overlaps a separate raster or geometry. This means that the raster/raster or raster/geometry combinations intersect but one does not completely contain the other. 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>
+					Depending on the order that the raster and geometry is passed to ST_Overlaps(), the test will operate in either raster-space or geometry-space.  If ST_Overlaps(raster, ....), the test is in raster-space (the geometry is converted to a raster).  If ST_Overlaps(geometry, ...), the test is in geometry-space (the raster is converted to a set of pixel polygons).
+				</para>
+			</note>
+
+			<note>
+				<para>
+					This operand will make use of any indexes that may be available on the geometries / rasters.
+				</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" />
+			</para>
+		</refsection>
+	</refentry>
 		
 	<refentry id="RT_ST_SameAlignment">
 		<refnamediv>
-- 
2.50.1