From: Sandro Santilli <strk@keybit.net>
Date: Fri, 5 Feb 2010 17:57:20 +0000 (+0000)
Subject: Document ST_IsValidDetail
X-Git-Tag: 2.0.0alpha1~3275
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=cc5170bdf6a9819353d3ac0a78acfb0f5a3990d2;p=postgis

Document ST_IsValidDetail

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

diff --git a/doc/reference_accessor.xml b/doc/reference_accessor.xml
index ede5458d5..ba3be94a5 100644
--- a/doc/reference_accessor.xml
+++ b/doc/reference_accessor.xml
@@ -953,7 +953,12 @@ NOTICE:  Self-intersection at or near point 0 0
 	  <refsection>
 		<title>See Also</title>
 
-		<para><xref linkend="ST_IsSimple" />, <xref linkend="ST_IsValidReason" />, <xref linkend="ST_Summary" /></para>
+		<para>
+<xref linkend="ST_IsSimple" />,
+<xref linkend="ST_IsValidReason" />,
+<xref linkend="ST_IsValidDetail" />,
+<xref linkend="ST_Summary" />
+</para>
 	  </refsection>
 	</refentry>
 
@@ -1032,6 +1037,84 @@ SELECT ST_IsValidReason('LINESTRING(220227 150406,2220227 150407,222020 150410)'
 	  </refsection>
 	</refentry>
 
+	<refentry id="ST_IsValidDetail">
+	  <refnamediv>
+		<refname>ST_IsValidDetail</refname>
+
+		<refpurpose>Returns a valid_detail (valid,reason,location) row stating if a geometry is valid or not and if not valid, a reason why and a location where.</refpurpose>
+	  </refnamediv>
+
+	  <refsynopsisdiv>
+		<funcsynopsis>
+		  <funcprototype>
+			<funcdef>valid_detail <function>ST_IsValidDetail</function></funcdef>
+			<paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+		  </funcprototype>
+		</funcsynopsis>
+	  </refsynopsisdiv>
+
+	  <refsection>
+		<title>Description</title>
+
+		<para>Returns a valid_detail row, formed by a boolean (valid) stating if a geometry is valid, a varchar (reason) stating a reason why it is invalid and a geometry (location) pointing out where it is invalid.</para>
+
+		<para>Useful to substitute and improve the combination of ST_IsValid and ST_IsValidReason to generate a detailed report of invalid geometries.</para>
+		<para>Availability: 2.0.0 - requires GEOS &gt;= 3.3.0.</para>
+
+	  </refsection>
+
+
+	  <refsection>
+		<title>Examples</title>
+
+		<programlisting>
+--First 3 Rejects from a successful quintuplet experiment
+SELECT gid, reason(ST_IsValidDetail(the_geom)), ST_AsText(location(ST_IsValidDetail(the_geom))) as location 
+FROM
+(SELECT ST_MakePolygon(ST_ExteriorRing(e.buff), ST_Accum(f.line)) As the_geom, gid
+FROM (SELECT ST_Buffer(ST_MakePoint(x1*10,y1), z1) As buff, x1*10 + y1*100 + z1*1000 As gid
+	FROM generate_series(-4,6) x1
+	CROSS JOIN generate_series(2,5) y1
+	CROSS JOIN generate_series(1,8) z1
+	WHERE x1 &gt; y1*0.5 AND z1 &lt; x1*y1) As e
+	INNER JOIN (SELECT ST_Translate(ST_ExteriorRing(ST_Buffer(ST_MakePoint(x1*10,y1), z1)),y1*1, z1*2) As line
+	FROM generate_series(-3,6) x1
+	CROSS JOIN generate_series(2,5) y1
+	CROSS JOIN generate_series(1,10) z1
+	WHERE x1 &gt; y1*0.75 AND z1 &lt; x1*y1) As f
+ON (ST_Area(e.buff) &gt; 78 AND ST_Contains(e.buff, f.line))
+GROUP BY gid, e.buff) As quintuplet_experiment
+WHERE ST_IsValid(the_geom) = false
+ORDER BY gid
+LIMIT 3;
+
+ gid  |      reason       |  location
+------+-------------------+-------------
+ 5330 | Self-intersection | POINT(32 5)
+ 5340 | Self-intersection | POINT(42 5)
+ 5350 | Self-intersection | POINT(52 5)
+
+ --simple example
+SELECT * FROM ST_IsValidDetail('LINESTRING(220227 150406,2220227 150407,222020 150410)');
+
+ valid | reason | location
+-------+--------+----------
+ t     |        |
+
+		</programlisting>
+	  </refsection>
+
+	  <!-- Optionally add a "See Also" section -->
+	  <refsection>
+		<title>See Also</title>
+
+		<para>
+<xref linkend="ST_IsValid" />,
+<xref linkend="ST_IsValidReason" />
+</para>
+	  </refsection>
+	</refentry>
+
 	<refentry id="ST_M">
 	  <refnamediv>
 		<refname>ST_M</refname>
@@ -1637,7 +1720,11 @@ Line[ZB] with 2 points : Polygon[ZB] with 1 rings
 	  <refsection>
 		<title>See Also</title>
 
-		<para><xref linkend="ST_IsValid" />, <xref linkend="ST_IsValidReason" /></para>
+		<para>
+<xref linkend="ST_IsValid" />,
+<xref linkend="ST_IsValidReason" />,
+<xref linkend="ST_IsValidDetail" />
+</para>
 	  </refsection>
 	</refentry>