quadtree 1.0.2 → 1.0.8

data/lib/quadtree/point.rb

@@ -1,66 +1,161 @@
+# frozen_string_literal: true
+
 module Quadtree
-    # Simple coordinate object to represent points in some space.
-    class Point
-
-      # @return [Float] X coordinate
-      attr_accessor :x
-
-      # @return [Float] Y coordinate
-      attr_accessor :y
-
-      # Payload attached to this {Point}.
-      attr_accessor :data
-
-      # Create a new {Point}.
-      #
-      # @param [Float] x X coordinate
-      # @param [Float] y Y coordinate
-      def initialize(x, y, data=nil)
-        @x = x
-        @y = y
-        @data = data unless data.nil?
-      end
-
-      # This will calculate distance to another, given that they are both
-      # on the same flat two dimensional plane.
-      #
-      # @param [Point] other the other {Point}.
-      # @return [Float] the distance to the other {Point}.
-      def distance_to(other)
-        Math.sqrt((other.x - self.x) ** 2 + (other.y - self.y) ** 2)
-      end
-
-      # This will calculate distance to another point using the Haversine
-      # formula. This means that it will treat #x as longitude and #y as
-      # latitude!
-      #
+  # Simple coordinate object to represent points in some space.
+  class Point
+    # The X coordinate of this instance.
+    # @return [Float, Integer] X coordinate.
+    attr_accessor :x
+
+    # The Y coordinate of this instance.
+    # @return [Float, Integer] Y coordinate.
+    attr_accessor :y
+
+    # Optional payload attached to this instance.
+    # @return [Object] payload attached to this instance.
+    attr_accessor :data
+
+    # @param x [Float, Integer] X coordinate.
+    # @param y [Float, Integer] Y coordinate.
+    # @param data [Object] payload payload attached to this instance
+    #   (optional).
+    # @raise [UnknownTypeError] if one or more input parameters (+x+ and +y+)
+    #   has the wrong type.
+    def initialize(x, y, data = nil)
+      self.x = get_typed_numeric(x)
+      self.y = get_typed_numeric(y)
+
+      self.data = data unless data.nil?
+    end
+
+    #
+    # Create a Hash for this {Point}.
+    #
+    # @return [Hash] Hash representation of this {Point}.
+    #
+    def to_h
+      {
+        'x': x,
+        'y': y,
+        'data': process_data(data)
+      }
+    end
+
+    #
+    # Create a Hash for this {Point}.
+    #
+    # @return [Hash] Hash representation of this {Point}.
+    #
+    def to_hash
+      to_h
+    end
+
+    #
+    # Create a JSON String representation of this {Point}.
+    #
+    # @return [String] JSON String of this {Point}.
+    #
+    def to_json(*_args)
+      require 'json'
+      to_h.to_json
+    end
+
+    #
+    # Create a String for this {Point}.
+    #
+    # @return [String] String representation of this {Point}.
+    #
+    def to_s
+      to_h.to_s
+    end
+
+    #
+    # Construct a {Quadtree::Point} from a JSON String.
+    #
+    # @param [String] json_data input JSON String.
+    #
+    # @return [Quadtree::Point] the {Quadtree::Point} contained in the JSON String.
+    #
+    def self.from_json(json_data)
+      new(json_data['x'], json_data['y'], json_data['data'])
+    end
+
+    # This will calculate distance to another {Point}, given that they are
+    # both in the same 2D space.
+    #
+    # @param other [Point] the other {Point}.
+    # @return [Float] the distance to the other {Point}.
+    def distance_to(other)
+      Math.sqrt((other.x - x)**2 + (other.y - y)**2)
+    end
+
+    # This will calculate distance to another {Point} using the Haversine
+    # formula. This means that it will treat {#x} as longitude and {#y} as
+    # latitude!
+    #
+    # a = sin²(Δφ/2) + cos φ_1 ⋅ cos φ_2 ⋅ sin²(Δλ/2)
+    #
+    # c = 2 ⋅ atan2( √a, √(1−a) )
+    #
+    # d = R ⋅ c
+    #
+    # where φ is latitude, λ is longitude, R is earth’s radius (mean
+    # radius = 6 371 km);
+    # note that angles need to be in radians to pass to trig functions!
+    #
+    # @param other [Point] the other {Point}.
+    # @return [Float] the distance, in meters, to the other {Point}.
+    def haversine_distance_to(other)
+      lat1 = y * (Math::PI / 180.0)
+      lat2 = other.y * (Math::PI / 180.0)
+      dlat = (other.y - y) * (Math::PI / 180.0)
+      dlon = (other.x - x) * (Math::PI / 180.0)
+
       # a = sin²(Δφ/2) + cos φ_1 ⋅ cos φ_2 ⋅ sin²(Δλ/2)
