PrologMethods/Geometry/knn.md

@@ -2,26 +2,46 @@
 
 An implementation of k-nearest-neighbor search using single-tree and dual-tree algorithms. Given a set of reference points and query points, this can find the k nearest neighbors in the reference set of each query point using trees.
 
+```prolog
+:- use_module('path/to/.../src/methods/knn/knn.pl').
+
+%% usage example
+TrainData = [5.1,3.5,1.4, 4.9,3.0,1.4, 4.7,3.2,1.3, 4.6,3.1,1.5],
+TestData = [3,2,0, 5,1,4, 0,0,4, 3,3,5, 0,5,5, 2,5,5],
+knn_initAndBuildModel(kd, dual_tree, 0, 20, 0.7, 0.0, 0.0, TrainData, 3),
+knn_searchWithQuery(TestData, 3, 2, NeighborsList, _, DistancesList, _).
+```
+
 # Available Predicates
 
-* [initAndBuildModel/10](/PrologMethods/Geometry/knn#initandbuildmodel10)
-* [searchWithQuery/10](/PrologMethods/Geometry/knn#searchwithquery10)
-* [searchNoQuery/7](/PrologMethods/Geometry/knn#searchnoquery7)
+* [knn_initAndBuildModel/9](/PrologMethods/Geometry/knn#knn_initandbuildmodel9)
+* [knn_searchWithQuery/7](/PrologMethods/Geometry/knn#knn_searchwithquery7)
+* [knn_searchNoQuery/5](/PrologMethods/Geometry/knn#knn_searchnoquery5)
 
 ---
 
 [links/resources](/PrologMethods/Geometry/knn#connected-linksresources)
 
-## **_initAndBuildModel/10_**
+## **_knn_initAndBuildModel/9_**
 
 Initialize the Model and build it.
 
 ```prolog
-%% part of the predicate definition
-initAndBuildModel(  +string, +string,
+%% predicate definition 
+knn_initAndBuildModel(TreeType, SearchMode, RandomBasis, LeafSize, Tau, Rho, Epsilon, ReferenceList, ReferenceRows) :-
+        LeafSize >= 1,
+        Tau >= 0,
+        Rho >= 0,
+        Rho =< 1,
+        Epsilon >= 0,
+        convert_list_to_float_array(ReferenceList, ReferenceRows, array(Xsize, Xrownum, X)),
+        initAndBuildModelI(TreeType, SearchMode, RandomBasis, LeafSize, Tau, Rho, Epsilon, X, Xsize, Xrownum).
+
+%% foreign c++ predicate definition 
+foreign(initAndBuildModel, c, initAndBuildModelI( +string, +string,
                                                   +integer, 
                                                   +integer, +float32, +float32, +float32,
-                    +pointer(float_array), +integer, +integer).
+                                                  +pointer(float_array), +integer, +integer)).
 ```
 
 ### Parameters
@@ -38,16 +58,24 @@ initAndBuildModel(  +string, +string,
 
 ---
 
-## **_searchWithQuery/10_**
+## **_knn_searchWithQuery/7_**
 
 Perform neighbor search on the queryset.
 
 ```prolog
-%% part of the predicate definition
-searchWithQuery(  +pointer(float_array), +integer, +integer,
+%% predicate definition 
+knn_searchWithQuery(QueryList, QueryRows, K, NeighborsList, YCols, DistancesList, ZCols) :-
+        K > 0,
+        convert_list_to_float_array(QueryList, QueryRows, array(Xsize, Xrownum, X)),
+        searchWithQueryI(X, Xsize, Xrownum, K, Y, YCols, YRows, Z, ZCols, ZRows),
+        convert_float_array_to_2d_list(Y, YCols, YRows, NeighborsList),
+        convert_float_array_to_2d_list(Z, ZCols, ZRows, DistancesList).
+
+%% foreign c++ predicate definition 
+foreign(searchWithQuery, c, searchWithQueryI( +pointer(float_array), +integer, +integer,
                                               +integer,
                                               -pointer(float_array), -integer, -integer,
-                  -pointer(float_array), -integer, -integer)
+                                              -pointer(float_array), -integer, -integer)).
 ```
 
 ### Parameters
@@ -60,15 +88,22 @@ searchWithQuery(  +pointer(float_array), +integer, +integer,
 
 ---
 
-## **_searchNoQuery/7_**
+## **_knn_searchNoQuery/5_**
 
 Perform monochromatic neighbor search.
 
 ```prolog
-%% part of the predicate definition
-searchNoQuery(  +integer,
+%% predicate definition 
+knn_searchNoQuery(K, NeighborsList, YCols, DistancesList, ZCols) :-
+        K > 0,
+        searchNoQueryI(K, Y, YCols, YRows, Z, ZCols, ZRows),
+        convert_float_array_to_2d_list(Y, YCols, YRows, NeighborsList),
+        convert_float_array_to_2d_list(Z, ZCols, ZRows, DistancesList).
+
+%% foreign c++ predicate definition 
+foreign(searchNoQuery, c, searchNoQueryI( +integer,
                                           -pointer(float_array), -integer, -integer,
-                -pointer(float_array), -integer, -integer)
+                                          -pointer(float_array), -integer, -integer)).
 ```
 
 ### Parameters
@@ -84,8 +119,8 @@ searchNoQuery(  +integer,
 
 If you want a more detailed explanation, then go to the python documentation. There is most of the time a good explanation on how the methods work and what the parameters do.
 
-* [**MLpack::knn_C++\_documentation**](https://www.mlpack.org/doc/stable/doxygen/classmlpack_1_1neighbor_1_1NeighborSearch.html)
-* [**MLpack::knn_Python_documentation**](https://www.mlpack.org/doc/stable/python_documentation.html#knn)
+* [**MLpack::knn_C++\_documentation**](https://www.mlpack.org/doc/mlpack-3.4.2/doxygen/classmlpack_1_1neighbor_1_1NeighborSearch.html)
+* [**MLpack::knn_Python_documentation**](https://www.mlpack.org/doc/mlpack-3.4.2/python_documentation.html#knn)
 
 added some of the links from the python documentation