[postgis-tickets] [SCM] PostGIS branch master updated. 3.1.0rc1-74-g14256dc
git at osgeo.org
git at osgeo.org
Fri Feb 12 11:22:30 PST 2021
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "PostGIS".
The branch, master has been updated
via 14256dc9cc83d23578ba1016eaadda4297ccb9ed (commit)
from b5bf441e96ee86b958fcc3b3d0f265c6b7dd69fb (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 14256dc9cc83d23578ba1016eaadda4297ccb9ed
Author: Martin Davis <mtnclimb at gmail.com>
Date: Fri Feb 12 11:22:21 2021 -0800
Improve doc for MinClearance, ReducePrecision
diff --git a/doc/reference_measure.xml b/doc/reference_measure.xml
index 4bc966e..416e259 100644
--- a/doc/reference_measure.xml
+++ b/doc/reference_measure.xml
@@ -1572,37 +1572,44 @@ SELECT ST_3DMaxDistance(
<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).
+ It is possible for a geometry to meet the criteria for validity according to <xref linkend="ST_IsValid" /> (polygons)
+ or <xref linkend="ST_IsSimple" /> (lines),
+ but to become invalid if one of its vertices is moved by a small distance.
+ This can happen due to loss of precision during conversion to text formats (such as WKT, KML, GML, GeoJSON),
+ or binary formats that do not use double-precision floating point coordinates (e.g. 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.
+ The minimum clearance is a quantitative measure of a geometry's robustness to change in coordinate precision.
+ It is the largest distance by which vertices of the geometry can be moved without creating an invalid geometry.
+ Larger values of minimum clearance indicate greater 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>
+ If a geometry has a minimum clearance of <varname>e</varname>, then:
+ <itemizedlist>
+ <listitem>
+ <para>
+ No two distinct vertices in the geometry are closer than the distance <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.
+ If no minimum clearance exists for a geometry (e.g. a single point, or a multipoint whose points are identical),
+ the return value is <varname>Infinity</varname>.
+ </para>
+
+ <para>
+ To avoid validity issues caused by precision loss,
+ <xref linkend="ST_ReducePrecision" /> can reduce coordinate precision
+ while ensuring that polygonal geometry remains valid.
</para>
<para>Availability: 2.3.0</para>
@@ -1624,7 +1631,10 @@ SELECT ST_MinimumClearance('POLYGON ((0 0, 1 0, 1 1, 0.5 3.2e-4, 0 0))');
<title>See Also</title>
<para>
- <xref linkend="ST_MinimumClearanceLine" />
+ <xref linkend="ST_MinimumClearanceLine" />,
+ <xref linkend="ST_IsSimple" />,
+ <xref linkend="ST_IsValid" />,
+ <xref linkend="ST_ReducePrecision" />
</para>
</refsection>
</refentry>
diff --git a/doc/reference_processing.xml b/doc/reference_processing.xml
index 37612b7..00a489c 100644
--- a/doc/reference_processing.xml
+++ b/doc/reference_processing.xml
@@ -1920,7 +1920,7 @@ geomtextrep
<refnamediv>
<refname>ST_ReducePrecision</refname>
- <refpurpose>Returns a valid geometry with all points rounded to the provided grid tolerance.</refpurpose>
+ <refpurpose>Returns a valid geometry with points rounded to a grid tolerance.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -1943,6 +1943,27 @@ geomtextrep
<para>Unlike <xref linkend="ST_SnapToGrid" /> the returned geometry will be valid, with no ring self-intersections or collapsed components.</para>
+ <para>
+ Precision reduction can be used to:
+ <itemizedlist>
+ <listitem><para>
+ match coordinate precision to the data accuracy
+ </para></listitem>
+ <listitem><para>
+ reduce the number of coordinates needed to represent a geometry
+ </para></listitem>
+ <listitem><para>
+ ensure valid geometry output to formats which use lower precision
+ (e.g. text formats such as WKT, GeoJSON or KML
+ when the number of output decimal places is limited).
+ </para></listitem>
+ <listitem><para>
+ export valid geometry to systems which use lower or limited precision
+ (e.g. SDE, Oracle tolerance value)
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
<para>Availability: 3.1.0 - requires GEOS >= 3.9.0. </para>
</refsection>
-----------------------------------------------------------------------
Summary of changes:
doc/reference_measure.xml | 56 ++++++++++++++++++++++++++------------------
doc/reference_processing.xml | 23 +++++++++++++++++-
2 files changed, 55 insertions(+), 24 deletions(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list