[postgis-tickets] [SCM] PostGIS branch master updated. 3.3.0rc2-79-g3c6da820c
git at osgeo.org
git at osgeo.org
Tue Sep 13 12:38:34 PDT 2022
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 3c6da820cff397a6b19dc02cbb391a14d9cf418e (commit)
from ad456b38fe05c328e39e65e9481d66b0fa432593 (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 3c6da820cff397a6b19dc02cbb391a14d9cf418e
Author: Martin Davis <mtnclimb at gmail.com>
Date: Tue Sep 13 12:38:31 2022 -0700
Improve doc for spatial predicates
diff --git a/doc/reference_relationship.xml b/doc/reference_relationship.xml
index f3530c3f6..06f106c82 100644
--- a/doc/reference_relationship.xml
+++ b/doc/reference_relationship.xml
@@ -15,7 +15,7 @@
<refname>ST_3DIntersects</refname>
<refpurpose>Tests if two geometries spatially
- intersect in 3D - only for points, linestrings, polygons, polyhedral surface (area).
+ intersect in 3D - only for points, linestrings, polygons, polyhedral surface (area)
</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -77,7 +77,7 @@
<refnamediv>
<refname>ST_Contains</refname>
- <refpurpose>Tests if no points of B lie in the exterior of A, and A and B have at least one interior point in common. </refpurpose>
+ <refpurpose>Tests if every point of B lies in A, and their interiors have a point in common</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -97,22 +97,30 @@
<refsection>
<title>Description</title>
- <para>Returns TRUE if geometry B is completely inside geometry A.
- A contains B if and only if no points of B lie in the exterior of A, and at least one point of the interior of B lies in the interior of A.
- </para>
- <para>A subtlety of the definition is that a geometry does not contain things in its boundary.
- Thus polygons and lines do <emphasis>not</emphasis> contain lines and points lying in their boundary.
- For further details see <ulink url="http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html">Subtleties of OGC Covers, Contains, Within</ulink>.
- (The <xref linkend="ST_Covers" /> predicate provides a more inclusive relationship.)
- However, a geometry does contain itself.
- (In contrast, in the <xref linkend="ST_ContainsProperly" />
- predicate a geometry does <emphasis>not</emphasis> properly contain itself.)</para>
+ <para>Returns TRUE if geometry A contains geometry B.
+ A contains B if and only if all points of B lie inside (i.e. in the interior or boundary of) A
+ (or equivalently, no points of B lie in the exterior of A),
+ and the interiors of A and B have at least one point in common.
+ </para>
- <para>ST_Contains is the inverse of <xref linkend="ST_Within"/>.
- So, <code>ST_Contains(A,B) = ST_Within(B,A)</code>.</para>
+ <para>The contains relationship is reflexive: every geometry contains itself.
+ (In contrast, in the <xref linkend="ST_ContainsProperly" />
+ predicate a geometry does <emphasis>not</emphasis> properly contain itself.)
+ The relationship is antisymmetric: if <code>ST_Contains(A,B) = true</code> and <code>ST_Contains(B,A) = true</code>, then
+ the two geometries must be topologically equal (<code>ST_Equals(A,B) = true</code>).
+ </para>
- <note><para>&index_aware;
- To avoid index use, use the function <function>_ST_Contains</function>.</para></note>
+ <para>ST_Contains is the converse of <xref linkend="ST_Within"/>.
+ So, <code>ST_Contains(A,B) = ST_Within(B,A)</code>.</para>
+
+ <note><para>Because the interiors must have a common point, a subtlety of the definition is that
+ polygons and lines do <emphasis>not</emphasis> contain lines and points lying fully in their boundary.
+ For further details see <ulink url="http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html">Subtleties of OGC Covers, Contains, Within</ulink>.
+ The <xref linkend="ST_Covers" /> predicate provides a more inclusive relationship.
+ </para></note>
+
+ <note><para>&index_aware;
+ To avoid index use, use the function <function>_ST_Contains</function>.</para></note>
<para>Performed by the GEOS module</para>
<para>Enhanced: 2.3.0 Enhancement to PIP short-circuit extended to support MultiPoints with few points. Prior versions only supported point in polygon.</para>
@@ -188,7 +196,7 @@
</tgroup>
</informaltable>
- <para>The <function>ST_Contains</function> predicate returns <varname>FALSE</varname> in the following situations:</para>
+ <para><function>ST_Contains</function> returns <varname>FALSE</varname> in the following situations:</para>
<informaltable>
<tgroup cols="2">
@@ -261,7 +269,7 @@ ST_Point | t | t | f | f
<refnamediv>
<refname>ST_ContainsProperly</refname>
- <refpurpose>Tests if B intersects the interior of A but not the boundary or exterior. </refpurpose>
+ <refpurpose>Tests if every point of B lies in the interior of A</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -281,15 +289,16 @@ ST_Point | t | t | f | f
<refsection>
<title>Description</title>
- <para>Returns true if B intersects the interior of A but not the boundary or exterior.</para>
+ <para>Returns <varname>true</varname> if every point of B lies inside A
+ (or equivalently, no point of B lies in the the boundary or exterior of A).</para>
<para>A does not properly contain itself, but does contain itself.</para>
<para>Every point of the other geometry is a point of this geometry's interior. The DE-9IM Intersection Matrix for the two geometries matches
[T**FF*FF*] used in <xref linkend="ST_Relate" /></para>
<para>
- An example use case for this predicate is computing the intersections of a set of geometries with a large polygonal geometry. Since intersection is a fairly slow operation, it can be more efficient to use containsProperly to filter out test geometries which lie
- wholly inside the area. In these cases the intersection is known a priori to be exactly the original test geometry.
+ A use for this predicate is computing the intersections of a set of geometries with a large polygonal geometry. Since intersection is a fairly slow operation, it can be more efficient to use containsProperly to filter out test geometries which lie
+ fully inside the area. In these cases the intersection is known a priori to be exactly the original test geometry.
</para>
<note><para>&index_aware;
@@ -355,7 +364,7 @@ ST_Point | t | t | f | f
<refnamediv>
<refname>ST_CoveredBy</refname>
- <refpurpose>Tests if no point in A is outside B</refpurpose>
+ <refpurpose>Tests if every point of A lies in B</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -385,11 +394,18 @@ ST_Point | t | t | f | f
<refsection>
<title>Description</title>
- <para>Returns <varname>true</varname> if no point in Geometry/Geography A lies outside
- Geometry/Geography B.
- Equivalently, tests if every point of geometry A is inside
- (i.e. intersects the interior or boundary of) geometry B.
- </para>
+ <para>Returns <varname>true</varname> if every point in Geometry/Geography A lies inside
+ (i.e. intersects the interior or boundary of)
+ Geometry/Geography B.
+ Equivalently, tests that no point of A lies outside (in the exterior of) B.
+ </para>
+
+ <para>ST_CoveredBy is the converse of <xref linkend="ST_Covers"/>.
+ So, <code>ST_CoveredBy(A,B) = ST_Covers(B,A)</code>.</para>
+
+ <para>Generally this function should be used instead of <xref linkend="ST_Within"/>,
+ since it has a simpler definition
+ which does not have the quirk that "boundaries are not within their geometry".</para>
<note><para>&index_aware;
To avoid index use, use the function <function>_ST_CoveredBy</function>.</para></note>
@@ -437,7 +453,7 @@ FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc,
<refnamediv>
<refname>ST_Covers</refname>
- <refpurpose>Tests if no point in B is outside A</refpurpose>
+ <refpurpose>Tests if every point of B lies in A</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -466,12 +482,20 @@ FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc,
<refsection>
<title>Description</title>
- <para>Returns <varname>true</varname> if no point in Geometry/Geography B is outside
- Geometry/Geography A.
- Equivalently, tests if every point of geometry B is inside
- (i.e. intersects the interior or boundary of) geometry A.
+ <para>Returns <varname>true</varname> if every point in Geometry/Geography B lies inside
+ (i.e. intersects the interior or boundary of)
+ Geometry/Geography A.
+ Equivalently, tests that no point of B lies outside (in the exterior of) A.
</para>
+ <para>ST_Covers is the converse of <xref linkend="ST_CoveredBy"/>.
+ So, <code>ST_Covers(A,B) = ST_CoveredBy(B,A)</code>.</para>
+
+ <para>Generally this function should be used instead of <xref linkend="ST_Contains"/>,
+ since it has a simpler definition
+ which does not have the quirk that "geometries do not contain their boundary".</para>
+
+
<note><para>&index_aware;
To avoid index use, use the function <function>_ST_Covers</function>.</para></note>
@@ -535,8 +559,7 @@ SELECT ST_Covers(geog_poly, geog_pt) As poly_covers_pt,
<refnamediv>
<refname>ST_Crosses</refname>
- <refpurpose>Tests if two geometries have some, but not all,
- interior points in common.</refpurpose>
+ <refpurpose>Tests if two geometries have some, but not all, interior points in common</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -710,8 +733,7 @@ WHERE ST_Crosses(roads.geom, highways.geom);</programlisting>
<refnamediv>
<refname>ST_Disjoint</refname>
- <refpurpose>Tests if two geometries are disjoint (they have no point in common).
- </refpurpose>
+ <refpurpose>Tests if two geometries have no points in common </refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
@@ -777,7 +799,7 @@ SELECT ST_Disjoint('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::geometry);
<refnamediv>
<refname>ST_Equals</refname>
- <refpurpose>Tests if two geometries include the same set of points.</refpurpose>
+ <refpurpose>Tests if two geometries include the same set of points</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -842,9 +864,7 @@ SELECT ST_Equals(ST_Reverse(ST_GeomFromText('LINESTRING(0 0, 10 10)')),
<refnamediv>
<refname>ST_Intersects</refname>
- <refpurpose>Tests if two geometries
- intersect (they have at least one point in common).
- </refpurpose>
+ <refpurpose>Tests if two geometries intersect (they have at least one point in common)</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
@@ -961,7 +981,7 @@ t
<refnamediv>
<refname>ST_LineCrossingDirection</refname>
- <refpurpose>Returns a number indicating the crossing behavior of two LineStrings.</refpurpose>
+ <refpurpose>Returns a number indicating the crossing behavior of two LineStrings</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -1127,8 +1147,7 @@ WHERE ST_LineCrossingDirection(s1.geom, s2.geom) > 0;
<refnamediv>
<refname>ST_OrderingEquals</refname>
- <refpurpose>Tests if two geometries represent the same geometry
- and have points in the same directional order.</refpurpose>
+ <refpurpose>Tests if two geometries represent the same geometry and have points in the same directional order</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -1191,7 +1210,7 @@ SELECT ST_OrderingEquals(ST_Reverse(ST_GeomFromText('LINESTRING(0 0, 10 10)')),
<refnamediv>
<refname>ST_Overlaps</refname>
- <refpurpose>Tests if two geometries intersect and have the same dimension, but are not completely contained by each other.</refpurpose>
+ <refpurpose>Tests if two geometries have the same dimension and intersect, but each has at least one point not in the other</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -1209,10 +1228,10 @@ SELECT ST_OrderingEquals(ST_Reverse(ST_GeomFromText('LINESTRING(0 0, 10 10)')),
<para>Returns TRUE if geometry A and B "spatially overlap".
Two geometries overlap if they have the same dimension,
- each has at least one point not shared by the other
- (or equivalently neither covers the other),
- and the intersection of their interiors has the same dimension.
- The overlaps relationship is symmetrical.
+ their interiors intersect in that dimension.
+ and each has at least one point inside the other
+ (or equivalently, neither one covers the other).
+ The overlaps relationship is symmetric and irreflexive.
</para>
<note><para>&index_aware;
@@ -1595,7 +1614,7 @@ SELECT pat.name AS relationship, pat.val AS pattern,
<refname>ST_Touches</refname>
<refpurpose>Tests if two geometries have at least one point in common,
- but their interiors do not intersect.</refpurpose>
+ but their interiors do not intersect</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -1750,7 +1769,7 @@ SELECT ST_Touches('LINESTRING(0 0, 1 1, 0 2)'::geometry, 'POINT(0 2)'::geometry)
<refnamediv>
<refname>ST_Within</refname>
- <refpurpose>Tests if no points of A lie in the exterior of B, and A and B have at least one interior point in common.</refpurpose>
+ <refpurpose>Tests if every point of A lies in B, and their interiors have a point in common</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -1770,19 +1789,27 @@ SELECT ST_Touches('LINESTRING(0 0, 1 1, 0 2)'::geometry, 'POINT(0 2)'::geometry)
<refsection>
<title>Description</title>
- <para>Returns TRUE if geometry A is completely inside geometry B. For this function to make
+ <para>Returns TRUE if geometry A is within geometry B.
+ A is within B if and only if all points of A lie inside (i.e. in the interior or boundary of) B
+ (or equivalently, no points of A lie in the exterior of B),
+ and the interiors of A and B have at least one point in common.
+ </para>
+ <para>For this function to make
sense, the source geometries must both be of the same coordinate projection,
- having the same SRID. It is a given that if ST_Within(A,B) is true and ST_Within(B,A) is true, then
- the two geometries are considered spatially equal.</para>
+ having the same SRID.
+ </para>
+ <para>The within relationship is reflexive: every geometry is within itself.
+ The relationship is antisymmetric: if <code>ST_Within(A,B) = true</code> and <code>ST_Within(B,A) = true</code>, then
+ the two geometries must be topologically equal (<code>ST_Equals(A,B) = true</code>).</para>
- <para>A subtlety of this definition is that the boundary of a geometry is not within the geometry.
- This means that lines and points lying in the boundary of a polygon or line are <emphasis>not</emphasis> within the geometry.
- For further details see <ulink url="http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html">Subtleties of OGC Covers, Contains, Within</ulink>.
- (The <xref linkend="ST_CoveredBy" /> predicate provides a more inclusive relationship).
- </para>
+ <para>ST_Within is the converse of <xref linkend="ST_Contains"/>.
+ So, <code>ST_Within(A,B) = ST_Contains(B,A)</code>.</para>
- <para>ST_Within is the inverse of <xref linkend="ST_Contains"/>.
- So, <code>ST_Within(A,B) = ST_Contains(B,A)</code>.</para>
+ <note><para>Because the interiors must have a common point, a subtlety of the definition is that
+ lines and points lying fully in the boundary of polygons or lines are <emphasis>not</emphasis> within the geometry.
+ For further details see <ulink url="http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html">Subtleties of OGC Covers, Contains, Within</ulink>.
+ The <xref linkend="ST_CoveredBy" /> predicate provides a more inclusive relationship.
+ </para></note>
<note><para>&index_aware;
To avoid index use, use the function <function>_ST_Within</function>.</para></note>
@@ -2171,7 +2198,7 @@ SELECT b.tower_id, b.geom
<refnamediv>
<refname>ST_PointInsideCircle</refname>
- <refpurpose>Tests if a point geometry is inside a circle defined by a center and radius.</refpurpose>
+ <refpurpose>Tests if a point geometry is inside a circle defined by a center and radius</refpurpose>
</refnamediv>
<refsynopsisdiv>
-----------------------------------------------------------------------
Summary of changes:
doc/reference_relationship.xml | 149 ++++++++++++++++++++++++-----------------
1 file changed, 88 insertions(+), 61 deletions(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list