Fixed a few more problems that cropped up while revising manual and

testing manual code.

Author: translunar

README.md

@@ -2,7 +2,7 @@ FLANN - Fast Library for Approximate Nearest Neighbors
 ======================================================
 
 FLANN is a library for performing fast approximate nearest neighbor searches in high dimensional spaces. It contains a collection of algorithms we found to work best for nearest neighbor search and a system for automatically choosing the best algorithm and optimum parameters depending on the dataset.
-FLANN is written in C++ and contains bindings for the following languages: C, MATLAB and Python.
+FLANN is written in C++ and contains bindings for the following languages: C, MATLAB, Python, and Ruby.
 
 
 Documentation

doc/manual.pdf

@@ -50,7 +50,7 @@ \section{Introduction}
 FLANN (Fast Library for Approximate Nearest Neighbors) is a library for
 performing fast approximate nearest neighbor searches. FLANN is written in
 the C++ programming language. FLANN can be easily used in many contexts
-through the C, MATLAB and Python bindings provided with the library.
+through the C, MATLAB, Python, and Ruby bindings provided with the library.
 
 
 
@@ -59,7 +59,7 @@ \subsection{Quick Start}
 
 
 This section contains small examples of how to use the FLANN library from
-different programming languages (C++, C, MATLAB and Python).
+different programming languages (C++, C, MATLAB, Python, and Ruby).
 
 \begin{itemize}
 
@@ -187,6 +187,31 @@ \subsection{Quick Start}
                branching=32, iterations=7, checks=16);
 \end{Verbatim}
 
+\item \textbf{Ruby}
+\begin{Verbatim}[fontsize=\scriptsize,frame=single]
+require 'flann' # also requires NMatrix
+
+dataset = NMatrix.random([10000,128])
+testset = NMatrix.random([1000,128])
+
+index   = Flann::Index.new(dataset) do |params|
+  params[:algorithm]  = :kmeans
+  params[:branching]  = 32
+  params[:iterations] = 7
+  params[:checks]     = 16
+end
+speedup = index.build! # this is optional
+
+results, distances = index.nearest_neighbors(testset, 5)
+
+index.save "my_index.save"
+
+# Alternatively, without an index:
+results, distances = Flann.nearest_neighbors(dataset, testset, 5,
+                      algorithm: :kmeans, branching: 32,
+                      iterations: 7, checks: 16)
+
+\end{Verbatim}
 \end{itemize}
 
 
@@ -1541,7 +1566,7 @@ \subsection{Using FLANN from python}
 
 
 
-See section \ref{sec:quickstart} for an example of how to use the Python
+See section \ref{sec:quickstart} for an example of how to use the Python and Ruby
 bindings.
 
 

doc/manual.tex

@@ -96,8 +96,8 @@ def dtype_to_c d #:nodoc:
     # Allocates index space and distance space for storing results from various searches. For a k-nearest neighbors
     # search, for example, you want trows (the number of rows in the testset) times k (the number of nearest neighbors
     # being searched for).
-    def allocate_results_space result_size #:nodoc:
-      [FFI::MemoryPointer.new(:int, result_size), FFI::MemoryPointer.new(:float, result_size)]
+    def allocate_results_space result_size, c_type #:nodoc:
+      [FFI::MemoryPointer.new(:int, result_size), FFI::MemoryPointer.new(c_type, result_size)]
     end
 
 
@@ -132,18 +132,23 @@ def handle_parameters parameters #:nodoc:
     # Find the k nearest neighbors.
     #
     # If no index parameters are given, FLANN_Parameters::DEFAULT are used. A block is accepted as well.
-    def nearest_neighbors dataset, testset, k, parameters: Parameters.new(Parameters::DEFAULT)
+    def nearest_neighbors dataset, testset, k, parameters = {}
+      parameters = Parameters.new(Flann::Parameters::DEFAULT.merge(parameters))
       # Get a pointer and a struct regardless of how the arguments are supplied.
       parameters_ptr, parameters = handle_parameters(parameters)
       result_size = testset.shape[0] * k
-      indices_int_ptr, distances_float_ptr = allocate_results_space(result_size)
 
-      Flann.flann_find_nearest_neighbors FFI::Pointer.new_from_nmatrix(dataset), dataset.shape[0], dataset.shape[1],
-                                         FFI::Pointer.new_from_nmatrix(testset), testset.shape[0],
-                                         indices_int_ptr, distances_float_ptr, k, parameters_ptr
+      c_type = Flann::dtype_to_c(dataset.dtype)
+      c_method = "flann_find_nearest_neighbors_#{c_type}".to_sym
+      indices_int_ptr, distances_t_ptr = allocate_results_space(result_size, c_type)
+
+      # dataset, rows, cols, testset, trows, indices, dists, nn, flann_params
+      Flann.send c_method,   FFI::Pointer.new_from_nmatrix(dataset), dataset.shape[0], dataset.shape[1],
+                             FFI::Pointer.new_from_nmatrix(testset), testset.shape[0],
+                             indices_int_ptr, distances_t_ptr, k, parameters_ptr
 
       # Return results: two arrays, one of indices and one of distances.
