Realized my changes were being ignored due to .gitignore. I've

translunar · translunar · commit 53491bab3ba6 · 2014-03-05T20:10:03.000-05:00
implemented most of the C functions at this point but haven't tested
most.
diff --git a/.gitignore b/.gitignore
@@ -15,7 +15,6 @@ test/flann_simple_test
 test/flann_uint_autotune.py
 build
 build_win
-lib
 dist/
 flann.kdev4
 TODO
diff --git a/src/ruby/lib/flann.rb b/src/ruby/lib/flann.rb
@@ -0,0 +1,203 @@
+require 'ffi'
+require 'nmatrix'
+
+require_relative "flann/index.rb"
+
+module Flann
+  extend FFI::Library
+  ffi_lib "libflann"
+
+  # Declare enumerators
+  Algorithm   = enum(:linear, :kdtree, :kmeans, :composite, :kdtree_single, :saved, :autotuned)
+  CentersInit = enum(:random, :gonzales, :kmeanspp)
+  LogLevel    = enum(:none, :fatal, :error, :warn, :info)
+  DistanceType = enum(:euclidean, :manhattan, :minkowski, :hist_intersect, :hellinger, :chi_square, :kullback_leibler)
+
+  DEFAULT_PARAMETERS = [:kdtree,
+                        32, 0.0,
+                        0, -1, 0,
+                        4, 4,
+                        32, 11, :random, 0.2,
+                        0.9, 0.01, 0, 0.1,
+                        :none, 0
+                       ]
+
+  # For NMatrix compatibility
+  typedef :float,  :float32
+  typedef :double, :float64
+  typedef :pointer, :index_params_ptr
+  typedef :pointer, :index_ptr
+
+  # A nearest neighbor search index for a given dataset.
+  class Parameters < FFI::Struct
+    layout :algorithm, Flann::Algorithm,    # The algorithm to use (linear, kdtree, kmeans, composite, kdtree_single, saved, autotuned)
+           :checks, :int,                   # How many leaves (features) to use (for kdtree)
+           :cluster_boundary_index, :float, # aka cb_tree, used when searching the kmeans tree
+           :trees, :int,                    # Number of randomized trees to use (for kdtree)
+           :branching, :int,                # Branching factor (for kmeans tree)
+           :iterations, :int,               # Max iterations to perform in one kmeans clustering (kmeans tree)
+           :centers_init, Flann::CentersInit, # Algorithm used (random, gonzales, kmeanspp)
+           :target_precision, :float,       # Precision desired (used for auto-tuning, -1 otherwise)
+           :build_weight, :float,           # Build tree time weighting factor
+           :memory_weight, :float,          # Index memory weighting factor
+           :sample_fraction, :float,        # What fraction of the dataset to use for autotuning
+
+           :table_number, :uint,            # The number of hash tables to use
+           :key_size, :uint,                # The length of the key to use in the hash tables
+           :multi_probe_level, :uint,       # Number of levels to use in multi-probe LSH, 0 for standard LSH
+           :log_level, Flann::LogLevel,     # Determines the verbosity of each flann function
+           :random_seed, :long              # Random seed to use
+  end
+
+  class << self
+
+
+    def dtype_to_c d
+      return :float if d == :float32
+      return :double if d == :float64
+      return d
+    end
+
+
+    # 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
+      [FFI::MemoryPointer.new(:int, result_size), FFI::MemoryPointer.new(:float, result_size)]
+    end
+
+
+    # Don't know if these will be a hash, a static struct, or a pointer to a struct. Return the pointer and the struct.
+    def handle_parameters parameters
+      parameters ||= DEFAULT_PARAMETERS unless block_given?
+
+      if parameters.is_a?(FFI::MemoryPointer) # User supplies us with the necessary parameters already in the correct form.
+        c_parameters_ptr = parameters
+        c_parameters = Flann::Parameters.new(c_parameters_ptr)
+      elsif parameters.is_a?(Flann::Parameters)
+        c_parameters = parameters
+        c_parameters_ptr = parameters.pointer
+      else
+        # Set the old fasioned way
+        c_parameters_ptr = FFI::MemoryPointer.new(Flann::Parameters.size)
+        c_parameters = Flann::Parameters.new(c_parameters_ptr)
+        if parameters.is_a?(Hash)
+          parameters.each_pair do |key, value|
+            c_parameters[key] = value
+          end
+        end
+      end
+
+      # There may also be a block.
+      yield c_parameters if block_given?
+
+      [c_parameters_ptr, c_parameters]
+    end
+
+    def handle_index index
+      return index.index_ptr if index.is_a?(Flann::Index)
+      index
+    end
+
+
+    # Find the k nearest neighbors with an index already built.
+    #
+    def nearest_neighbors_by_index index, testset, k, parameters: DEFAULT_PARAMETERS
+      parameters_ptr, parameters = handle_parameters(parameters)
+      result_size = testset.shape[0] * k
+      indices_int_ptr, distances_float_ptr = allocate_results_space(result_size)
+      index_ptr = handle_index(index)
+
+      raise(ArgumentError, "did you forget to call #build! on your index?") if index.index_ptr.nil?
+
+      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
+
+      [indices_int_ptr.read_array_of_int(result_size), distances_float_ptr.read_array_of_float(result_size)]
+    end
+
+
+    # Find the k nearest neighbors.
+    #
+    # If no index parameters are given, FLANN_DEFAULT_PARAMETERS are used. A block is accepted as well.
+    def nearest_neighbors dataset, testset, k, parameters: DEFAULT_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
+
+      # 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)]
+    end
+    alias :nn :nearest_neighbors
+
+    # Set the distance function to use when computing distances between data points.
+    def set_distance_type! distance_function, order = 0
+      Flann.send(:flann_set_distance_type, distance_function, order)
+      self
+    end
+
+    # Perform hierarchical clustering of a set of points.
+    def compute_cluster_centers dataset, clusters, parameters: DEFAULT_PARAMETERS
+      c_method = "flann_compute_cluster_centers_#{Flann::dtype_to_c(dataset.dtype)}".to_sym
+
+      result = dataset.clone_structure
+      parameters_ptr, parameters = handle_parameters(parameters)
+      Flann.send(c_method, FFI::Pointer.new_from_nmatrix(dataset), dataset.shape[0], dataset.shape[1], clusters, FFI::Pointer.new_from_nmatrix(result), parameters_ptr)
+    end
+  end
+
+
+protected
+
+  # byte: unsigned char*dataset, int rows, int cols, float* speedup, FLANNParameters* flann_params
+  # only thing that changes is the pointer type for the first arg.
+  attach_function :flann_build_index_byte,   [:pointer, :int, :int, :pointer, :index_params_ptr], :index_ptr
+  attach_function :flann_build_index_int,    [:pointer, :int, :int, :pointer, :index_params_ptr], :index_ptr
+  attach_function :flann_build_index_float,  [:pointer, :int, :int, :pointer, :index_params_ptr], :index_ptr
+  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
+
+  # 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
+
+  # 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
+  attach_function :flann_radius_search_int,    [:index_ptr, :pointer, :pointer, :pointer, :int, :float, :index_params_ptr], :int
+  attach_function :flann_radius_search_float,  [:index_ptr, :pointer, :pointer, :pointer, :int, :float, :index_params_ptr], :int
+  attach_function :flann_radius_search_double, [:index_ptr, :pointer, :pointer, :pointer, :int, :float, :index_params_ptr], :int
+
+  attach_function :flann_save_index_byte, [:index_ptr, :pointer], :int
+  attach_function :flann_save_index_int, [:index_ptr, :pointer], :int
+  attach_function :flann_save_index_float, [:index_ptr, :pointer], :int
+  attach_function :flann_save_index_double, [:index_ptr, :pointer], :int
+
+  attach_function :flann_load_index_byte, [:pointer, :pointer, :int, :int], :index_ptr
+  attach_function :flann_load_index_int, [:pointer, :pointer, :int, :int], :index_ptr
+  attach_function :flann_load_index_float, [:pointer, :pointer, :int, :int], :index_ptr
+  attach_function :flann_load_index_double, [:pointer, :pointer, :int, :int], :index_ptr
+
+  attach_function :flann_free_index_byte, [:index_ptr, :index_params_ptr], :int
+  attach_function :flann_free_index_int, [:index_ptr, :index_params_ptr], :int
+  attach_function :flann_free_index_float, [:index_ptr, :index_params_ptr], :int
+  attach_function :flann_free_index_double, [:index_ptr, :index_params_ptr], :int
+
+  attach_function :flann_set_distance_type, [DistanceType, :int], :void
+
+  attach_function :flann_compute_cluster_centers_byte, [:pointer, :int, :int, :int, :pointer, :index_params_ptr], :int
+  attach_function :flann_compute_cluster_centers_int, [:pointer, :int, :int, :int, :pointer, :index_params_ptr], :int
+  attach_function :flann_compute_cluster_centers_float, [:pointer, :int, :int, :int, :pointer, :index_params_ptr], :int
+  attach_function :flann_compute_cluster_centers_double, [:pointer, :int, :int, :int, :pointer, :index_params_ptr], :int
+
+end
diff --git a/src/ruby/lib/flann/index.rb b/src/ruby/lib/flann/index.rb
@@ -0,0 +1,90 @@
+class FFI::Pointer
+  class << self
+    def new_from_nmatrix nm
+      ::FFI::Pointer.new(nm.data_pointer).tap { |p| p.autorelease = false }
+    end
+  end
+end
+
+module Flann
+  class Index
+
+    # Constructor takes a block where we set each of the parameters. We need to be careful to do this since
+    # we're using the C API and not C++; so everything important needs to be initialized or there could be
+    # a segfault. For reasonable default definitions, see:
+    #
+    # * https://github.com/mariusmuja/flann/tree/master/src/cpp/flann/algorithms
+    #
+    def initialize dataset: nil, dtype: :float64, parameters: Flann::DEFAULT_PARAMETERS
+      @dataset        = dataset
+      @dtype          = (!dataset.nil? && dataset.is_a?(NMatrix)) ? dataset.dtype : dtype
+      @index_ptr      = nil
+
+      @parameters_ptr, @parameters = Flann::handle_parameters(parameters)
+
+      yield @parameters if block_given?
+    end
+    attr_reader :dtype, :dataset, :parameters, :parameters_ptr, :index_ptr
+
+    # Build an index
+    def build!
+      raise("no dataset specified") if @dataset.nil?
+
+      c_method = "flann_build_index_#{Flann::dtype_to_c(dtype)}".to_sym
+      speedup_float_ptr = FFI::MemoryPointer.new(:float)
+      @index_ptr = Flann.send(c_method, FFI::Pointer.new_from_nmatrix(@dataset), @dataset.shape[0], @dataset.shape[1], speedup_float_ptr, parameters_ptr)
+
+      # Return the speedup
+      speedup_float_ptr.read_float
+    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: DEFAULT_PARAMETERS
+      self.build! if index_ptr.nil?
+      Flann::nearest_neighbors_by_index index_ptr, testset, k, parameters: parameters
+    end
+
+    # Perform a radius search on a single query point
+    def radius_search query, radius, max_k: dataset.shape[1], parameters: DEFAULT_PARAMETERS
+      self.build! if index_ptr.nil?
+      parameters_ptr, parameters = handle_parameters(parameters)
+      indices_int_ptr, distances_float_ptr = allocate_results_space(max_k)
+
+      c_method = "flann_radius_search_#{Flann::dtype_to_c(dtype)}".to_sym
+      Flann.send(c_method, FFI::Pointer.new_from_nmatrix(query), indices_int_ptr, distances_float_ptr, max_k, radius, 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)]
+    end
+
+    # Save an index to a file (without the dataset).
+    def save filename
+      raise(IOError, "Cannot write an unbuilt index") if self.index_ptr.nil?
+      c_filename = FFI::MemoryPointer.from_string(filename)
+      c_method = "flann_save_index_#{Flann::dtype_to_c(dtype)}".to_sym
+      Flann.send(c_method, c_filename)
+      self
+    end
+
+    # Load an index from a file (with the dataset already known!).
+    #
+    # FIXME: This needs to free the previous dataset first.
+    def load! filename
+      c_filename = FFI::MemoryPointer.from_string(filename)
+      c_method = "flann_load_index_#{Flann::dtype_to_c(dtype)}".to_sym
+
+      @index_ptr = Flann.send(c_method, c_filename, FFI::Pointer.new_from_nmatrix(@dataset), @dataset.shape[0], @dataset.shape[1])
+      self
+    end
+
+    # Free an index
+    def free! parameters = DEFAULT_PARAMETERS
+      c_method = "flann_free_index_#{Flann::dtype_to_c(dtype)}".to_sym
+      parameters_ptr, parameters = handle_parameters(parameters)
+      Flann.send(c_method, @index_ptr, parameters_ptr)
+      @index_ptr = nil
+      self
+    end
+
+  end
+end
