document GetFaceByPoint and revise release_notes

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

diff --git a/doc/extras_topology.xml b/doc/extras_topology.xml
index eeaecf27d60a6b3cfbbc25235467776952a905b0..6d0731db9e5e84c18785bfb199254dc54b03ffef 100644 (file)
--- a/doc/extras_topology.xml
+++ b/doc/extras_topology.xml
@@ -1037,7 +1037,7 @@ SELECT topology.AddTopoGeometryColumn('ri_topo', 'ri', 'roads', 'topo', 'LINE');
         
             <!-- optionally mention that this function uses indexes if appropriate -->
             <note>
-              <para>If tolerance = 0, the function use ST_Intersect otherwise use the ST_DWithin.</para>
+              <para>If tolerance = 0, the function use ST_Intersects otherwise uses ST_DWithin.</para>
             </note>
             <!-- use this format if new function -->
             <para>Availability: 2.0.0 - requires GEOS &gt;= 3.3.0. </para>
@@ -1068,6 +1068,57 @@ ERROR:  Two or more edges found</programlisting>
           </refsection>
         </refentry>
         
+        <refentry id="GetFaceByPoint">
+               <refnamediv>
+                       <refname>GetFaceByPoint</refname>
+                       <refpurpose>Find the face-id of a face that intersects a given point</refpurpose>
+               </refnamediv>
+               <refsynopsisdiv>
+                       <funcsynopsis>
+                               <funcprototype>
+                                       <funcdef>integer <function>GetFaceByPoint</function></funcdef>
+                                       <paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
+                                       <paramdef><type>geometry </type> <parameter>apoint</parameter></paramdef>
+                                       <paramdef><type>float8 </type> <parameter>tol</parameter></paramdef>
+                               </funcprototype>
+                       </funcsynopsis>
+               </refsynopsisdiv>
+               <refsection>
+                       <title>Retrieve the id of a face that intersects a Point</title>
+                       <para>The function returns an integer (id-face) given a topology, a POINT and a tolerance. If tolerance = 0 then the point has to intersect the face.</para>
+                       <para>If the point is the location of a node, then an exception is thrown. To avoid this run the GetNodeByPoint function.</para>
+                       <para>If the point doesn't intersect a face, returns 0 (zero).</para>
+                       <para>If use tolerance > 0 and there is more than one face near the point then an exception is thrown.</para>
+                       
+                       <!-- optionally mention that this function uses indexes if appropriate -->
+                       <note>
+                               <para>If tolerance = 0, the function uses ST_Intersects otherwise uses ST_DWithin.</para>
+                       </note>
+                       <!-- use this format if new function -->
+                       <para>Availability: 2.0.0 - requires GEOS &gt;= 3.3.0. </para>
+               </refsection>
+               <refsection>
+                       <title>Examples</title>
+                       <para>These examples use edges faces created in <xref linkend="AddFace" /></para>
+                       <programlisting>SELECT topology.GetFaceByPoint('ma_topo',geom, 10) As with1mtol, topology.GetFaceByPoint('ma_topo',geom,0) As withnotol
+       FROM ST_GeomFromEWKT('SRID=-1;POINT(234604.6 899382.0)') As geom;
+       
+        with1mtol | withnotol
+       -----------+-----------
+                        1 |         0</programlisting>
+                       <programlisting>SELECT topology.GetFaceByPoint('ma_topo',geom, 1) As nearnode
+       FROM ST_GeomFromEWKT('SRID=-1;POINT(227591.9 893900.4)') As geom;
+       
+-- get error --
+ERROR:  Two or more faces found</programlisting>
+               </refsection>
+               <!-- Optionally add a "See Also" section -->
+               <refsection>
+                       <title>See Also</title>
+                       <para><xref linkend="AddFace" />,<xref linkend="GetNodeByPoint" />,<xref linkend="GetEdgeByPoint" /></para>
+               </refsection>
+       </refentry>
+        
         <refentry id="GetNodeByPoint">
           <refnamediv>
             <refname>GetNodeByPoint</refname>

diff --git a/doc/release_notes.xml b/doc/release_notes.xml
index 8296bea288cd31aaac92ad64a9041741588fadc6..9d302d6a6c151b65626f7110ce963aefe543bee7 100644 (file)
--- a/doc/release_notes.xml
+++ b/doc/release_notes.xml
@@ -24,7 +24,7 @@
           <para>Raster support integrated and documented
                        (Pierre Racine, Jorge Arévalo, Mateusz Loskot, Sandro Santilli, Regina Obe)</para>
           <para>Making spatial indexes 3D aware - in progress (Paul Ramsey, Mark Cave-Ayland)</para>
-          <para>Topology support improved, documented, testing (Sandro Santilli / Faunalia for RT-SIGTA, Regina Obe, Andrea Peri)</para>
+          <para>Topology support improved (more functions), documented, testing (Sandro Santilli / Faunalia for RT-SIGTA), Andrea Peri, Regina Obe)</para>
           <para>3D relationship support functions  (Nicklas Avén)</para>
           <para>   ST_3DDistance, ST_3DClosestPoint, ST_3DIntersects, ST_3DShortestLine and more...</para>
           <para>ST_Split (Sandro Santilli / Faunalia for RT-SIGTA)</para>
@@ -32,7 +32,7 @@
           <para>ST_MakeValid (Sandro Santilli / Faunalia for RT-SIGTA)</para>
           <para>ST_RemoveRepeatedPoints (Sandro Santilli / Faunalia for RT-SIGTA)</para>
           <para>ST_GeometryN and ST_NumGeometries support for non-collections (Sandro Santilli)</para>
-          <para>ST_isCollection (Sandro Santilli, Maxime van Noppen)</para>
+          <para>ST_IssCollection (Sandro Santilli, Maxime van Noppen)</para>
           <para>ST_SharedPaths (Sandro Santilli / Faunalia for RT-SIGTA)</para>
           <para>ST_Snap (Sandro Santilli)</para>
           <para>ST_RelateMatch (Sandro Santilli / Faunalia for RT-SIGTA)</para>