+      a = calculate_haversine_a(lat1, lat2, dlat, dlon)
       # c = 2 ⋅ atan2( √a, √(1−a) )
+      c = 2.0 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
       # d = R ⋅ c
-      #
-      # where φ is latitude, λ is longitude, R is earth’s radius (mean
-      # radius = 6 371 km);
-      # note that angles need to be in radians to pass to trig functions!
-      #
-      # @param [Point] other the other {Point}.
-      # @return [Float] the distance, in meters, to the other {Point}.
-      def haversine_distance_to(other)
-        # earth's radius
-        r = 6371 * 1000.0
-        # coverting degrees to radians
-        lat1 = self.y * (Math::PI / 180)
-        lat2 = other.y * (Math::PI / 180)
-        dlat = (other.y - self.y) * (Math::PI / 180)
-        dlon = (other.x - self.x) * (Math::PI / 180)
-
-        # a = sin²(Δφ/2) + cos φ_1 ⋅ cos φ_2 ⋅ sin²(Δλ/2)
-        a = Math.sin(dlat / 2) * Math.sin(dlat / 2) +
-            Math.cos(lat1) * Math.cos(lat2) *
-            Math.sin(dlon / 2) * Math.sin(dlon / 2)
-        # c = 2 ⋅ atan2( √a, √(1−a) )
-        c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a))
-        # d = R ⋅ c
-        return r * c
-      end
+      6371 * 1000.0 * c
+    end
+
+    private
+
+    def calculate_haversine_a(lat1, lat2, dlat, dlon)
+      Math.sin(dlat / 2.0) * Math.sin(dlat / 2.0) +
+        Math.cos(lat1) * Math.cos(lat2) *
+        Math.sin(dlon / 2.0) * Math.sin(dlon / 2.0)
+    end
+
+    def process_data(data)
+      data.nil? || data.is_a?(Array) || data.is_a?(String) || data.is_a?(Numeric) ? data : data.to_h
+    end
+
+    def get_typed_numeric(any_input)
+      # Try integer first since float will parse integers too
+      return get_integer(any_input) unless get_integer(any_input).nil?
+      # Try Float next
+      return get_float(any_input) unless get_float(any_input).nil?
+
+      raise UnknownTypeError, "Unknown type for parameter: #{any_input.class}"
+    end
+
+    def get_integer(any_input)
+      return Integer(any_input) if any_input.is_a? String
+      return any_input if any_input.is_a? Integer
+
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def get_float(any_input)
+      return Float(any_input) if any_input.is_a? String
+      return any_input if any_input.is_a? Float
+
+      nil
+    rescue StandardError
+      nil
     end
+  end
 end

data/lib/quadtree/quadtree.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
+
 module Quadtree
-  # A Quadtree
+  # A Quadtree.
   class Quadtree
-
     # Arbitrary constant to indicate how many elements can be stored in this
     # quad tree node.
-    # @return [Integer]
+    # @return [Integer] number of {Point}s this {Quadtree} can hold.
     NODE_CAPACITY = 4
 
     # Axis-aligned bounding box stored as a center with half-dimensions to
@@ -18,98 +19,203 @@ module Quadtree
 
     # Children
 
+    # North west corner of this quad.
     # @return [Quadtree]
     attr_accessor :north_west
+
+    # North east corner of this quad.
     # @return [Quadtree]
     attr_accessor :north_east
+
+    # South west corner of this quad.
     # @return [Quadtree]
     attr_accessor :south_west
+
+    # South east corner of this quad.
     # @return [Quadtree]
     attr_accessor :south_east
 
