[postgis-tickets] [SCM] PostGIS branch master updated. 3.4.0beta2-13-g064e9b4ee
git at osgeo.org
git at osgeo.org
Tue Aug 1 09:22:45 PDT 2023
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 064e9b4ee7c42dd2a0ab0aff2f7c232d033ef014 (commit)
from a84f3d0e7eb67b5bcf40aa97833576e68873c6b3 (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 064e9b4ee7c42dd2a0ab0aff2f7c232d033ef014
Author: Martin Davis <mtnclimb at gmail.com>
Date: Tue Aug 1 09:22:44 2023 -0700
Improve doc for clustering functions
diff --git a/doc/reference_cluster.xml b/doc/reference_cluster.xml
index e382bb354..a24e965ec 100644
--- a/doc/reference_cluster.xml
+++ b/doc/reference_cluster.xml
@@ -149,21 +149,21 @@ GROUP BY cid;
<xref linkend="ST_ClusterIntersectingWin"/>
</para>
</refsection>
-
</refentry>
- <refentry id="ST_ClusterIntersectingWin">
+
+ <refentry id="ST_ClusterIntersecting">
<refnamediv>
- <refname>ST_ClusterIntersectingWin</refname>
+ <refname>ST_ClusterIntersecting</refname>
- <refpurpose>Window function that returns a cluster id for each input geometry, clustering input geometries into connected sets.</refpurpose>
+ <refpurpose>Aggregate function that clusters input geometries into connected sets.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
- <funcdef>integer <function>ST_ClusterIntersectingWin</function></funcdef>
- <paramdef><type>geometry winset </type> <parameter>geom</parameter></paramdef>
+ <funcdef>geometry[] <function>ST_ClusterIntersecting</function></funcdef>
+ <paramdef><type>geometry set</type> <parameter>g</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
@@ -171,62 +171,59 @@ GROUP BY cid;
<refsection>
<title>Description</title>
- <para>ST_ClusterIntersectingWin is a windowing function that builds inter-connecting clusters of geometries that intersect. It is possible to traverse all geometries in a cluster without leaving the cluster. The return value is the cluster number that the geometry argument participates in, or null for null inputs.</para>
+ <para>An aggregate function that returns an array of GeometryCollections
+ partitioning the input geometries into connected clusters that are disjoint.
+ Each geometry in a cluster intersects at least one other geometry in the cluster,
+ and does not intersect any geometry in other clusters.
+ </para>
- <para role="availability" conformance="3.4.0">Availability: 3.4.0</para>
+ <para role="availability" conformance="2.2.0">Availability: 2.2.0</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
-WITH testdata AS (
- SELECT id, geom::geometry FROM (
- VALUES (1, 'LINESTRING (0 0, 1 1)'),
- (2, 'LINESTRING (5 5, 4 4)'),
- (3, 'LINESTRING (6 6, 7 7)'),
- (4, 'LINESTRING (0 0, -1 -1)'),
- (5, 'POLYGON ((0 0, 4 0, 4 4, 0 4, 0 0))')) AS t(id, geom)
-)
-SELECT id,
- ST_AsText(geom),
- ST_ClusterIntersectingWin(geom) OVER () AS cluster
-FROM testdata;
+WITH testdata AS
+ (SELECT unnest(ARRAY['LINESTRING (0 0, 1 1)'::geometry,
+ 'LINESTRING (5 5, 4 4)'::geometry,
+ 'LINESTRING (6 6, 7 7)'::geometry,
+ 'LINESTRING (0 0, -1 -1)'::geometry,
+ 'POLYGON ((0 0, 4 0, 4 4, 0 4, 0 0))'::geometry]) AS geom)
- id | st_astext | cluster
-----+--------------------------------+---------
- 1 | LINESTRING(0 0,1 1) | 0
- 2 | LINESTRING(5 5,4 4) | 0
- 3 | LINESTRING(6 6,7 7) | 1
- 4 | LINESTRING(0 0,-1 -1) | 0
- 5 | POLYGON((0 0,4 0,4 4,0 4,0 0)) | 0
+SELECT ST_AsText(unnest(ST_ClusterIntersecting(geom))) FROM testdata;
+
+--result
+st_astext
+---------
+GEOMETRYCOLLECTION(LINESTRING(0 0,1 1),LINESTRING(5 5,4 4),LINESTRING(0 0,-1 -1),POLYGON((0 0,4 0,4 4,0 4,0 0)))
+GEOMETRYCOLLECTION(LINESTRING(6 6,7 7))
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para>
- <xref linkend="ST_ClusterDBSCAN" />,
- <xref linkend="ST_ClusterKMeans" />,
+ <xref linkend="ST_ClusterIntersectingWin" />,
+ <xref linkend="ST_ClusterWithin" />,
<xref linkend="ST_ClusterWithinWin" />
- <xref linkend="ST_ClusterWithin" />
- <xref linkend="ST_ClusterIntersecting" />
</para>
</refsection>
</refentry>
- <refentry id="ST_ClusterIntersecting">
+
+ <refentry id="ST_ClusterIntersectingWin">
<refnamediv>
- <refname>ST_ClusterIntersecting</refname>
+ <refname>ST_ClusterIntersectingWin</refname>
- <refpurpose>Aggregate function that clusters input geometries into connected sets.</refpurpose>
+ <refpurpose>Window function that returns a cluster id for each input geometry, clustering input geometries into connected sets.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
- <funcdef>geometry[] <function>ST_ClusterIntersecting</function></funcdef>
- <paramdef><type>geometry set</type> <parameter>g</parameter></paramdef>
+ <funcdef>integer <function>ST_ClusterIntersectingWin</function></funcdef>
+ <paramdef><type>geometry winset </type> <parameter>geom</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
@@ -234,49 +231,49 @@ FROM testdata;
<refsection>
<title>Description</title>
- <para>ST_ClusterIntersecting is an aggregate function that returns an array of GeometryCollections, where each GeometryCollection represents an interconnected set of geometries.</para>
+ <para>A window function that builds connected clusters of geometries that intersect. It is possible to traverse all geometries in a cluster without leaving the cluster. The return value is the cluster number that the geometry argument participates in, or null for null inputs.</para>
- <para role="availability" conformance="2.2.0">Availability: 2.2.0</para>
+ <para role="availability" conformance="3.4.0">Availability: 3.4.0</para>
</refsection>
<refsection>
<title>Examples</title>
<programlisting>
-WITH testdata AS
- (SELECT unnest(ARRAY['LINESTRING (0 0, 1 1)'::geometry,
- 'LINESTRING (5 5, 4 4)'::geometry,
- 'LINESTRING (6 6, 7 7)'::geometry,
- 'LINESTRING (0 0, -1 -1)'::geometry,
- 'POLYGON ((0 0, 4 0, 4 4, 0 4, 0 0))'::geometry]) AS geom)
-
-SELECT ST_AsText(unnest(ST_ClusterIntersecting(geom))) FROM testdata;
+WITH testdata AS (
+ SELECT id, geom::geometry FROM (
+ VALUES (1, 'LINESTRING (0 0, 1 1)'),
+ (2, 'LINESTRING (5 5, 4 4)'),
+ (3, 'LINESTRING (6 6, 7 7)'),
+ (4, 'LINESTRING (0 0, -1 -1)'),
+ (5, 'POLYGON ((0 0, 4 0, 4 4, 0 4, 0 0))')) AS t(id, geom)
+)
+SELECT id,
+ ST_AsText(geom),
+ ST_ClusterIntersectingWin(geom) OVER () AS cluster
+FROM testdata;
---result
+ id | st_astext | cluster
+----+--------------------------------+---------
+ 1 | LINESTRING(0 0,1 1) | 0
+ 2 | LINESTRING(5 5,4 4) | 0
+ 3 | LINESTRING(6 6,7 7) | 1
+ 4 | LINESTRING(0 0,-1 -1) | 0
+ 5 | POLYGON((0 0,4 0,4 4,0 4,0 0)) | 0
-st_astext
----------
-GEOMETRYCOLLECTION(LINESTRING(0 0,1 1),LINESTRING(5 5,4 4),LINESTRING(0 0,-1 -1),POLYGON((0 0,4 0,4 4,0 4,0 0)))
-GEOMETRYCOLLECTION(LINESTRING(6 6,7 7))
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para>
- <xref linkend="ST_ClusterDBSCAN" />,
- <xref linkend="ST_ClusterKMeans" />,
+ <xref linkend="ST_ClusterIntersecting" />,
+ <xref linkend="ST_ClusterWithin" />,
<xref linkend="ST_ClusterWithinWin" />
- <xref linkend="ST_ClusterWithin" />
</para>
</refsection>
</refentry>
-
-
-
-
-
<refentry id="ST_ClusterKMeans">
<refnamediv>
<refname>ST_ClusterKMeans</refname>
@@ -420,7 +417,7 @@ from
<refnamediv>
<refname>ST_ClusterWithin</refname>
- <refpurpose>Aggregate function that clusters input geometries by separation distance.</refpurpose>
+ <refpurpose>Aggregate function that clusters geometries by separation distance.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -436,7 +433,14 @@ from
<refsection>
<title>Description</title>
- <para>ST_ClusterWithin is an aggregate function that returns an array of GeometryCollections, where each GeometryCollection represents a set of geometries separated by no more than the specified distance. (Distances are Cartesian distances in the units of the SRID.)</para>
+ <para>An aggregate function that returns an array of GeometryCollections,
+ where each collection is a cluster containing some input geometries.
+ Clustering partitions the input geometries into sets,
+ in which each geometry is within the specified <parameter>distance</parameter>
+ of at least one other geometry in the same cluster.
+ Distances are Cartesian distances in the units of the SRID.
+ </para>
+ <para>ST_ClusterWithin is equivalent to running <xref linkend="ST_ClusterDBSCAN" /> with a `minpoints` of zero.</para>
<para role="availability" conformance="2.2.0">Availability: 2.2.0</para>
<para>&curve_support;</para>
@@ -465,11 +469,10 @@ GEOMETRYCOLLECTION(LINESTRING(6 6,7 7))
<refsection>
<title>See Also</title>
<para>
- <xref linkend="ST_ClusterDBSCAN" />,
- <xref linkend="ST_ClusterKMeans" />,
- <xref linkend="ST_ClusterIntersectingWin"/>,
<xref linkend="ST_ClusterWithinWin"/>,
- <xref linkend="ST_ClusterIntersecting"/>
+ <xref linkend="ST_ClusterDBSCAN" />,
+ <xref linkend="ST_ClusterIntersecting"/>,
+ <xref linkend="ST_ClusterIntersectingWin"/>
</para>
</refsection>
@@ -495,7 +498,12 @@ GEOMETRYCOLLECTION(LINESTRING(6 6,7 7))
<refsection>
<title>Description</title>
- <para>ST_ClusterWithinWin is a window function that returns an integer for each input geometry, where the integer the cluster number the geometry is a member of. Clusters represent a set of input geometries separated by no more than the specified distance. (Distances are Cartesian distances in the units of the SRID.)
+ <para>A window function that returns an integer for each input geometry,
+ which is the id of the cluster containing the geometry.
+ Clustering partitions the input geometries into sets,
+ in which each geometry is within the specified <parameter>distance</parameter>
+ of at least one other geometry in the same cluster.
+ Distances are Cartesian distances in the units of the SRID.
</para>
<para>ST_ClusterWithinWin is equivalent to running <xref linkend="ST_ClusterDBSCAN" /> with a `minpoints` of zero.</para>
<para role="availability" conformance="3.4.0">Availability: 3.4.0</para>
@@ -533,11 +541,10 @@ FROM testdata;
<refsection>
<title>See Also</title>
<para>
+ <xref linkend="ST_ClusterWithin"/>,
<xref linkend="ST_ClusterDBSCAN" />,
- <xref linkend="ST_ClusterKMeans" />,
+ <xref linkend="ST_ClusterIntersecting"/>,
<xref linkend="ST_ClusterIntersectingWin"/>,
- <xref linkend="ST_ClusterWithin"/>,
- <xref linkend="ST_ClusterIntersecting"/>
</para>
</refsection>
-----------------------------------------------------------------------
Summary of changes:
doc/reference_cluster.xml | 145 ++++++++++++++++++++++++----------------------
1 file changed, 76 insertions(+), 69 deletions(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list