From: Regina Obe <lr@pcorp.us>
Date: Wed, 7 Apr 2010 13:59:11 +0000 (+0000)
Subject: first draft of ST_ConvexHull -- still need to put in pictures
X-Git-Tag: 2.0.0alpha1~3062
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=24dd92c4685c133eb9b82294ec8abbc86532a031;p=postgis

first draft of ST_ConvexHull -- still need to put in pictures

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

diff --git a/doc/reference_wktraster.xml b/doc/reference_wktraster.xml
index 4400a811c..8c1df07ef 100644
--- a/doc/reference_wktraster.xml
+++ b/doc/reference_wktraster.xml
@@ -951,4 +951,87 @@ FROM dummy_rast WHERE rid=1;
 			</refsection>
 		</refentry>
 	</sect1>
+	
+	<sect1 id="Raster_Processing">
+		<title>Raster Processing Functions</title>
+		<refentry id="RT_ST_ConvexHull">
+			<refnamediv>
+				<refname>ST_ConvexHull</refname>
+				<refpurpose>Return the convex hull geometry of the raster including pixel values equal to BandNoDataValue. 
+				For regular shaped and non-skewed
+				rasters, this gives the same answer as ST_Envelope so only useful for irregularly shaped or skewed rasters.</refpurpose>
+			</refnamediv>
+		
+			<refsynopsisdiv>
+				<funcsynopsis>
+				  <funcprototype>
+					<funcdef>geometry <function>ST_ConvexHull</function></funcdef>
+					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+				  </funcprototype>
+				</funcsynopsis>
+			</refsynopsisdiv>
+		
+			<refsection>
+				<title>Description</title>
+				
+				<para>Return the convex hull geometry of the raster including the NoDataBandValue band pixels. For regular shaped and non-skewed
+				rasters, this gives more or less the same answer as ST_Envelope 
+				so only useful for irregularly shaped or skewed rasters.</para>
+				
+				<para><note>ST_Envelope floors the coordinates and hence add a little buffer around the raster so the answer is subtley 
+					different from ST_ConvexHull which does not floor.</note>
+				</para>
+			</refsection>
+				
+				<refsection>
+					<title>Examples</title>
+				<informaltable>
+				  <tgroup cols="2">
+					<tbody>
+					  <row>
+						<entry>
+							<para> <!-- TODO: Put in pictures -->
+<programlisting>-- Note envelope and convexhull are more or less the same
+SELECT ST_AsText(ST_ConvexHull(rast)) As convhull, 
+	ST_AsText(ST_Envelope(rast)) As env
+FROM dummy_rast WHERE rid=1;
+
+                        convhull                        |                env
+
+--------------------------------------------------------+-----------------------
+ POLYGON((0.5 0.5,20.5 0.5,20.5 60.5,0.5 60.5,0.5 0.5)) | POLYGON((0 0,20 0,20 60,0 60,0 0))
+ </programlisting>
+						</para>
+					</entry>
+
+					<entry>
+						<para> <!-- TODO: Put in pictures -->
+				<programlisting> 
+-- now we skew the raster 
+-- note how the convex hull and envelope are now different
+SELECT ST_AsText(ST_ConvexHull(rast)) As convhull, 
+	ST_AsText(ST_Envelope(rast)) As env
+FROM (SELECT ST_SetRotation(rast,0.1,0.1) As rast 
+	FROM dummy_rast WHERE rid=1) As foo;
+	
+                        convhull                        |                env
+
+--------------------------------------------------------+------------------------------------
+ POLYGON((0.5 0.5,20.5 1.5,22.5 61.5,2.5 60.5,0.5 0.5)) | POLYGON((0 0,22 0,22 61,0 61,0 0))
+				</programlisting>
+						</para>
+					</entry>
+			</row>
+		</tbody>
+		</tgroup>
+		</informaltable>
+			</refsection>
+		
+			<!-- Optionally add a "See Also" section -->
+			<refsection>
+				<title>See Also</title>
+				<para><xref linkend="RT_ST_Envelop" />, <xref linkend="ST_ConvexHull" />, <xref linkend="ST_AsText" /></para>
+			</refsection>
+		</refentry>
+	</sect1>
 </chapter>