flann 1.8.4.2

data/lib/flann/index.rb

@@ -0,0 +1,162 @@
+# Copyright 2014 John O. Woods (john.o.woods@gmail.com), West Virginia
+#   University's Applied Space Exploration Lab, and West Virginia Robotic
+#   Technology Center. All rights reserved.
+#
+# THE BSD LICENSE
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+class FFI::Pointer
+  class << self
+    def new_from_nmatrix nm
+      raise(StorageError, "dense storage expected") unless nm.dense?
+      c_type = Flann::dtype_to_c(nm.dtype)
+      c_type = :uchar if c_type == :byte
+      ::FFI::Pointer.new(c_type, 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 index_dataset = nil, dtype: :float64, parameters: Flann::Parameters::DEFAULT
+      @dataset        = index_dataset
+      #require 'pry'
+      #binding.pry if @dataset.nil?
+      @dtype          = (!index_dataset.nil? && index_dataset.is_a?(NMatrix)) ? index_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
+
+    # Assign a new dataset. Requires that the old index be freed.
+    def dataset= index_dataset
+      free!
+      @dataset = index_dataset
+    end
+
+    # Build an index
+    def build!
+      raise("no dataset specified") if dataset.nil?
+      c_type   = Flann::dtype_to_c(dtype)
+      c_method = "flann_build_index_#{c_type}".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)
+      if index_ptr.address == 0
+        require 'pry'
+        binding.pry
+        raise("failed to allocate index_ptr")
+      end
+
+
+      # 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 = {}
+      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
+
+      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)
+
+      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),
+       c_type == :double ? distances_t_ptr.read_array_of_double(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=nil, parameters = {}
+      max_k    ||= dataset.shape[0]
+      parameters = Parameters.new(Flann::Parameters::DEFAULT.merge(parameters))
+
+      self.build! if index_ptr.nil?
+      parameters_ptr, parameters = Flann::handle_parameters(parameters)
+
+      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   = indices_int_ptr.read_array_of_int(max_k)
+      distances = c_type == :double ? distances_t_ptr.read_array_of_double(max_k) : distances_t_ptr.read_array_of_float(max_k)
+
+      # Stop where indices == -1
+      cutoff = indices.find_index(-1)
+      cutoff.nil? ? [indices, distances] : [indices[0...cutoff], distances[0...cutoff]]
+    end
+
+    # Save an index to a file (without the dataset).
+    def save filename
+      raise(IOError, "Cannot write an unbuilt index") if index_ptr.nil?     # FIXME: This should probably have its own exception type.
+      c_method = "flann_save_index_#{Flann::dtype_to_c(dtype)}".to_sym
+      Flann.send(c_method, index_ptr, 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_method = "flann_load_index_#{Flann::dtype_to_c(dtype)}".to_sym
+
+      @index_ptr = Flann.send(c_method, filename, FFI::Pointer.new_from_nmatrix(dataset), dataset.shape[0], dataset.shape[1])
+      self
+    end
+
+    # Free an index
+    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)
+      @index_ptr = nil
+      self
+    end
+
+  end
+end

data/lib/flann/version.rb

@@ -0,0 +1,37 @@
+# Copyright 2014 John O. Woods (john.o.woods@gmail.com), West Virginia
+#   University's Applied Space Exploration Lab, and West Virginia Robotic
+#   Technology Center. All rights reserved.
+#
+# THE BSD LICENSE
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+module Flann
+  module VERSION
+    MAJOR = 1
+    MINOR = 8
+    TINY  = 4
+    MINISCULE = 2
+
+    STRING = [MAJOR, MINOR, TINY, MINISCULE].compact.join('.')
+  end
+end

data/spec/flann_spec.rb

@@ -0,0 +1,104 @@
+# Copyright 2014 John O. Woods (john.o.woods@gmail.com), West Virginia
+#   University's Applied Space Exploration Lab, and West Virginia Robotic
+#   Technology Center. All rights reserved.
+#
+# THE BSD LICENSE
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require File.dirname(__FILE__) + "/spec_helper.rb"
+
+describe Flann do
+
+  it "::VERSION::STRING matches #define FLANN_VERSION_ in config.h" do
+    found = false
+    File.open(File.dirname(__FILE__) + "/../../cpp/flann/config.h", "r") do |f|
+      while line = f.gets
+        next unless line =~ /#[\s]*define[\s]+FLANN_VERSION_[\s]+"\d.\d.\d"/
+        fields = line.split
+        found = true
+        expect(fields.last[1...-1]).to eq(Flann::VERSION::STRING.split('.')[0...-1].join('.'))
+      end
+    end
+
+    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
+      Flann.set_distance_type! :euclidean
+
+      # Version check needed before attempting get_distance_type
+      if Flann.respond_to?(:flann_get_distance_type)
+        d = Flann.get_distance_type
+        expect(d).to eq(:euclidean)
+      end
+    end
+  end
+
+  [:byte, :int32, :float32, :float64].each do |dtype|
+    before :each do
+      scale = [:byte, :int32, :int64].include?(dtype) ? 255 : 1.0
+      @dataset = NMatrix.random([1000,128], dtype: dtype, scale: scale)
+      @testset = NMatrix.random([100,128],  dtype: dtype, scale: scale)
+    end
+
+    context "#nearest_neighbors" do
+      it "computes the nearest neighbors without an index" do
+        Flann.nearest_neighbors @dataset, @testset, 5
+      end
+    end
+
+    context "#cluster" do
+      it "calls flann_compute_cluster_centers_... properly" do
+        Flann.cluster(@dataset, 5)
+      end
+    end
+
+
+  end
+
+
+end

data/spec/index_spec.rb

@@ -0,0 +1,114 @@
+# Copyright 2014 John O. Woods (john.o.woods@gmail.com), West Virginia
+#   University's Applied Space Exploration Lab, and West Virginia Robotic
+#   Technology Center. All rights reserved.
+#
+# THE BSD LICENSE
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require File.dirname(__FILE__) + "/spec_helper.rb"
+
+
+describe Flann::Index do
+  [:byte, :int32, :float32, :float64].each do |dtype|
+    context dtype.inspect do
+      before :each do
+        scale = [:byte, :int32, :int64].include?(dtype) ? 255 : 1.0
+
+        @dataset = NMatrix.random([1000,128], dtype: dtype, scale: scale)
+        @testset = NMatrix.random([100,128],  dtype: dtype, scale: scale)
+        @index   = Flann::Index.new(@dataset) do |t|
+          t[:algorithm] = :kdtree
+          t[:trees]     = 4
+        end
+        @index.build!
+      end
+
+
+      context "#nearest_neighbors" do
+        it "runs without error" do
+          @index.nearest_neighbors @testset, 5
+        end
+
+        if dtype == :float32
+          it "runs a :kdtree_single search correctly" do
+            @dataset = read_dataset "test.dataset"
+            @testset = @dataset[0,:*].clone
+            @index   = Flann::Index.new(@dataset) do |t|
+              t[:algorithm] = :kdtree_single
+            end
+            @index.build!
+            indices, distances = @index.nearest_neighbors @testset, 11
+            #expect(indices).to eq([0,1,256,257,2,512,258,513,514,3,768])
+            expect(indices[0]).to eq(0)
+            expect(indices[1..2].sort).to eq([1,256])
+            expect(indices[3]).to eq(257)
+            expect(indices[4..5].sort).to eq([2,512])
+            expect(indices[6..7].sort).to eq([258,513])
+            expect(indices[8]).to eq(514)
+            expect(indices[9..10].sort).to eq([3,768])
+
+            expect(distances[0]).to be_within(1E-16).of(0.0)
+            expect(distances[1]).to be_within(1E-4).of(2.614689)
+            expect(distances[2]).to be_within(1E-4).of(2.614689)
+            expect(distances[3]).to be_within(1E-4).of(5.229378)
+            expect(distances[4]).to be_within(1E-4).of(10.465225)
+            expect(distances[5]).to be_within(1E-4).of(10.465225)
+            expect(distances[6]).to be_within(1E-4).of(13.079914)
+            expect(distances[7]).to be_within(1E-4).of(13.079914)
+            expect(distances[8]).to be_within(1E-4).of(20.93045)
+            expect(distances[9]).to be_within(1E-4).of(23.541904)
+          end
+        end
+      end
+
+
+      context "#radius_search" do
+        it "runs without error" do
+          query = NMatrix.random([1,128])
+          @index.radius_search query, 0.4
+        end
+      end
+
+
+      context "#save" do
+        it "saves an index to a file which can be loaded again" do
+          FileUtils.rm("temp_index.save_file", :force => true)
+          @index.save("temp_index.save_file")
+
+          raise(IOError, "save failed") unless File.exists?("temp_index.save_file")
+
+          post_index = Flann::Index.new(@dataset)
+          post_index.load!("temp_index.save_file")
+          FileUtils.rm("temp_index.save_file", :force => true)
+        end
+      end
+
+
+      context "#free!" do
+        it "frees an index" do
+          @index.free!
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,50 @@
+# Copyright 2014 John O. Woods (john.o.woods@gmail.com), West Virginia
+#   University's Applied Space Exploration Lab, and West Virginia Robotic
+#   Technology Center. All rights reserved.
+#
+# THE BSD LICENSE
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'rspec'
+require 'rspec/longrun'
+
+require "./lib/flann"
+
+# Helper function for reading a test dataset so we can test nearest neighbors
+# and radius search and such.
+def read_dataset filename
+  Dir.chdir("spec") do
+    f = File.new(filename, 'r')
+    n = NMatrix.new([65536, 3], dtype: :float32)
+    i = 0
+    while line = f.gets
+      line.chomp!
+      fields = line.split
+      n[i,:*] = fields.map { |field| field.to_f }
+
+      i += 1
+    end
+
+    n
+  end
+end