-    def initialize(boundary)
-      @boundary = boundary
-      @points = []
-      @north_west = nil
-      @north_east = nil
-      @south_west = nil
-      @south_east = nil
+    #
+    # Create a new {Quadtree}.
+    #
+    # @param [AxisAlignedBoundingBox] boundary the boundary for this {Quadtree}.
+    # @param [Array<Point>] points any initial {Point}s.
+    # @param [Quadtree] north_west northwestern child {Quadtree}
+    # @param [Quadtree] north_east northeastern child {Quadtree}
+    # @param [Quadtree] south_west southwestern child {Quadtree}
+    # @param [Quadtree] south_east southestern child {Quadtree}
+    #
+    def initialize(boundary, points = [], north_west = nil, north_east = nil, south_west = nil, south_east = nil)
+      self.boundary = boundary
+      self.points = points
+      self.north_west = north_west
+      self.north_east = north_east
+      self.south_west = south_west
+      self.south_east = south_east
+    end
+
+    #
+    # Create a Hash from this {Quadtree}.
+    #
+    # @return [Hash] Hash representation.
+    #
+    def to_h
+      {
+        'boundary': boundary.to_h,
+        'points': points.map(&:to_h),
+        'north_west': north_west.nil? ? nil : north_west.to_h,
+        'north_east': north_east.nil? ? nil : north_east.to_h,
+        'south_west': south_west.nil? ? nil : south_west.to_h,
+        'south_east': south_east.nil? ? nil : south_east.to_h
+      }
+    end
+
+    #
+    # Create a Hash from this {Quadtree}.
+    #
+    # @return [Hash] Hash representation of this {Quadtree}.
+    #
+    def to_hash
+      to_h
+    end
+
+    #
+    # Create a JSON String representation of this {Quadtree}.
+    #
+    # @return [String] JSON String of this {Quadtree}.
+    #
+    def to_json(*_args)
+      require 'json'
+      to_h.to_json
+    end
+
+    #
+    # Create a String for this {Quadtree}.
+    #
+    # @return [String] String representation of this {Quadtree}.
+    #
+    def to_s
+      to_h.to_s
+    end
+
+    #
+    # Construct a Quadtree from a JSON String.
+    #
+    # @param [String] json_data input JSON String.
+    #
+    # @return [Quadtree] the {Quadtree} contained in the JSON String.
+    #
+    def self.from_json(json_data)
+      new(
+        AxisAlignedBoundingBox.from_json(json_data['boundary']),
+        json_data['points'].map { |point_data| Point.from_json(point_data) },
+        json_data['north_west'].nil? ? nil : Quadtree.from_json(json_data['north_west']),
+        json_data['north_east'].nil? ? nil : Quadtree.from_json(json_data['north_east']),
+        json_data['south_west'].nil? ? nil : Quadtree.from_json(json_data['south_west']),
+        json_data['south_east'].nil? ? nil : Quadtree.from_json(json_data['south_east'])
+      )
     end
 
-    # @param [Point] point
-    # @return [Boolean]
+    # Insert a {Point} in this {Quadtree}.
+    #
+    # @param point [Point] the point to insert.
+    # @return [Boolean] +true+ on success, +false+ otherwise.
     def insert!(point)
-      return false unless @boundary.contains_point?(point)
+      return false unless boundary.contains_point?(point)
 
       if points.size < NODE_CAPACITY
-        @points << point
+        points << point
         return true
       end
 
-      subdivide! if @north_west.nil?
-      return true if @north_west.insert!(point)
-      return true if @north_east.insert!(point)
-      return true if @south_west.insert!(point)
-      return true if @south_east.insert!(point)
+      subdivide! if north_west.nil?
+      return true if north_west.insert!(point)
+      return true if north_east.insert!(point)
+      return true if south_west.insert!(point)
+      return true if south_east.insert!(point)
 
       false
     end
 
+    # Return the size of this instance, the number of {Point}s stored in this
+    # {Quadtree}.
+    #
+    # @return [Integer] the size of this instance.
+    def size
+      count = 0
+      count += points.size
+      unless north_west.nil?
+        count += north_west.size
+        count += north_east.size
+        count += south_west.size
+        count += south_east.size
+      end
+      count
+    end
+
     # Finds all points contained within a range.
     #