-      [indices_int_ptr.read_array_of_int(result_size), distances_float_ptr.read_array_of_float(result_size)]
+      [indices_int_ptr.read_array_of_int(result_size), distances_t_ptr.read_array_of_float(result_size)]
     end
     alias :nn :nearest_neighbors
 
@@ -158,7 +163,8 @@ def set_distance_type! distance_function, order = 0
     # Arguments:
     # * dataset: NMatrix of points
     # * parameters:
-    def cluster dataset, clusters, parameters: Parameters.new(Parameters::DEFAULT)
+    def cluster dataset, clusters, parameters = {}
+      parameters = Parameters.new(Flann::Parameters::DEFAULT.merge(parameters))
       c_method = "flann_compute_cluster_centers_#{Flann::dtype_to_c(dataset.dtype)}".to_sym
 
       result = dataset.clone_structure
@@ -184,10 +190,16 @@ def cluster dataset, clusters, parameters: Parameters.new(Parameters::DEFAULT)
   attach_function :flann_build_index_double, [:pointer, :int, :int, :pointer, :index_params_ptr], :index_ptr
 
   # index, testset, trows, indices, dists, nn, flann_params
-  attach_function :flann_find_nearest_neighbors_index, [:index_ptr, :pointer, :int, :pointer, :pointer, :int, :index_params_ptr], :int
+  attach_function :flann_find_nearest_neighbors_index_byte,   [:index_ptr, :pointer, :int, :pointer, :pointer, :int, :index_params_ptr], :int
+  attach_function :flann_find_nearest_neighbors_index_int,    [:index_ptr, :pointer, :int, :pointer, :pointer, :int, :index_params_ptr], :int
+  attach_function :flann_find_nearest_neighbors_index_float,  [:index_ptr, :pointer, :int, :pointer, :pointer, :int, :index_params_ptr], :int
+  attach_function :flann_find_nearest_neighbors_index_double, [:index_ptr, :pointer, :int, :pointer, :pointer, :int, :index_params_ptr], :int
 
   # dataset, rows, cols, testset, trows, indices, dists, nn, flann_params
-  attach_function :flann_find_nearest_neighbors, [:pointer, :int, :int, :pointer, :int, :pointer, :pointer, :int, :index_params_ptr], :int
+  attach_function :flann_find_nearest_neighbors_byte,   [:pointer, :int, :int, :pointer, :int, :pointer, :pointer, :int, :index_params_ptr], :int
+  attach_function :flann_find_nearest_neighbors_int,    [:pointer, :int, :int, :pointer, :int, :pointer, :pointer, :int, :index_params_ptr], :int
+  attach_function :flann_find_nearest_neighbors_float,  [:pointer, :int, :int, :pointer, :int, :pointer, :pointer, :int, :index_params_ptr], :int
+  attach_function :flann_find_nearest_neighbors_double, [:pointer, :int, :int, :pointer, :int, :pointer, :pointer, :int, :index_params_ptr], :int
 
   # index, query point, result indices, result distances, max_nn, radius, flann_params
   attach_function :flann_radius_search_byte,   [:index_ptr, :pointer, :pointer, :pointer, :int, :float, :index_params_ptr], :int

src/ruby/lib/flann.rb

@@ -16,7 +16,7 @@ class Index
     #
     # * https://github.com/mariusmuja/flann/tree/master/src/cpp/flann/algorithms
     #
-    def initialize dataset: nil, dtype: :float64, parameters: Flann::Parameters::DEFAULT
+    def initialize dataset = nil, dtype: :float64, parameters: Flann::Parameters::DEFAULT
       @dataset        = dataset
       @dtype          = (!dataset.nil? && dataset.is_a?(NMatrix)) ? dataset.dtype : dtype
       @index_ptr      = nil
@@ -27,6 +27,11 @@ def initialize dataset: nil, dtype: :float64, parameters: Flann::Parameters::DEF
     end
     attr_reader :dtype, :dataset, :parameters, :parameters_ptr, :index_ptr
 
+    # Assign a new dataset. Requires that the old index be freed.
+    def dataset= new_dataset
+      free!
+    end
+
     # Build an index
     def build!
       raise("no dataset specified") if dataset.nil?
@@ -40,34 +45,44 @@ def build!
     end
 
     # Get the nearest neighbors based on this index. Forces a build of the index if one hasn't been done yet.
-    def nearest_neighbors testset, k, parameters: Parameters.new(Parameters::DEFAULT)
+    def nearest_neighbors testset, k, parameters = {}
+      parameters = Parameters.new(Flann::Parameters::DEFAULT.merge(parameters))
+
       self.build! if index_ptr.nil?
 
       parameters_ptr, parameters = Flann::handle_parameters(parameters)
       result_size = testset.shape[0] * k
-      indices_int_ptr, distances_float_ptr = Flann::allocate_results_space(result_size)
 
