From 63b5a4021efe3718f39b7cfb14d312995c6d69b1 Mon Sep 17 00:00:00 2001
From: Pierre Alexandre Tremblay <info@pierrealexandretremblay.com>
Date: Thu, 17 Sep 2020 09:41:24 +0100
Subject: [PATCH] KDtree - new examples and doc for radius search new interface

---
 .../HelpSource/Classes/FluidKDTree.schelp     | 39 ++++++++++++++-----
 1 file changed, 30 insertions(+), 9 deletions(-)

diff --git a/release-packaging/HelpSource/Classes/FluidKDTree.schelp b/release-packaging/HelpSource/Classes/FluidKDTree.schelp
index c469b8b..e260360 100644
--- a/release-packaging/HelpSource/Classes/FluidKDTree.schelp
+++ b/release-packaging/HelpSource/Classes/FluidKDTree.schelp
@@ -15,7 +15,9 @@ Make a new KDTree model for the given server.
 ARGUMENT:: server
 The server on which to make the model.
 ARGUMENT:: numNeighbours
-The number of neighbours to return.
+The number of neighbours to return. A 0 will return all points in order of distance. When a radius is defined, numNeighbours is the maximum of items returned.
+ARGUMENT:: radius
+The threshold of acceptable distance for a point to be returned. A 0 will bypass this function, returning numNeighbours points.
 ARGUMENT:: lookupDataSet
 An optional link::Classes/FluidDataSet:: from which data points will be returned for realtime queries. This does not need to be the same DataSet that the tree was fitted against, but does need to have matching labels. Using this mechanism, we have a way to, e.g. associate labels with segments of playback buffers, without needing pass strings around the server. warning::This parameter can not be safely changed after the instance of FluidKDTree has been created::
 
@@ -48,7 +50,7 @@ EXAMPLES::
 code::
 
 
-// Make a DataSet of random 23D points
+// Make a DataSet of random 2D points
 s.boot;
 (
 fork{
@@ -73,19 +75,15 @@ fork{
 ~tree.cols;
 
 
-//Return labels of k nearest points to a new point
+//Return the labels of k nearest points to a new point
 (
 ~p = [ 1.0.linrand,1.0.linrand ];
-~tree.numNeighbours = 5;
 ~tmpbuf = Buffer.loadCollection(s, ~p, 1, {
 	~tree.kNearest(~tmpbuf,{ |a|a.postln;~nearest = a;})
 });
 )
 
-// Labels of nearest points
-~nearest.postln;
-
-// Values
+// Retrieve values from the DataSet by iterating through the returned labels
 (
 fork{
 	~nearest.do{|n|
@@ -94,8 +92,31 @@ fork{
 	}
 }
 )
-//Distances of the nearest points
+// Distances of the nearest points
 ~tree.kNearestDist(~tmpbuf, { |a| a.postln });
+
+// Explore changing the number of neighbourgs
+~tree.numNeighbours = 11; // note that this value needs to be sent to the server
+~tree.numNeighbours = 0; // 0 will return all items in order of distance
+
+// Limit the search to an acceptable distance in a radius
+// Define a point, and observe typical distance values
+~p = [ 0.2,0.2];
+~tree.numNeighbours = 20;
+(
+~tmpbuf = Buffer.loadCollection(s, ~p, 1, {
+	~tree.kNearestDist(~tmpbuf,{ |a|a.postln;~nearest = a;});
+});
+)
+
+// enter a valid radius.
+~tree.radius = 0.05;
+// FluidKDTree will return only values that are within that radius, up to numNeighbours values
+(
+~tmpbuf = Buffer.loadCollection(s, ~p, 1, {
+	~tree.kNearest(~tmpbuf,{ |a|a.postln;~nearest = a;});
+});
+)
 ::
 
 subsection:: Server Side Queries