-    # @param [AxisAlignedBoundingBox] range the range to search within.
-    # @return [Array<Point>]
+    # @param range [AxisAlignedBoundingBox] the range to search within.
+    # @return [Array<Point>] all {Point}s in given range.
     def query_range(range)
       # Prepare an array of results
       points_in_range = []
 
       # Automatically abort if the range does not intersect this quad
-      return points_in_range unless @boundary.intersects?(range)
+      return points_in_range unless boundary.intersects?(range)
 
       # Check objects at this quad level
-      @points.each do |point|
+      points.each do |point|
         points_in_range << point if range.contains_point?(point)
       end
 
       # Terminate here, if there are no children
-      return points_in_range if @north_west.nil?
+      return points_in_range if north_west.nil?
 
       # Otherwise, add the points from the children
-      points_in_range += @north_west.query_range(range)
-      points_in_range += @north_east.query_range(range)
-      points_in_range += @south_west.query_range(range)
-      points_in_range += @south_east.query_range(range)
+      points_in_range += north_west.query_range(range)
+      points_in_range += north_east.query_range(range)
+      points_in_range += south_west.query_range(range)
+      points_in_range += south_east.query_range(range)
 
       points_in_range
     end
 
     private
 
-    # @return [Boolean]
+    # @return [Boolean] +true+ on success, +false+ otherwise.
     def subdivide!
-      left_edge = @boundary.left
-      right_edge = @boundary.right
-      top_edge = @boundary.top
-      bottom_edge = @boundary.bottom
-      quad_half_dimension = @boundary.half_dimension / 2
-
-      north_west_center = Quadtree::Point.new left_edge + quad_half_dimension, top_edge - quad_half_dimension
-      north_east_center = Quadtree::Point.new right_edge - quad_half_dimension, top_edge - quad_half_dimension
-      south_east_center = Quadtree::Point.new left_edge + quad_half_dimension, bottom_edge + quad_half_dimension
-      south_west_center = Quadtree::Point.new right_edge - quad_half_dimension, bottom_edge + quad_half_dimension
-
-      north_west_boundary = Quadtree::AxisAlignedBoundingBox.new north_west_center, quad_half_dimension
-      north_east_boundary = Quadtree::AxisAlignedBoundingBox.new north_east_center, quad_half_dimension
-      south_west_boundary = Quadtree::AxisAlignedBoundingBox.new south_west_center, quad_half_dimension
-      south_east_boundary = Quadtree::AxisAlignedBoundingBox.new south_east_center, quad_half_dimension
-
-      @north_west = Quadtree::Quadtree.new north_west_boundary
-      @north_east = Quadtree::Quadtree.new north_east_boundary
-      @south_west = Quadtree::Quadtree.new south_west_boundary
-      @south_east = Quadtree::Quadtree.new south_east_boundary
+      left_edge = boundary.left
+      right_edge = boundary.right
+      top_edge = boundary.top
+      bottom_edge = boundary.bottom
+      quad_half_dimension = boundary.half_dimension / 2
+
+      north_west_center = Point.new(left_edge + quad_half_dimension,
+                                    top_edge - quad_half_dimension)
+      north_east_center = Point.new(right_edge - quad_half_dimension,
+                                    top_edge - quad_half_dimension)
+      south_east_center = Point.new(left_edge + quad_half_dimension,
+                                    bottom_edge + quad_half_dimension)
+      south_west_center = Point.new(right_edge - quad_half_dimension,
+                                    bottom_edge + quad_half_dimension)
+
+      north_west_boundary = AxisAlignedBoundingBox.new(north_west_center,
+                                                       quad_half_dimension)
+      north_east_boundary = AxisAlignedBoundingBox.new(north_east_center,
+                                                       quad_half_dimension)
+      south_west_boundary = AxisAlignedBoundingBox.new(south_west_center,
+                                                       quad_half_dimension)
+      south_east_boundary = AxisAlignedBoundingBox.new(south_east_center,
+                                                       quad_half_dimension)
+
+      self.north_west = Quadtree.new north_west_boundary
+      self.north_east = Quadtree.new north_east_boundary
+      self.south_west = Quadtree.new south_west_boundary
+      self.south_east = Quadtree.new south_east_boundary
 
       true
-    rescue
+    rescue StandardError
       false
     end
   end