rquad 0.2.0

data/.gitignore

@@ -0,0 +1,2 @@
+
+/pkg/rquad-0.1.0.gem

data/CHANGES

@@ -0,0 +1,2 @@
+Version 0.5
+- Initial public release, base quadtree and vector classes in place, with tests.

data/LICENSE

@@ -0,0 +1,21 @@
+LICENSE
+ 
+Copyright (c) 2008, Andrew Cantino, Iteration Labs, LLC, http://iterationlabs.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,7 @@
+Welcome to the rQuad Ruby Quadtree library.
+
+This package is distributed subject to the 'MIT License' found in the LICENSE file in this directory.
+
+The source is freely available online: http://github.com/iterationlabs/rquad/tree/master
+
+If you make modifications to this software and would be willing to contribute them back to the community, please send them in for possible inclusion in future releases!

data/Rakefile

@@ -0,0 +1,52 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "rquad"
+    gem.summary = %Q{Ruby Quadtree Library}
+    gem.description = %Q{Ruby Quadtree Library}
+    gem.email = "roman.scherer@nugg.ad"
+    gem.homepage = "http://github.com/r0man/rquad"
+    gem.authors = ["Roman Scherer"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "rquad #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/rquad.rb

@@ -0,0 +1,2 @@
+require "rquad/vector"
+require "rquad/quadtree"

data/lib/rquad/quadtree.rb

@@ -0,0 +1,353 @@
+# SOFTWARE INFO
+#
+# This file is part of the quadtree.rb Ruby quadtree library, distributed 
+# subject to the 'MIT License' below.  This software is available for 
+# download at http://iterationlabs.com/free_software/quadtree.
+#
+# If you make modifications to this software and would be willing to 
+# contribute them back to the community, please send them to us for 
+# possible inclusion in future releases!
+#
+# LICENSE
+#  
+# Copyright (c) 2008, Iteration Labs, LLC, http://iterationlabs.com
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+require "rquad/vector"
+
+module RQuad
+
+  # A payload for a QuadTree.  Hs accessors for vector, data, and node.
+  class QuadTreePayload
+    attr_accessor :vector, :data, :node
+
+    # Initialize a QuadTreePayload with a Vector, some data (any class).
+    def initialize(v, d, n = nil)
+      self.node = n
+      self.vector = v
+      self.data = d
+    end
+  end
+  
+  # A quadtree node that can contain QuadTreePayloads and other QuadTree nodes.  A quadtree is a tree that subdivides space into recursively defined quadrents that (in this implementation) can contain no more than one spacially-unique payload.  Quadtrees are good for answering questions about neighborhoods of points in a space.
+  #
+  # Making a quadtree is simple, just initialize a new QuadTree with two vectors, its top left and bottom right points, then add QuadTreePayloads to it and it will store them in an efficiently constructed quadtree structure.  You may then ask for all payloads in a region, all payloads near a point, etc.
+  # 
+  # Example usage with longitudes and latitudes:
+  # 
+  # qt = QuadTree.new(Vector.new(-180, 90), Vector.new(180, -90))
+  # qt.add(QuadTreePayload.new(Vector.new(lng1, lat1), entity1))
+  # qt.add(QuadTreePayload.new(Vector.new(lng2, lat2), entity2))
+  # qt.add(QuadTreePayload.new(Vector.new(lng3, lat3), entity3))
+  # qt.add(QuadTreePayload.new(Vector.new(lng4, lat4), entity4))
+  #
+  class QuadTree
+    # You may ask a QuadTree for its `payload`, `tl` point, `br` point, and `depth`.
+    attr_accessor :payload, :tl, :br, :depth
+    
+    # Initialize a new QuadTree with two vectors: its top-left corner and its bottom-right corner.  Optionally, you can also provide a reference to this node's parent node.
+    def initialize(tl, br, parent_node = nil)
+      @parent = parent_node
+      @tl = tl
+      @br = br
+      @size = 0
+      @summed_contained_vectors = Vector.new(0,0)
+      @depth = 0
+    end
+    
+    # Add a QuadTreePayload to this QuadTree.  If this node is empty, it will be stored in this node.  If not, both the new payload and the old one will be recursively added to the appropriate one of the four children of this node.  There is a special case: if this node already has a payload and the new payload has an identical position to the existing payload, then the new payload will be stored here in ddition to the existing payload.
+    #  jitter_proc - a Proc object that, if provided, is used to jitter payloads with identical vectors (accepts and returns a QuadTreePayload).
+    def add(geo_data, depth = 1, jitter_proc = nil)
+      geo_data.node = self
+      if size > 0
+        if @payload && (@payload.first.vector == geo_data.vector)
+          # The vectors match.
+          if jitter_proc
+            @payload << jitter_proc.call(geo_data)
+          else
+            @payload << geo_data
+          end
+        else
+          # The vectors don't match.
+          if payload
+            @payload.each { |p| add_into_subtree(p, depth + 1, jitter_proc) }
+            @payload = nil
+          end
+          add_into_subtree(geo_data, depth + 1, jitter_proc)
+        end
+      else
+        @payload = [geo_data]
+        @depth = depth
+      end
+      @summed_contained_vectors += geo_data.vector
+      @size += 1
+    end
+
+    # This method returns the payloads contained under this node in the quadtree.  It takes an options hash with the following optional keys:
+    #  :max_count - the maximum number of payloads to return, provided via a breadth-first search.
+    #  :details_proc - a Proc object to which every internal node at the maximum deoth achieved by the search is passed -- this is useful for providing summary statistics about subtrees that were not explored by this traversal due to a :max_count limitation.
+    #  :requirement_proc - a Proc object that, if provided, must return true when evaluating a payload in order for that payload to be returned.
+    # Returns a Hash with keys :payloads, an array of all of the payloads below this node, and :details, the mapped result of applying :details_proc (if provided) to every internal node at the mximum depth achieved by the search.
+    def get_contained(options = {})
+      payloads = []
+      internal_nodes = []
+      last_depth = -1
+      breadth_first_each do |node, depth|
+        break if options[:max_count] && payloads.length >= options[:max_count] && (!options[:details_proc] || depth != last_depth)
+
+        if node.payload
+          internal_nodes.delete_if {|i| i.parent_of?(node)} if options[:details_proc]
+          node.payload.each do |entry|
+            if !options[:requirement_proc] || options[:requirement_proc].call(entry)
+              payloads << entry
+            end
+          end
+        elsif options[:details_proc] && (node.tlq? || node.trq? || node.blq? || node.brq?)
+          internal_nodes.delete_if {|i| i.parent_of?(node)}
+          internal_nodes << node
+        end
+        last_depth = depth
+      end
+      { :payloads => payloads, :details => (options[:details_proc] ? internal_nodes.map {|i| options[:details_proc].call(i)} : nil) }
+    end
+
+    # Calls get_contained and only returns the :payloads key.  Accepts the same options as get_contained except for the :details_proc option.
+    def get_contained_payloads(options = {})
+      get_contained(options)[:payloads]
+    end
+    
+    # Returns the centroid of the payloads contained in this quadtree.
+    def center_of_mass
+      @summed_contained_vectors / @size
+    end
+    
+    # Performs a breath-first traversal of this quadtree, yielding [node, depth] for each node.
+    def breadth_first_each
+      queue = [self]
+      while queue.length > 0
+        node = queue.shift
+        queue << node.tlq if node.tlq?
+        queue << node.trq if node.trq?
+        queue << node.blq if node.blq?
+        queue << node.brq if node.brq?
+        yield node, node.depth
+      end
+    end
+    
+    # Yields each payload in this quadtree via a breadth-first traversal.
+    def each_payload
+      breadth_first_each do |node, depth|
+        next unless node.payload
+        node.payload.each do |payload|
+          yield payload
+        end
+      end
+    end
+    
+    # True if this node is a direct parent of `node`.
+    def parent_of?(node)
+      node && node == tlq(false) || node == trq(false) || node == blq(false) || node == brq(false)
+    end
+    
+    # True if this node is a direct child of `node`.
+    def child_of?(node)
+      node.parent_of?(self)
+    end
+    
+    # Yields all pseudo-leaves formed when the graph is cut off at a certain depth, plus any leaves encountered before that depth.
+    def leaves_each(leaf_depth)
+      stack = [self]
+      while stack.length > 0
+        node = stack.pop
+        start_size = stack.length
+        stack << node.tlq if node.tlq? && node.tlq.depth < leaf_depth + depth
+        stack << node.trq if node.trq? && node.trq.depth < leaf_depth + depth
+        stack << node.blq if node.blq? && node.blq.depth < leaf_depth + depth
+        stack << node.brq if node.brq? && node.brq.depth < leaf_depth + depth
+        if node.depth == leaf_depth + depth - 1 || (!node.tlq? && !node.trq? && !node.blq? && !node.brq?)
+          yield node
+        end
+      end
+    end
+    
+    # Returns the size of this node: the number of contained payloads.
+    def size
+      @size
+    end
+    
+    # Returns this node's parent node or nil if this node is a root node.
+    def parent
+      @parent
+    end
+    
+    # Returns approxametly `approx_number` payloads near `location`.
+    def approx_near(location, approx_number)
+      if approx_number >= size
+        return get_contained_payloads
+      else
+        get_containing_quad(location).approx_near(location, approx_number)
+      end
+    end
+    
+    # Returns up to `max_number` payloads inside of the region specified by `region_tl` and `region_br`.
+    def payloads_in_region(region_tl, region_br, max_number = nil)
+      quad1 = get_containing_quad(region_tl)
+      quad2 = get_containing_quad(region_br)
+      if quad1 == quad2 && payload.nil?
+        quad1.payloads_in_region(region_tl, region_br, max_number)
+      else
+        region_containment_proc = lambda do |i|
+          region_tl.x <= i.vector.x && region_br.x >= i.vector.x && region_tl.y >= i.vector.y && region_br.y <= i.vector.y
+        end
+        get_contained_payloads(:max_count => max_number, :requirement_proc => region_containment_proc)
+      end
+    end
+    
+    # Returns an array of [centroid (Vector), count] pairs summarizing the set of centroids at a certain tree depth.  That is, it provides centroids and counts of all of the subtrees still available at depth `depth`, plus any that terminated above that depth.
+    def center_of_masses_in_region(region_tl, region_br, depth)
+      quad1 = get_containing_quad(region_tl)
+      quad2 = get_containing_quad(region_br)
+      if quad1 == quad2 && payload.nil?
+        quad1.center_of_masses_in_region(region_tl, region_br, depth)
+      else
+        centers_of_mass = []
+        leaves_each(depth) do |node|
+          centers_of_mass << [node.center_of_mass, node.size]
+        end
+        centers_of_mass
+      end    
+    end
+    
+    # Returns a hash with keys :payloads and :details.  The :payloads are payloads found, while details are for nodes that didn't get to be explored because the requisite number of payloads were already found.  
+    def payloads_and_centers_in_region(region_tl, region_br, approx_num_to_return)
+      quad1 = get_containing_quad(region_tl)
+      quad2 = get_containing_quad(region_br)
+      if quad1 == quad2 && payload.nil?
+        quad1.payloads_and_centers_in_region(region_tl, region_br, approx_num_to_return)
+      else
+        region_containment_proc = lambda do |i|
+          region_tl.x <= i.vector.x && region_br.x >= i.vector.x && region_tl.y >= i.vector.y && region_br.y <= i.vector.y
+        end
+        details_proc = lambda do |i|
+          [i.center_of_mass, i.size]
+        end
+        get_contained(:max_count => approx_num_to_return, :requirement_proc => region_containment_proc, :details_proc => details_proc)
+      end
+    end
+    
+    # The top-left quadrent of this quadtree.  If `build` is true, this will make the quadrent quadtree if it doesn't alredy exist.
+    def tlq(build = true)
+      @tlq ||= QuadTree.new(Vector.new(tl), Vector.new(tl.x + (br.x - tl.x) / 2.0, br.y + (tl.y - br.y) / 2.0), self) if build
+      @tlq
+    end
+    
+    # The top-right quadrent of this quadtree.  If `build` is true, this will make the quadrent quadtree if it doesn't alredy exist.
+    def trq(build = true)
+      @trq ||= QuadTree.new(Vector.new(tl.x + (br.x - tl.x) / 2.0, tl.y), Vector.new(br.x, br.y + (tl.y - br.y) / 2.0), self) if build
+      @trq
+    end
+    
+    # The bottom-left quadrent of this quadtree.  If `build` is true, this will make the quadrent quadtree if it doesn't alredy exist.
+    def blq(build = true)
+      @blq ||= QuadTree.new(Vector.new(tl.x, br.y + (tl.y - br.y) / 2.0), Vector.new(tl.x + (br.x - tl.x) / 2.0, br.y), self) if build
+      @blq
+    end
+    
+    # The bottom-right quadrent of this quadtree.  If `build` is true, this will make the quadrent quadtree if it doesn't alredy exist.
+    def brq(build = true)
+      @brq ||= QuadTree.new(Vector.new(tl.x + (br.x - tl.x) / 2.0, br.y + (tl.y - br.y) / 2.0), Vector.new(br), self) if build
+      @brq
+    end
+    
+    # Returns true if this quadtree has a top-left quadrent already defined.
+    def tlq?
+      @tlq && (@tlq.payload || (@tlq.tlq? || @tlq.trq? || @tlq.blq? || @tlq.brq?))
+    end
+
+    # Returns true if this quadtree has a top-right quadrent already defined.
+    def trq?
+      @trq && (@trq.payload || (@trq.tlq? || @trq.trq? || @trq.blq? || @trq.brq?))
+    end
+
+    # Returns true if this quadtree has a bottom-left quadrent already defined.
+    def blq?
+      @blq && (@blq.payload || (@blq.tlq? || @blq.trq? || @blq.blq? || @blq.brq?))
+    end
+
+    # Returns true if this quadtree has a bottom-right quadrent already defined.
+    def brq?
+      @brq && (@brq.payload || (@brq.tlq? || @brq.trq? || @brq.blq? || @brq.brq?))
+    end
+    
+    # Returns true if Vector `v` falls inside of this quadtree.
+    def inside?(v)
+      # Greedy, so the order of comparison of quads will matter.
+      tl.x <= v.x && br.x >= v.x && tl.y >= v.y && br.y <= v.y
+    end
+    
+    # Clips Vector `v` to the bounds of this quadtree.
+    def clip_vector(v)
+      v = v.dup
+      v.x = tl.x if v.x < tl.x
+      v.y = tl.y if v.y > tl.y
+      v.x = br.x if v.x > br.x
+      v.y = br.y if v.y < br.y
+      v
+    end
+    
+    # Scans back up a quadtree from this node until a node is found that contains the region defined by `in_tl` and `in_br`, at which point the subtree size is returned from that point.
+    # (Only scans back up the tree, won't scan down.)
+    def family_size_at_width(in_tl, in_br)
+      if (inside?(in_tl) && inside?(in_br)) || parent.nil?
+        size
+      else
+        parent.family_size_at_width(in_tl, in_br)
+      end
+    end
+    
+    def to_s
+      "[Quadtree #{object_id}, size: #{size}, depth: #{depth}]"
+    end
+    
+    def inspect
+      to_s
+    end
+    
+    private
+
+    def add_into_subtree(geo_data, depth = 1, jitter_proc = nil)
+      get_containing_quad(geo_data.vector).add(geo_data, depth, jitter_proc)
+    end
+    
+    def get_containing_quad(vector)
+      if tlq.inside?(vector)
+        tlq
+      elsif trq.inside?(vector)
+        trq
+      elsif blq.inside?(vector)
+        blq
+      elsif brq.inside?(vector)
+        brq
+      else
+        raise "This shouldn't happen!  #{vector} isn't in any of my quads! (#{self.to_s})"
+      end
+    end
+  end
+end

data/lib/rquad/vector.rb

@@ -0,0 +1,162 @@
+# SOFTWARE INFO
+#
+# This file is part of the quadtree.rb Ruby quadtree library, distributed 
+# subject to the 'MIT License' below.  This software is available for 
+# download at http://iterationlabs.com/free_software/quadtree.
+#
+# If you make modifications to this software and would be willing to 
+# contribute them back to the community, please send them to us for 
+# possible inclusion in future releases!
+#
+# LICENSE
+#  
+# Copyright (c) 2008, Iteration Labs, LLC, http://iterationlabs.com
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+# 
+
+# A class for representing a simple 2D or 3D vector.  Primarily for use with the QudTree class.  Very simple and minimilistic.
+# irb(main):002:0> v = Vector.new(1, 2)
+# => #<Vector:0xb7c8dacc @x=1.0, @y=2.0>
+# irb(main):003:0> v + Vector.new(10, 11)
+# => #<Vector:0xb7c86d30 @x=11.0, @y=13.0>
+# irb(main):004:0> (v + Vector.new(10, 11)).length
+# => 17.0293863659264
+# irb(main):005:0> v * -2
+# => #<Vector:0xb7c73834 @x=-2.0, @y=-4.0>
+module RQuad
+  class Vector
+    # Initialize a Vector with either another Vector, an Array, or 2-3 numbers.
+    def initialize(x = nil, y = nil, z = nil)
+      if x && x.kind_of?(Vector)
+        @x = x.x
+        @y = x.y
+        @z = x.z
+      elsif x && x.kind_of?(Array)
+        @x = x[0]
+        @y = x[1]
+        @z = x[2]
+      else
+        @x = x.to_f if x
+        @y = y.to_f if y
+        @z = z.to_f if z
+      end
+    end
+    
+    # The X component of this vector.
+    def x
+      @x
+    end
+    
+    # The Y component of this vector.
+    def y
+      @y
+    end
+    
+    # The Z component of this vector.
+    def z
+      @z
+    end
+    
+    # Set the X component of this vector.
+    def x=(new_x)
+      @x = new_x.to_f if new_x
+    end
+
+    # Set the Y component of this vector.
+    def y=(new_y)
+      @y = new_y.to_f if new_y
+    end
+
+    # Set the Z component of this vector.
+    def z=(new_z)
+      @z = new_z.to_f if new_z
+    end
+    
+    # The length of this vector in 2D or 3D space.
+    def length
+      if z
+        Math.sqrt(x * x + y * y + z * z)
+      elsif x && y
+        Math.sqrt(x * x + y * y)
+      else
+        nil
+      end
+    end
+    
+    # The Euclidean distnce between this and another Vector `other`.
+    def dist_to(other)
+      (other - self).length
+    end
+    
+    # This vector minus another Vector `other`.
+    def -(other)
+      self + other * -1
+    end
+    
+    # Divide this vector by a `scalar`.
+    def /(scalar)
+      if z
+        Vector.new(x / scalar, y / scalar, z / scalar)
+      elsif x && y
+        Vector.new(x / scalar, y / scalar)
+      else
+        Vector.new
+      end
+    end
+    
+    # Multiply this vector by a `scalar`.
+    def *(scalar)
+      if z
+        Vector.new(x * scalar, y * scalar, z * scalar)
+      elsif x && y
+        Vector.new(x * scalar, y * scalar)
+      else
+        Vector.new
+      end
+    end
+    
+    # Add another Vector `other` to this vector.
+    def +(other)
+      if z && other.z
+        Vector.new(x + other.x, y + other.y, z + other.z)
+      elsif x && y && other.x && other.y
+        Vector.new(x + other.x, y + other.y)
+      else
+        Vector.new
+      end
+    end
+    
+    # Test if this vector is equal to another Vector `other`.
+    def ==(other)
+      result = (other.x == x && other.y == y && other.z == z)
+      #    puts "(#{other.x} == #{x} && #{other.y} == #{y} && #{other.z} == #{z}) = #{result.inspect}"
+      result
+    end
+    
+    # Display this vector as a String, either in <x, y> or <x, y, z> notation.
+    def to_s
+      if z
+        "<#{x ? x : 'nil'}, #{y ? y : 'nil'}, #{z}>"
+      else
+        "<#{x ? x : 'nil'}, #{y ? y : 'nil'}>"
+      end
+    end
+  end
+end

data/rquad.gemspec

@@ -0,0 +1,55 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{rquad}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Roman Scherer"]
+  s.date = %q{2010-11-02}
+  s.description = %q{Ruby Quadtree Library}
+  s.email = %q{roman.scherer@nugg.ad}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README"
+  ]
+  s.files = [
+    ".gitignore",
+     "CHANGES",
+     "LICENSE",
+     "README",
+     "Rakefile",
+     "VERSION",
+     "lib/rquad.rb",
+     "lib/rquad/quadtree.rb",
+     "lib/rquad/vector.rb",
+     "rquad.gemspec",
+     "test/helper.rb",
+     "test/rquad/test_quadtree.rb",
+     "test/rquad/test_vector.rb"
+  ]
+  s.homepage = %q{http://github.com/r0man/rquad}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Ruby Quadtree Library}
+  s.test_files = [
+    "test/rquad/test_quadtree.rb",
+     "test/rquad/test_vector.rb",
+     "test/helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/test/helper.rb

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'test/unit'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rquad'
+
+class Test::Unit::TestCase
+end

data/test/rquad/test_quadtree.rb

@@ -0,0 +1,247 @@
+#!/usr/bin/env ruby
+# SOFTWARE INFO
+#
+# This file is part of the quadtree.rb Ruby quadtree library, distributed 
+# subject to the 'MIT License' below.  This software is available for 
+# download at http://iterationlabs.com/free_software/quadtree.
+#
+# If you make modifications to this software and would be willing to 
+# contribute them back to the community, please send them to us for 
+# possible inclusion in future releases!
+#
+# LICENSE
+#  
+# Copyright (c) 2008, Iteration Labs, LLC, http://iterationlabs.com
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+# 
+
+require 'test/unit'
+require 'fileutils'
+require "rquad/quadtree"
+require "rquad/vector"
+
+module RQuad
+  
+  class TestQuadTree < Test::Unit::TestCase
+    def standard_quad
+      q = QuadTree.new(Vector.new(0,100), Vector.new(100,0))
+      q.add(QuadTreePayload.new(Vector.new(10, 10), :a))
+      q.add(QuadTreePayload.new(Vector.new(75, 75), :b))
+      q.add(QuadTreePayload.new(Vector.new(5, 99), :c))
+      q.add(QuadTreePayload.new(Vector.new(99, 5), :d))
+      q.add(QuadTreePayload.new(Vector.new(99, 4), :e))
+      q
+    end
+    
+    def test_new_quadtree
+      q = QuadTree.new(Vector.new(0,100), Vector.new(100,0))
+      assert_equal 0, q.size
+    end
+    
+    def test_adding_element
+      q = QuadTree.new(Vector.new(0,100), Vector.new(100,0))
+      q.add(QuadTreePayload.new(Vector.new(10, 10), 'hello'))
+      assert_equal 1, q.size
+      assert_equal 'hello', q.payload.first.data
+    end
+    
+    def test_adding_a_few_elements
+      q = QuadTree.new(Vector.new(0,100), Vector.new(100,0))
+      q.add(QuadTreePayload.new(Vector.new(10, 10), :a))
+      q.add(QuadTreePayload.new(Vector.new(75, 75), :b))
+      q.add(QuadTreePayload.new(Vector.new(5, 99), :c))
+      q.add(QuadTreePayload.new(Vector.new(99, 5), :d))
+      assert_equal 4, q.size
+      assert_equal nil, q.payload
+      assert_equal 1, q.tlq.size
+      assert_equal 1, q.trq.size
+      assert_equal 1, q.blq.size
+      assert_equal 1, q.brq.size
+      assert_equal :c, q.tlq.payload.first.data
+      assert_equal :b, q.trq.payload.first.data
+      assert_equal :a, q.blq.payload.first.data
+      assert_equal :d, q.brq.payload.first.data
+    end
+    
+    def test_greedy_adding_of_elements_on_boundaries
+      q = QuadTree.new(Vector.new(0,100), Vector.new(100,0))
+      q.add(QuadTreePayload.new(Vector.new(50, 50), :a))
+      assert_equal 1, q.size
+      assert_equal :a, q.payload.first.data
+      q.add(QuadTreePayload.new(Vector.new(0, 50), :b))
+      assert_equal :a, q.tlq.brq.payload.first.data
+      assert_equal :b, q.tlq.blq.payload.first.data    
+    end
+    
+    def test_adding_two_identical_elements
+      q = QuadTree.new(Vector.new(0,100), Vector.new(100,0))
+      q.add(QuadTreePayload.new(Vector.new(10, 10), 'hello'))
+      assert_equal 1, q.size
+      assert_equal 'hello', q.payload.first.data
+      q.add(QuadTreePayload.new(Vector.new(10, 10), 'hi!'))
+      assert_equal 2, q.size
+      assert_equal 2, q.payload.length
+      assert_equal 'hello', q.payload.first.data
+      assert_equal 'hi!', q.payload.last.data
+    end
+    
+    def test_approx_near
+      q = standard_quad
+      assert_equal 5, q.approx_near(Vector.new(50, 50), 5).length
+      assert_equal 5, q.approx_near(Vector.new(50, 50), 10).length
+      assert_equal true, q.approx_near(Vector.new(99, 1), 3).any? {|i| i.vector == Vector.new(99, 4)}
+      assert_equal true, q.approx_near(Vector.new(99, 1), 3).any? {|i| i.vector == Vector.new(99, 5)}
+      assert_equal false, q.approx_near(Vector.new(99, 1), 3).any? {|i| i.vector == Vector.new(10, 10)}
+    end
+    
+    def test_payloads_in_region_in_small_region
+      q = standard_quad
+      assert_equal 2, q.payloads_in_region(Vector.new(98, 10), Vector.new(100, 0)).length
+      assert_equal 1, q.payloads_in_region(Vector.new(98, 10), Vector.new(100, 0), 1).length
+      assert_equal true, q.payloads_in_region(Vector.new(98, 10), Vector.new(100, 0)).any? {|i| i.vector == Vector.new(99, 4)}
+      assert_equal true, q.payloads_in_region(Vector.new(98, 10), Vector.new(100, 0)).any? {|i| i.vector == Vector.new(99, 5)}
+      assert_equal false, q.payloads_in_region(Vector.new(98, 10), Vector.new(100, 0)).any? {|i| i.vector == Vector.new(10, 10)}
+    end
+
+    def test_payloads_in_region_in_large_region
+      q = standard_quad
+      assert_equal 5, q.payloads_in_region(Vector.new(0, 100), Vector.new(100, 0)).length
+    end
+    
+    def test_adding_a_third_element_to_two_identical_elements
+      q = QuadTree.new(Vector.new(0,100), Vector.new(100,0))
+      q.add(QuadTreePayload.new(Vector.new(10, 10), 'hello'))
+      assert_equal 1, q.size
+      assert_equal 'hello', q.payload.first.data
+      q.add(QuadTreePayload.new(Vector.new(10, 10), 'hi!'))
+      assert_equal 2, q.size
+      assert_equal 2, q.payload.length
+      assert_equal 'hello', q.payload.first.data
+      assert_equal 'hi!', q.payload.last.data
+      
+      q.add(QuadTreePayload.new(Vector.new(20,20), 'third wheel'))
+      assert_equal 3, q.size
+      assert_equal nil, q.payload
+      assert_equal 2, q.blq.blq.blq.payload.length
+      assert_equal 1, q.blq.blq.trq.payload.length
+      assert_equal 'third wheel', q.blq.blq.trq.payload.first.data
+      
+      # And test get_contained_payloads while we're at it.
+      assert_equal 3, q.get_contained_payloads.length
+      assert_equal 3, q.blq.blq.get_contained_payloads.length
+      assert_equal 1, q.blq.blq.trq.get_contained_payloads.length
+      assert_equal 2, q.blq.blq.blq.get_contained_payloads.length
+      assert_equal 0, q.blq.blq.brq.get_contained_payloads.length
+    end
+    
+    def test_get_contained_payloads_with_number_limit
+      q = standard_quad
+      assert_equal 1, q.get_contained_payloads(:max_count => 1).length
+      assert_equal 4, q.get_contained_payloads(:max_count => 4).length
+      assert_equal 5, q.get_contained_payloads(:max_count => 20).length
+      assert_equal 5, q.get_contained_payloads.length
+      
+      assert_equal true, q.get_contained_payloads(:max_count => 4).any? {|i| i.vector == Vector.new(10, 10)}
+      assert_equal true, q.get_contained_payloads(:max_count => 4).any? {|i| i.vector == Vector.new(75, 75)}
+      assert_equal true, q.get_contained_payloads(:max_count => 4).any? {|i| i.vector == Vector.new(5, 99)}
+      assert_equal true, q.get_contained_payloads(:max_count => 4).any? {|i| i.vector == Vector.new(99, 5)}
+      assert_equal false, q.get_contained_payloads(:max_count => 4).any? {|i| i.vector == Vector.new(11, 10)} # because it's lower and quads go clockwise
+    end
+    
+    def test_center_of_mass
+      q = QuadTree.new(Vector.new(0,100), Vector.new(100,0))
+      q.add(QuadTreePayload.new(Vector.new(30, 55), :a))
+      q.add(QuadTreePayload.new(Vector.new(70, 55), :b))
+      assert_equal Vector.new(50,55), q.center_of_mass
+      assert_equal Vector.new(30,55), q.tlq.center_of_mass
+      assert_equal Vector.new(70,55), q.trq.center_of_mass    
+    end
+    
+    def test_depth
+      q = standard_quad
+      assert_equal 1, q.depth
+      assert_equal 2, q.tlq.depth
+      assert_equal 2, q.trq.depth
+      assert_equal 2, q.blq.depth
+      assert_equal 2, q.brq.depth
+      assert_equal 3, q.brq.brq.depth
+    end
+    
+    def test_leaves_each
+      q = standard_quad
+      leaves = []
+      q.leaves_each(100) do |leaf|
+        leaves << leaf
+      end
+      assert_equal 5, leaves.length
+
+      leaves = []
+      q.leaves_each(3) do |leaf|
+        leaves << leaf
+      end
+      assert_equal 4, leaves.length
+    end
+    
+    def test_clip_vector
+      q = QuadTree.new(Vector.new(0,100), Vector.new(100,0))
+      assert_equal Vector.new(0, 100), q.clip_vector(Vector.new(-1, 100))
+      assert_equal Vector.new(100, 100), q.clip_vector(Vector.new(200, 200))
+      assert_equal Vector.new(0, 0), q.clip_vector(Vector.new(-200, -200))
+      assert_equal Vector.new(100, 0), q.clip_vector(Vector.new(200, -200))
+    end
+    
+    def test_child_of_and_parent_of
+      q = standard_quad
+      assert_equal true, q.blq.child_of?(q)
+      assert_equal true, q.trq.child_of?(q)
+      assert_equal true, q.brq.tlq.child_of?(q.brq)
+      assert_equal true, q.brq.parent_of?(q.brq.brq)
+    end
+    
+    def test_payloads_and_centers_in_region
+      q = standard_quad
+      assert_equal 1, q.payloads_and_centers_in_region(Vector.new(0,100), Vector.new(100, 0), 1)[:details].length
+      assert_equal 2, q.payloads_and_centers_in_region(Vector.new(0,100), Vector.new(100, 0), 1)[:details].first.last
+      assert_equal 3, q.payloads_and_centers_in_region(Vector.new(0,100), Vector.new(100, 0), 1)[:payloads].length
+    end
+    
+    def test_parent
+      q = standard_quad
+      assert_equal q.brq, q.brq.brq.parent
+      assert_equal q, q.brq.parent
+      assert_equal nil, q.parent
+    end
+    
+    def test_quadtreepayload_node
+      q = standard_quad
+      assert_equal q.blq, q.get_contained_payloads(:max_count => 5).find {|i| i.vector == Vector.new(10, 10)}.node
+    end
+    
+    def test_family_size_at_width
+      q = standard_quad
+      tl = Vector.new(0, 49)
+      br = Vector.new(49, 0)
+      assert_equal 5, q.family_size_at_width(tl, br)
+      assert_equal 5, q.brq.brq.family_size_at_width(tl, br)
+      assert_equal 1, q.blq.family_size_at_width(tl, br)
+    end
+  end
+
+end

data/test/rquad/test_vector.rb

@@ -0,0 +1,95 @@
+#!/usr/bin/env ruby
+# SOFTWARE INFO
+#
+# This file is part of the quadtree.rb Ruby quadtree library, distributed 
+# subject to the 'MIT License' below.  This software is available for 
+# download at http://iterationlabs.com/free_software/quadtree.
+#
+# If you make modifications to this software and would be willing to 
+# contribute them back to the community, please send them to us for 
+# possible inclusion in future releases!
+#
+# LICENSE
+#  
+# Copyright (c) 2008, Iteration Labs, LLC, http://iterationlabs.com
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+# 
+
+require 'test/unit'
+require 'fileutils'
+require "rquad/vector"
+
+module RQuad
+  
+  class TestVector < Test::Unit::TestCase
+    def test_new_vector
+      assert_equal nil, Vector.new.x
+      assert_equal nil, Vector.new.y
+      assert_equal nil, Vector.new.z
+      
+      v = Vector.new(1, 2, 3)
+      v2 = Vector.new(v)
+      assert_equal 1, v2.x
+      assert_equal 2, v2.y
+      assert_equal 3, v2.z
+      assert_equal v, v2
+      
+      v3 = Vector.new([1, 2, 3])
+      assert_equal v, v3
+    end
+
+    def test_multiply
+      assert_equal Vector.new(4, 6), Vector.new(2, 3) * 2
+      assert_equal Vector.new(0, -10), Vector.new(0, 1) * -10
+      assert_equal Vector.new(2, -10, 100), Vector.new(-0.2, 1, -10) * -10
+    end
+    
+    def test_add
+      assert_equal Vector.new(2, 3), Vector.new(1, 1) + Vector.new(1, 2)
+      assert_equal Vector.new(2, 3), Vector.new(-1, 10) + Vector.new(3, -7.0)
+      assert_equal Vector.new(2, 3, -1), 
+      Vector.new(-1, 10, 2) + Vector.new(3, -7.0, -3)
+    end
+    
+    def test_subtract
+      assert_equal Vector.new(2, 3), Vector.new(4, 4) - Vector.new(2, 1)
+      assert_equal Vector.new(5, -1), Vector.new(-1, 10) - Vector.new(-6, 11)
+      assert_equal Vector.new(5, -1, 10), 
+      Vector.new(-1, 10, 12) - Vector.new(-6, 11, 2)
+    end
+    
+    def test_length
+      assert_equal 5, Vector.new(5, 0).length
+      assert_equal 5.0, Vector.new(0, 5, 0).length
+      assert_equal 5, Vector.new(3, 4, 0).length
+      assert_equal 5, Vector.new(0, 3, 4).length
+    end
+    
+    def test_equality
+      assert_equal Vector.new(5, 0), Vector.new(5, 0)
+      assert_equal Vector.new(-1, -2), Vector.new(-1, -2)
+      assert_equal Vector.new(-1, -2, -4), Vector.new(-1, -2, -4)
+      assert_not_equal Vector.new(-1, -2, 5), Vector.new(-1, -2, 4)
+      assert_not_equal Vector.new(-1, -2), Vector.new(-1, -2, 4)
+      assert_not_equal Vector.new(-2, -2), Vector.new(-1, -2)
+    end
+  end
+
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: rquad
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 0
+  version: 0.2.0
+platform: ruby
+authors: 
+- Roman Scherer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-02 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: Ruby Quadtree Library
+email: roman.scherer@nugg.ad
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README
+files: 
+- .gitignore
+- CHANGES
+- LICENSE
+- README
+- Rakefile
+- VERSION
+- lib/rquad.rb
+- lib/rquad/quadtree.rb
+- lib/rquad/vector.rb
+- rquad.gemspec
+- test/helper.rb
+- test/rquad/test_quadtree.rb
+- test/rquad/test_vector.rb
+has_rdoc: true
+homepage: http://github.com/r0man/rquad
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Ruby Quadtree Library
+test_files: 
+- test/rquad/test_quadtree.rb
+- test/rquad/test_vector.rb
+- test/helper.rb