[postgis-tickets] r14856 - #3424, ST_MinimumClearance
Daniel Baston
dbaston at gmail.com
Mon Apr 25 14:02:24 PDT 2016
Author: dbaston
Date: 2016-04-25 14:02:23 -0700 (Mon, 25 Apr 2016)
New Revision: 14856
Modified:
trunk/NEWS
trunk/doc/introduction.xml
trunk/doc/reference_measure.xml
trunk/postgis/lwgeom_geos.c
trunk/postgis/postgis.sql.in
trunk/regress/Makefile.in
Log:
#3424, ST_MinimumClearance
Modified: trunk/NEWS
===================================================================
--- trunk/NEWS 2016-04-22 09:46:38 UTC (rev 14855)
+++ trunk/NEWS 2016-04-25 21:02:23 UTC (rev 14856)
@@ -16,6 +16,7 @@
- #3339 ST_GeneratePoints (Paul Ramsey)
- #3362 ST_ClusterDBSCAN (Dan Baston)
- #3364 ST_GeometricMedian (Dan Baston)
+ - #3424 ST_MinimumClearance (Dan Baston)
- #3428 ST_Points (Dan Baston)
- #3465 ST_ClusterKMeans (Paul Ramsey)
- #3469 ST_MakeLine with MULTIPOINTs (Paul Norman)
Modified: trunk/doc/introduction.xml
===================================================================
--- trunk/doc/introduction.xml 2016-04-22 09:46:38 UTC (rev 14855)
+++ trunk/doc/introduction.xml 2016-04-25 21:02:23 UTC (rev 14856)
@@ -264,6 +264,7 @@
Lidwala Consulting Engineers,
LisaSoft,
Logical Tracking & Tracing International AG,
+Maponics,
Michigan Tech Research Institute,
Natural Resources Canada,
Norwegian Forest and Landscape Institute,
Modified: trunk/doc/reference_measure.xml
===================================================================
--- trunk/doc/reference_measure.xml 2016-04-22 09:46:38 UTC (rev 14855)
+++ trunk/doc/reference_measure.xml 2016-04-25 21:02:23 UTC (rev 14856)
@@ -2361,6 +2361,133 @@
</refsection>
</refentry>
+ <refentry id="ST_MinimumClearance">
+ <refnamediv>
+ <refname>ST_MinimumClearance</refname>
+ <refpurpose>Returns the minimum clearance of a geometry, a measure a geometry's robustness.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float <function>ST_MinimumClearance</function></funcdef>
+ <paramdef><type>geometry </type><parameter>g</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>
+ It is not uncommon to have a geometry that, while meeting the criteria for validity according to ST_IsValid (polygons)
+ or ST_IsSimple (lines), would become invalid if one of the vertices moved by a slight distance, as can happen during
+ conversion to text-based formats (such as WKT, KML, GML GeoJSON), or binary formats that do not use double-precision
+ floating point coordinates (MapInfo TAB).
+ </para>
+
+ <para>
+ A geometry's "minimum clearance" is the smallest distance by which a vertex of the geometry could be moved to produce
+ an invalid geometry. It can be thought of as a quantitative measure of a geometry's robustness, where increasing values
+ of minimum clearance indicate increasing robustness.
+ </para>
+
+ <para>
+ If a geometry has a minimum clearance of <varname>e</varname>, it can be said that:
+ <itemizedlist>
+ <listitem>
+ <para>
+ No two distinct vertices in the geometry are separated by less than <varname>e</varname>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ No vertex is closer than <varname>e</varname> to a line segement of which it is not an endpoint.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ If no minimum clearance exists for a geometry (for example, a single point, or a multipoint whose points are identical), then
+ ST_MinimumClearance will return Infinity.
+ </para>
+
+ <para>Availability: 2.3.0 - requires GEOS >= 3.6.0</para>
+
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <programlisting>
+SELECT ST_MinimumClearance('POLYGON ((0 0, 1 0, 1 1, 0.5 3.2e-4, 0 0))');
+ st_minimumclearance
+---------------------
+ 0.00032
+ </programlisting>
+
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+
+ <para>
+ <xref linkend="ST_MinimumClearanceLine" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="ST_MinimumClearanceLine">
+ <refnamediv>
+ <refname>ST_MinimumClearanceLine</refname>
+ <refpurpose>Returns the two-point LineString spanning a geometry's minimum clearance.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>Geometry <function>ST_MinimumClearanceLine</function></funcdef>
+
+ <paramdef><type>geometry </type>
+ <parameter>g</parameter></paramdef>
+
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>
+ Returns the two-point LineString spanning a geometry's minimum clearance. If the geometry does not have a minimum
+ clearance, <varname>LINESTRING EMPTY</varname> will be returned.
+ </para>
+
+ <para>Availability: 2.3.0 - requires GEOS >= 3.6.0</para>
+
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <programlisting>
+SELECT ST_AsText(ST_MinimumClearanceLine('POLYGON ((0 0, 1 0, 1 1, 0.5 3.2e-4, 0 0))'));
+st_astext
+-------------------------------
+LINESTRING(0.5 0.00032,0.5 0)
+ </programlisting>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+
+ <para>
+ <xref linkend="ST_MinimumClearance" />
+ </para>
+ </refsection>
+
+ </refentry>
+
+
<refentry id="ST_HausdorffDistance">
<refnamediv>
<refname>ST_HausdorffDistance</refname>
Modified: trunk/postgis/lwgeom_geos.c
===================================================================
--- trunk/postgis/lwgeom_geos.c 2016-04-22 09:46:38 UTC (rev 14855)
+++ trunk/postgis/lwgeom_geos.c 2016-04-25 21:02:23 UTC (rev 14856)
@@ -3662,3 +3662,98 @@
#endif /* POSTGIS_GEOS_VERSION >= 35 */
}
+
+/******************************************
+ *
+ * ST_MinimumClearance
+ *
+ * Returns the minimum clearance of a geometry.
+ *
+ ******************************************/
+Datum ST_MinimumClearance(PG_FUNCTION_ARGS);
+PG_FUNCTION_INFO_V1(ST_MinimumClearance);
+Datum ST_MinimumClearance(PG_FUNCTION_ARGS)
+{
+#if POSTGIS_GEOS_VERSION < 36
+ lwpgerror("The GEOS version this PostGIS binary "
+ "was compiled against (%d) doesn't support "
+ "'ST_MinimumClearance' function (3.6.0+ required)",
+ POSTGIS_GEOS_VERSION);
+ PG_RETURN_NULL();
+#else /* POSTGIS_GEOS_VERSION >= 36 */
+ GSERIALIZED* input;
+ GEOSGeometry* input_geos;
+ int error;
+ double result;
+
+ initGEOS(lwpgnotice, lwgeom_geos_error);
+
+ input = PG_GETARG_GSERIALIZED_P(0);
+ input_geos = POSTGIS2GEOS(input);
+ if (!input_geos) /* exception thrown at construction */
+ {
+ HANDLE_GEOS_ERROR("Geometry could not be converted to GEOS");
+ PG_RETURN_NULL();
+ }
+
+ error = GEOSMinimumClearance(input_geos, &result);
+ GEOSGeom_destroy(input_geos);
+ if (error)
+ {
+ HANDLE_GEOS_ERROR("Error computing minimum clearance");
+ PG_RETURN_NULL();
+ }
+
+ PG_FREE_IF_COPY(input, 0);
+ PG_RETURN_FLOAT8(result);
+#endif
+}
+
+/******************************************
+ *
+ * ST_MinimumClearanceLine
+ *
+ * Returns the minimum clearance line of a geometry.
+ *
+ ******************************************/
+Datum ST_MinimumClearanceLine(PG_FUNCTION_ARGS);
+PG_FUNCTION_INFO_V1(ST_MinimumClearanceLine);
+Datum ST_MinimumClearanceLine(PG_FUNCTION_ARGS)
+{
+#if POSTGIS_GEOS_VERSION < 36
+ lwpgerror("The GEOS version this PostGIS binary "
+ "was compiled against (%d) doesn't support "
+ "'ST_MinimumClearanceLine' function (3.6.0+ required)",
+ POSTGIS_GEOS_VERSION);
+ PG_RETURN_NULL();
+#else /* POSTGIS_GEOS_VERSION >= 36 */
+ GSERIALIZED* input;
+ GSERIALIZED* result;
+ GEOSGeometry* input_geos;
+ GEOSGeometry* result_geos;
+
+ initGEOS(lwpgnotice, lwgeom_geos_error);
+
+ input = PG_GETARG_GSERIALIZED_P(0);
+ input_geos = POSTGIS2GEOS(input);
+ if (!input_geos) /* exception thrown at construction */
+ {
+ HANDLE_GEOS_ERROR("Geometry could not be converted to GEOS");
+ PG_RETURN_NULL();
+ }
+
+ result_geos = GEOSMinimumClearanceLine(input_geos);
+ GEOSGeom_destroy(input_geos);
+ if (!result_geos)
+ {
+ HANDLE_GEOS_ERROR("Error computing minimum clearance");
+ PG_RETURN_NULL();
+ }
+
+ result = GEOS2POSTGIS(result_geos, LW_FALSE);
+ GEOSGeom_destroy(result_geos);
+
+ PG_FREE_IF_COPY(input, 0);
+ PG_RETURN_POINTER(result);
+#endif
+}
Modified: trunk/postgis/postgis.sql.in
===================================================================
--- trunk/postgis/postgis.sql.in 2016-04-22 09:46:38 UTC (rev 14855)
+++ trunk/postgis/postgis.sql.in 2016-04-25 21:02:23 UTC (rev 14856)
@@ -4001,6 +4001,18 @@
LANGUAGE 'c' IMMUTABLE STRICT
COST 100;
+-- Availability: 2.3.0
+CREATE OR REPLACE FUNCTION ST_MinimumClearance(geometry)
+ RETURNS float8
+ AS 'MODULE_PATHNAME', 'ST_MinimumClearance'
+ LANGUAGE 'c' IMMUTABLE STRICT;
+
+-- Availability: 2.3.0
+CREATE OR REPLACE FUNCTION ST_MinimumClearanceLine(geometry)
+ RETURNS geometry
+ AS 'MODULE_PATHNAME', 'ST_MinimumClearanceLine'
+ LANGUAGE 'c' IMMUTABLE STRICT;
+
-- PostGIS equivalent function: Centroid(geometry)
CREATE OR REPLACE FUNCTION ST_Centroid(geometry)
RETURNS geometry
Modified: trunk/regress/Makefile.in
===================================================================
--- trunk/regress/Makefile.in 2016-04-22 09:46:38 UTC (rev 14855)
+++ trunk/regress/Makefile.in 2016-04-25 21:02:23 UTC (rev 14856)
@@ -216,6 +216,12 @@
voronoi
endif
+ifeq ($(shell expr $(POSTGIS_GEOS_VERSION) ">=" 36),1)
+ # GEOS-3.6 adds:
+ # ST_MinimumClearance
+ TESTS += \
+ minimum_clearance
+endif
ifeq ($(HAVE_JSON),yes)
# JSON-C adds:
More information about the postgis-tickets
mailing list