From 87b9f76e8c16053c10d44c31c3662a8cb3c0c53b Mon Sep 17 00:00:00 2001
From: Paul Ramsey <pramsey@cleverelephant.ca>
Date: Wed, 24 Feb 2016 11:40:55 +0000
Subject: [PATCH] Rename ST_KMeans to ST_ClusterKMeans, add doco

git-svn-id: http://svn.osgeo.org/postgis/trunk@14675 b70326c6-7e19-0410-871a-916f4a2858ee
---
 NEWS                      |  2 +-
 doc/reference_measure.xml | 48 +++++++++++++++++++++++++++++++++++++++
 postgis/lwgeom_window.c   |  6 ++---
 postgis/postgis.sql.in    |  4 ++--
 4 files changed, 54 insertions(+), 6 deletions(-)

diff --git a/NEWS b/NEWS
index 90eae90ae..c138ead76 100644
--- 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 af33d47c9..edff99151 100644
--- 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 bfe4a75c2..afc3af074 100644
--- 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 7387c1d77..ec702a471 100644
--- 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;
 
 
-- 
2.40.0