-      Flann.flann_find_nearest_neighbors_index index_ptr,
-                                               FFI::Pointer.new_from_nmatrix(testset),
-                                               testset.shape[0],
-                                               indices_int_ptr, distances_float_ptr,
-                                               k,
-                                               parameters_ptr
+      c_type = Flann::dtype_to_c(dataset.dtype)
+      c_method = "flann_find_nearest_neighbors_index_#{c_type}".to_sym
+      indices_int_ptr, distances_t_ptr = Flann::allocate_results_space(result_size, c_type)
 
-      [indices_int_ptr.read_array_of_int(result_size), distances_float_ptr.read_array_of_float(result_size)]
+      Flann.send c_method, index_ptr,
+                           FFI::Pointer.new_from_nmatrix(testset),
+                           testset.shape[0],
+                           indices_int_ptr, distances_t_ptr,
+                           k,
+                           parameters_ptr
+
+      [indices_int_ptr.read_array_of_int(result_size), distances_t_ptr.read_array_of_float(result_size)]
     end
 
     # Perform a radius search on a single query point
-    def radius_search query, radius, max_k: dataset.shape[1], parameters: Parameters.new(Parameters::DEFAULT)
+    def radius_search query, radius, parameters = {}
+      max_k      = parameters[:max_neighbors] || dataset.shape[1]
+      parameters = Parameters.new(Flann::Parameters::DEFAULT.merge(parameters))
+
       self.build! if index_ptr.nil?
       parameters_ptr, parameters = Flann::handle_parameters(parameters)
-      indices_int_ptr, distances_float_ptr = Flann::allocate_results_space(max_k)
 
-      c_method = "flann_radius_search_#{Flann::dtype_to_c(dtype)}".to_sym
-      Flann.send(c_method, index_ptr, FFI::Pointer.new_from_nmatrix(query), indices_int_ptr, distances_float_ptr, max_k, radius, parameters_ptr)
+      c_type = Flann::dtype_to_c(dataset.dtype)
+      c_method = "flann_radius_search_#{c_type}".to_sym
+      indices_int_ptr, distances_t_ptr = Flann::allocate_results_space(max_k, c_type)
+
+      Flann.send(c_method, index_ptr, FFI::Pointer.new_from_nmatrix(query), indices_int_ptr, distances_t_ptr, max_k, radius, parameters_ptr)
 
       # Return results: two arrays, one of indices and one of distances.
-      [indices_int_ptr.read_array_of_int(max_k), distances_float_ptr.read_array_of_float(max_k)]
+      [indices_int_ptr.read_array_of_int(max_k), distances_t_ptr.read_array_of_float(max_k)]
     end
 
     # Save an index to a file (without the dataset).
@@ -89,7 +104,8 @@ def load! filename
     end
 
     # Free an index
-    def free! parameters = Parameters.new(Parameters::DEFAULT)
+    def free! parameters = {}
+      parameters = Parameters.new(Flann::Parameters::DEFAULT.merge(parameters))
       c_method = "flann_free_index_#{Flann::dtype_to_c(dtype)}".to_sym
       parameters_ptr, parameters = Flann::handle_parameters(parameters)
       Flann.send(c_method, index_ptr, parameters_ptr)

src/ruby/lib/flann/index.rb

@@ -16,6 +16,29 @@
     raise("could not find version string in config.h") unless found
   end
 
+  it "works on the example given in the manual" do
+    dataset = NMatrix.random([10000,128])
+    testset = NMatrix.random([1000,128])
+
+    index   = Flann::Index.new(dataset) do |params|
+      params[:algorithm]  = :kmeans
+      params[:branching]  = 32
+      params[:iterations] = 7
+      params[:checks]     = 16
+    end
+    speedup = index.build! # this is optional
+
+    results, distances = index.nearest_neighbors(testset, 5)
+
+    # Skip saving, as that's tested elsewhere, and I don't feel like cleaning up.
+    # index.save "my_index.save"
+
+    # Alternatively, without an index:
+    results, distances = Flann.nearest_neighbors(dataset, testset, 5,
+                          algorithm: :kmeans, branching: 32,
+                          iterations: 7, checks: 16)
+  end
+
   context "#set_distance_type!" do
     it "sets the distance functor without error" do
       pending "distance type unsupported in the C bindings, use the C++ bindings instead"

src/ruby/spec/flann_spec.rb

@@ -6,7 +6,7 @@
   before :each do
     @dataset = NMatrix.random([1000,128])
     @testset = NMatrix.random([100,128])
-    @index   = Flann::Index.new(dataset: @dataset) do |t|
+    @index   = Flann::Index.new(@dataset) do |t|
       t[:algorithm] = :kdtree
       t[:trees]     = 4
     end
@@ -43,7 +43,7 @@
 
       raise(IOError, "save failed") unless File.exists?("temp_index.save_file")
 
-      post_index = Flann::Index.new(dataset: @dataset)
+      post_index = Flann::Index.new(@dataset)
       post_index.load!("temp_index.save_file")
       FileUtils.rm("temp_index.save_file", :force => true)
     end