From: Regina Obe <lr@pcorp.us>
Date: Fri, 11 Mar 2011 12:26:04 +0000 (+0000)
Subject: document GetFaceByPoint and revise release_notes
X-Git-Tag: 2.0.0alpha1~1908
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=ed69058a39be26a14a4d975cd9823888d4299ab1;p=postgis

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 eeaecf27d..6d0731db9 100644
--- 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 8296bea28..9d302d6a6 100644
--- 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>