[postgis-commits] svn - r2818 - branches/1.3/doc

[postgis-commits at postgis.refractions.net]

Author: robe
Date: 2008-06-30 08:34:38 -0700 (Mon, 30 Jun 2008)
New Revision: 2818

Modified:
   branches/1.3/doc/postgis.xml
Log:
Same changes as in trunk

Modified: branches/1.3/doc/postgis.xml
===================================================================
--- branches/1.3/doc/postgis.xml	2008-06-30 15:30:17 UTC (rev 2817)
+++ branches/1.3/doc/postgis.xml	2008-06-30 15:34:38 UTC (rev 2818)
@@ -3181,8 +3181,8 @@
 			  <para>It is usually used with MULTI and Geometry Collections.  Although it is not an aggregate - you can use it in conjunction with ST_Collect to get the convex hull of a set of points.  ST_ConvexHull(ST_Collect(somepointfield)).  It is often used to determine an affected area based on a set of point observations.
 			  </para>
 			  <programlisting>SELECT d.disease_type, ST_ConvexHull(ST_Collect(d.the_geom)) As the_geom 
-			  		FROM disease_obs As d 
-					GROUP BY d.disease_type</programlisting>
+	FROM disease_obs As d 
+	GROUP BY d.disease_type</programlisting>
 			  
               <para>Performed by the GEOS module</para>
 
@@ -3218,8 +3218,8 @@
             <term>ST_SymDifference(geometry A, geometry B)</term>
 
             <listitem>
-              <para>Returns a geometry that represents the point set symmetric
-              difference of Geometry A with Geometry B.</para>
+              <para>Returns a geometry that represents the portions of A and B that do not intersect.  It is 
+			  called a symmetric difference because ST_SymDifference(A,B) = ST_SymDifference(B,A).</para>
 
               <para>Performed by the GEOS module</para>
 
@@ -3233,8 +3233,8 @@
             <term>ST_Difference(geometry A, geometry B)</term>
 
             <listitem>
-              <para>Returns a geometry that represents the point set
-              difference of Geometry A with Geometry B.</para>
+              <para>Returns a geometry that represents that part of geometry A that does not intersect
+			  	with geometry B.</para>
 
               <para>Performed by the GEOS module</para>
 
@@ -4619,11 +4619,27 @@
               <para>This function returns a GEOMETRYCOLLECTION or a MULTI
               object from a set of geometries. The collect() function is an
               &quot;aggregate&quot; function in the terminology of PostgreSQL.
-              That means that it operators on lists of data, in the same way
+              That means that it operates on rows of data, in the same way
               the sum() and mean() functions do. For example, &quot;SELECT
               COLLECT(GEOM) FROM GEOMTABLE GROUP BY ATTRCOLUMN&quot; will
               return a separate GEOMETRYCOLLECTION for each distinct value of
               ATTRCOLUMN.</para>
+			  <para>ST_Collect and ST_Union are often interchangeable.  
+			  ST_Collect is in general orders of magnitude faster than ST_Union because it does not try to dissolve
+			  boundaries.  It merely rolls up single geometries into MULTI and MULTI or mixed geometry types into Geometry Collections.  
+			  Unfortunately geometry collections are not well-supported by 
+			  GIS tools.  To prevent ST_Collect from returning a Geometry Collection when collecting MULTI geometries, 
+			  one can use the below trick that utilizes ST_Dump to expand the MULTIs out to singles and then regroup them.
+			  </para>
+			  <programlisting>
+Thread ref: http://postgis.refractions.net/pipermail/postgis-users/2008-June/020331.html
+SELECT stusps, 
+	   ST_Multi(ST_Collect(f.the_geom)) as singlegeom  
+	 FROM (SELECT stusps, (ST_Dump(the_geom)).geom As the_geom 
+				FROM
+				somestatetable ) As f
+GROUP BY stusps
+			  </programlisting>
             </listitem>
           </varlistentry>
 
@@ -4649,6 +4665,15 @@
               input geometry is a collection or multi it will return a record
               for each of the collection components, and the path will express
               the position of the component inside the collection.</para>
+			  
+			  <para>ST_Dump is useful for expanding geometries.  It is the reverse of a GROUP BY in that
+			  	it creates new rows. For example it can be use to expand MULTIPOLYGONS into POLYGONS.</para>
+				
+			  <programlisting>
+SELECT sometable.*, (ST_Dump(the_geom)).geom As the_geom 
+	 FROM somestatetable
+			  </programlisting>
+				
 
               <para>Availability: PostGIS 1.0.0RC1. Requires PostgreSQL 7.3 or
               higher.</para>
@@ -6160,7 +6185,7 @@
           </listitem>
           <listitem>
 
-            <para>Attach the patch to a new issue in bug tracker.</command></para>
+            <para>Attach the patch to a new issue in bug tracker.</para>
 
           </listitem>
         </orderedlist>