Rename ST_KMeans to ST_ClusterKMeans, add doco

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

diff --git a/NEWS b/NEWS
index 90eae90ae1cd9b5840969326bb93de330d0c3455..c138ead76a5778dc35a50802decb9a725f8b3433 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -13,7 +13,7 @@ PostGIS 2.3.0
   - #3339 ST_GeneratePoints (Paul Ramsey)
   - #3362 ST_ClusterDBSCAN (Dan Baston) 
   - #3428 ST_Points (Dan Baston)
-  - #3465 ST_KMeans (Paul Ramsey)
+  - #3465 ST_ClusterKMeans (Paul Ramsey)
 
 PostGIS 2.2.1
 2016/01/06

diff --git a/doc/reference_measure.xml b/doc/reference_measure.xml
index af33d47c93940cb3585864b805d7b94537f39617..edff99151b73d0c4534360a8e38db5ad83ddb014 100644 (file)
--- a/doc/reference_measure.xml
+++ b/doc/reference_measure.xml
@@ -4160,4 +4160,52 @@ SELECT ST_Buffer(ST_GeomFromText('POINT(50 50)'), 20) As smallc,
                <para><xref linkend="ST_Contains"/>, <xref linkend="ST_Equals"/>, <xref linkend="ST_IsValid"/></para>
          </refsection>
        </refentry>
+  
+       <refentry id="ST_ClusterKMeans">
+         <refnamediv>
+               <refname>ST_ClusterKMeans</refname>
+
+               <refpurpose>Windowing function that returns integer for cluster each input geometry is in.</refpurpose>
+         </refnamediv>
+
+         <refsynopsisdiv>
+               <funcsynopsis>
+                 <funcprototype>
+                       <funcdef>integer <function>ST_ClusterKMeans</function></funcdef>
+
+                       <paramdef><type>geometry </type>
+                       <parameter>geom</parameter></paramdef>
+
+                       <paramdef><type>integer </type>
+                       <parameter>number_of_clusters</parameter></paramdef>
+                 </funcprototype>
+               </funcsynopsis>
+         </refsynopsisdiv>
+
+         <refsection>
+      <title>Description</title>
+
+      <para>Returns 2D distance based 
+        <ulink url="https://en.wikipedia.org/wiki/K-means_clustering">k-means</ulink> 
+        cluster number for each input geometry. The distance used for clustering is the 
+        distance between the centroids of the geometries.
+      </para>
+    </refsection>
+
+    <refsection>
+      <title>Examples</title>
+                   <programlisting>
+SELECT ST_ClusterKMeans(geom, 5) over (), geom, parcel_id 
+FROM parcels;
+</programlisting>
+    </refsection>
+
+    <refsection>
+                 <title>See Also</title>
+      <!-- <para><xref linkend="ST_ClusterDBSCAN"/></para> -->
+      <para>See also ST_ClusterDBSCAN</para>
+         </refsection>
+       </refentry>  
+  
+  
 </sect1>

diff --git a/postgis/lwgeom_window.c b/postgis/lwgeom_window.c
index bfe4a75c2f55a7500fd1b4084418c3b4ad8506cd..afc3af0741559fbc185637b2fd68ed41277b9795 100644 (file)
--- a/postgis/lwgeom_window.c
+++ b/postgis/lwgeom_window.c
@@ -38,7 +38,7 @@
 #include "lwgeom_pg.h"
 
 extern Datum ST_ClusterDBSCAN(PG_FUNCTION_ARGS);
-extern Datum ST_KMeans(PG_FUNCTION_ARGS);
+extern Datum ST_ClusterKMeans(PG_FUNCTION_ARGS);
 
 typedef struct {
        bool    isdone;
@@ -159,8 +159,8 @@ Datum ST_ClusterDBSCAN(PG_FUNCTION_ARGS)
        PG_RETURN_INT32(context->cluster_assignments[row].cluster_id);
 }
 
-PG_FUNCTION_INFO_V1(ST_KMeans);
-Datum ST_KMeans(PG_FUNCTION_ARGS)
+PG_FUNCTION_INFO_V1(ST_ClusterKMeans);
+Datum ST_ClusterKMeans(PG_FUNCTION_ARGS)
 {
        WindowObject winobj = PG_WINDOW_OBJECT();
        kmeans_context *context;

diff --git a/postgis/postgis.sql.in b/postgis/postgis.sql.in
index 7387c1d77922076e9c38acaacfd12b6365540621..ec702a47110611cea05535e098840dfdecb756f0 100644 (file)
--- a/postgis/postgis.sql.in
+++ b/postgis/postgis.sql.in
@@ -3797,9 +3797,9 @@ CREATE AGGREGATE ST_MakeLine (
 --------------------------------------------------------------------------------
 
 -- Availability: 2.3.0
-CREATE FUNCTION ST_KMeans(geom geometry, k integer)
+CREATE FUNCTION ST_ClusterKMeans(geom geometry, k integer)
   RETURNS integer
-  AS 'MODULE_PATHNAME', 'ST_KMeans'
+  AS 'MODULE_PATHNAME', 'ST_ClusterKMeans'
   LANGUAGE 'c' VOLATILE STRICT WINDOW;