[postgis-tickets] r14675 - Rename ST_KMeans to ST_ClusterKMeans, add doco

[Paul Ramsey]

Author: pramsey
Date: 2016-02-24 03:40:55 -0800 (Wed, 24 Feb 2016)
New Revision: 14675

Modified:
   trunk/NEWS
   trunk/doc/reference_measure.xml
   trunk/postgis/lwgeom_window.c
   trunk/postgis/postgis.sql.in
Log:
Rename ST_KMeans to ST_ClusterKMeans, add doco


Modified: trunk/NEWS
===================================================================
--- trunk/NEWS	2016-02-24 11:21:30 UTC (rev 14674)
+++ trunk/NEWS	2016-02-24 11:40:55 UTC (rev 14675)
@@ -13,7 +13,7 @@
   - #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

Modified: trunk/doc/reference_measure.xml
===================================================================
--- trunk/doc/reference_measure.xml	2016-02-24 11:21:30 UTC (rev 14674)
+++ trunk/doc/reference_measure.xml	2016-02-24 11:40:55 UTC (rev 14675)
@@ -4160,4 +4160,52 @@
 		<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>

Modified: trunk/postgis/lwgeom_window.c
===================================================================
--- trunk/postgis/lwgeom_window.c	2016-02-24 11:21:30 UTC (rev 14674)
+++ trunk/postgis/lwgeom_window.c	2016-02-24 11:40:55 UTC (rev 14675)
@@ -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 @@
 	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;

Modified: trunk/postgis/postgis.sql.in
===================================================================
--- trunk/postgis/postgis.sql.in	2016-02-24 11:21:30 UTC (rev 14674)
+++ trunk/postgis/postgis.sql.in	2016-02-24 11:40:55 UTC (rev 14675)
@@ -3797,9 +3797,9 @@
 --------------------------------------------------------------------------------
 
 -- 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;