give example of ST_3DArea

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

diff --git a/doc/reference_sfcgal.xml b/doc/reference_sfcgal.xml
index 8e1c14207350f25ea9bf0cac168d044de019e897..23795544dd7b547e698d7c98f10c08aed7294e32 100644 (file)
--- a/doc/reference_sfcgal.xml
+++ b/doc/reference_sfcgal.xml
@@ -612,7 +612,7 @@ FROM  ST_GeomFromText('LINESTRING Z (2 2 6,1.5 1.5 7,1 1 8,0.5 0.5 8,0 0 10)') A
          <refnamediv>
                <refname>ST_3DArea</refname>
 
-               <refpurpose>Computes area of 3D geometries</refpurpose>
+               <refpurpose>Computes area of 3D surface geometries.  Will return 0 for solids.</refpurpose>
          </refnamediv>
 
          <refsynopsisdiv>
@@ -633,7 +633,28 @@ FROM  ST_GeomFromText('LINESTRING Z (2 2 6,1.5 1.5 7,1 1 8,0.5 0.5 8,0 0 10)') A
                <para>&P_support;</para>
                <para>&T_support;</para>
          </refsection>
+         
+         <refsection><title>Examples</title>
+         <para>Note: By default a PolyhedralSurface built from WKT is a surface geometry, not solid.  It therefore has surface area.  Once converted to a solid, no area.</para>
+<programlisting>SELECT ST_3DArea(geom) As cube_surface_area, 
+       ST_3DArea(ST_MakeSolid(geom)) As solid_surface_area
+  FROM (SELECT 'POLYHEDRALSURFACE( ((0 0 0, 0 0 1, 0 1 1, 0 1 0, 0 0 0)), 
+    ((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)), 
+    ((0 0 0, 1 0 0, 1 0 1, 0 0 1, 0 0 0)), 
+    ((1 1 0, 1 1 1, 1 0 1, 1 0 0, 1 1 0)), 
+    ((0 1 0, 0 1 1, 1 1 1, 1 1 0, 0 1 0)), 
+    ((0 0 1, 1 0 1, 1 1 1, 0 1 1, 0 0 1)) )'::geometry) As f(geom);
+    
+ cube_surface_area | solid_surface_area
+-------------------+--------------------
+                 6 |                  0    </programlisting>
+         
+         </refsection>
+         <refsection>
+               <title>See Also</title>
 
+               <para><xref linkend="ST_Area" />, <xref linkend="ST_MakeSolid" />, <xref linkend="ST_IsSolid" />, <xref linkend="ST_Area" /></para>
+         </refsection>
        </refentry>
 
        <refentry id="ST_Tesselate">