geomodel 0.0.1

data/lib/geomodel/geomath.rb

@@ -0,0 +1,28 @@
+require 'geocoder'
+
+module Geomodel::Math
+  
+  RADIUS = 6378135
+  
+  # Calculates the great circle distance between two points (law of cosines).
+  # 
+  # Args:
+  #   start_point: A geotypes.Point or db.GeoPt indicating the first point.
+  #   end_point_: A geotypes.Point or db.GeoPt indicating the second point.
+  # 
+  # Returns:
+  #   The 2D great-circle distance between the two given points, in meters.
+  #
+  def self.distance(start_point, end_point)
+    start_point_lat = Geocoder::Calculations.to_radians(start_point.latitude)
+    start_point_lon = Geocoder::Calculations.to_radians(start_point.longitude)
+    end_point_lat = Geocoder::Calculations.to_radians(end_point.latitude) 
+    end_point_lon = Geocoder::Calculations.to_radians(end_point.longitude)
+    # work out the internal value for the spherical law of cosines and clamp
+    # it between -1.0 and 1.0 to avoid rounding errors
+    sloc = (Math.sin(start_point_lat) * Math.sin(end_point_lat) +
+            Math.cos(start_point_lat) * Math.cos(end_point_lat) * Math.cos(end_point_lon - start_point_lon))
+    sloc = [[sloc, 1.0].min, -1.0].max
+    RADIUS * Math.acos(sloc)
+  end
+end

data/lib/geomodel/geotypes.rb

@@ -0,0 +1,109 @@
+module Geomodel::Types
+  
+  # A two-dimensional point in the [-90,90] x [-180,180] lat/lon space.
+  # 
+  # Attributes:
+  #   lat: A float in the range [-90,90] indicating the point's latitude.
+  #   lon: A float in the range [-180,180] indicating the point's longitude.
+  # 
+  class Point
+    
+    attr_reader :latitude, :longitude
+    
+    alias_method :lat, :latitude
+    alias_method :lon, :longitude
+    
+    def initialize(latitude, longitude)
+      if -90 > latitude || latitude > 90
+        raise ArgumentError.new("Latitude must be in [-90, 90]") 
+      else
+        @latitude = latitude
+      end 
+      
+      if -180 > longitude || longitude > 180
+        raise ArgumentError.new("Longitude must be in [-180, 180]") 
+      else
+        @longitude = longitude
+      end        
+    end
+    
+    def ==(point)
+      (@latitude === point.latitude) && (@longitude === point.longitude)
+    end
+    
+    def to_s
+      "(#{@latitude}, #{@longitude})"
+    end
+    
+  end
+  
+  #   A two-dimensional rectangular region defined by NE and SW points.
+  # 
+  #   Attributes:
+  #     north_east: A read-only geotypes.Point indicating the box's Northeast
+  #         coordinate.
+  #     south_west: A read-only geotypes.Point indicating the box's Southwest
+  #         coordinate.
+  #     north: A float indicating the box's North latitude.
+  #     east: A float indicating the box's East longitude.
+  #     south: A float indicating the box's South latitude.
+  #     west: A float indicating the box's West longitude.
+  # 
+  class Box
+    attr_reader :north_east, :south_west
+    
+    def initialize(north, east, south, west)
+      south, north = north, south if south > north
+      
+      # Don't swap east and west to allow disambiguation of
+      # antimeridian crossing.
+      @north_east = Point.new(north, east)
+      @south_west = Point.new(south, west)
+    end
+    
+    def north=(north)
+      raise ArgumentError.new("Latitude must be north of box's south latitude") if north < @south_west.latitude
+      @north_east.latitude = north
+    end
+    
+    def east=(east)
+      @north_east.longitude = east
+    end
+    
+    def south=(south)
+      raise ArgumentError.new("Latitude must be south of box's north latitude") if south > @south_west.latitude
+      @south_west.latitude = south
+    end
+    
+    def west=(west)
+      @south_west.longitude = west
+    end
+    
+    def north
+      @north_east.latitude
+    end
+    
+    def east
+      @north_east.longitude
+    end
+    
+    def south
+      @south_west.latitude
+    end
+    
+    def west
+      @south_west.longitude
+    end
+    
+    def ==(box)
+      (@north_east === box.north_east) && (@south_west === box.south_west)
+    end
+    
+    def to_s
+      "(#{@north_east.latitude}, #{@north_east.longitude}, #{@south_west.latitude}, #{@south_west.longitude})"
+    end
+    
+  end
+end
+
+

data/lib/geomodel/util.rb

@@ -0,0 +1,51 @@
+module Geomodel::Util
+  
+  def self.merge_in_place(target, arrays, dup_func = nil, comp_func = nil)
+    arrays.each do |array| 
+      array.each do |element|
+        target.push(element) 
+      end
+    end
+
+    comp_func.nil? ? target.sort! : target.sort!(&comp_func)
+    dup_func.nil? ? target.uniq! : target.uniq!(&dup_func)
+  end
+  
+  # Returns the edges of the rectangular region containing all of the
+  # given geocells, sorted by distance from the given point, along with
+  # the actual distances from the point to these edges.
+  # 
+  # Args:
+  #   cells: The cells (should be adjacent) defining the rectangular region
+  #       whose edge distances are requested.
+  #   point: The point that should determine the edge sort order.
+  # 
+  # Returns:
+  #   A list of (direction, distance) tuples, where direction is the edge
+  #   and distance is the distance from the point to that edge. A direction
+  #   value of (0,-1), for example, corresponds to the South edge of the
+  #   rectangular region containing all of the given geocells.
+  # 
+  def self.distance_sorted_edges(cells, point)
+
+    # TODO(romannurik): Assert that lat,lon are actually inside the geocell.
+    boxes = cells.map { |cell| Geomodel::GeoCell.compute_box(cell) }
+
+    max_box = Geomodel::Types::Box.new(
+      boxes.map(&:north).max,
+      boxes.map(&:east).max,
+      boxes.map(&:south).max,
+      boxes.map(&:west).max
+    )
+    
+    dist_south = Geomodel::Math.distance(Geomodel::Types::Point.new(max_box.south, point.longitude), point)
+    dist_north = Geomodel::Math.distance(Geomodel::Types::Point.new(max_box.north, point.longitude), point)
+    dist_west = Geomodel::Math.distance(Geomodel::Types::Point.new(point.latitude, max_box.west), point)
+    dist_east = Geomodel::Math.distance(Geomodel::Types::Point.new(point.latitude, max_box.east), point)
+        
+    [
+      [Geomodel::GeoCell::SOUTH, dist_south], [Geomodel::GeoCell::NORTH, dist_north], [Geomodel::GeoCell::WEST, dist_west], [Geomodel::GeoCell::EAST, dist_east]
+    ].sort { |x, y| x[1] <=> y[1] }.transpose
+  end
+  
+end

data/lib/geomodel/version.rb

@@ -0,0 +1,3 @@
+module Geomodel
+  VERSION = "0.0.1"
+end

data/spec/geocell_spec.rb

@@ -0,0 +1,154 @@
+require 'spec_helper'
+
+describe 'Geomodel::GeoCell' do
+
+  it "can compute a valid geocell" do
+    cell = Geomodel::GeoCell.compute(Geomodel::Types::Point.new(37, -122), 14)
+    
+    expect(cell.size).to eq(14)
+    expect(Geomodel::GeoCell.is_valid(cell)).to be_true
+    expect(Geomodel::GeoCell.contains_point(cell, Geomodel::Types::Point.new(37, -122)))
+  end
+  
+  it "can determined if a geocell is invalid" do
+    cell = Geomodel::GeoCell.compute(Geomodel::Types::Point.new(0, 0), 0)
+    
+    expect(cell.size).to eq(0)
+    expect(Geomodel::GeoCell.is_valid(cell)).to be_false
+  end
+  
+  it "contains a lower resolution cell containing the same point as a prefix" do
+    cell = Geomodel::GeoCell.compute(Geomodel::Types::Point.new(37, -122), 14)
+    lowres_cell = Geomodel::GeoCell.compute(Geomodel::Types::Point.new(37, -122), 8)
+    
+    expect(cell.start_with?(lowres_cell)).to be_true
+    expect(Geomodel::GeoCell.contains_point(lowres_cell, Geomodel::Types::Point.new(37, -122)))
+  end
+  
+  it "can compute a box" do
+    cell = Geomodel::GeoCell.compute(Geomodel::Types::Point.new(37, -122), 14)
+    box = Geomodel::GeoCell.compute_box(cell)
+    
+    expect(box.south).to be <= 37 
+    expect(box.north).to be >= 37
+    expect(box.west).to be <= -122
+    expect(box.east).to be >= -122
+  end
+  
+  it "can determine adjacency using bounding boxes" do
+    cell = Geomodel::GeoCell.compute(Geomodel::Types::Point.new(37, -122), 14)
+    box = Geomodel::GeoCell.compute_box(cell)
+    
+    adjacent_south = Geomodel::GeoCell.adjacent(cell, [0, 1])
+    adjacent_north = Geomodel::GeoCell.adjacent(cell, [0, -1])
+    adjacent_west = Geomodel::GeoCell.adjacent(cell, [1, 0])
+    adjacent_east = Geomodel::GeoCell.adjacent(cell, [-1, 0])
+    
+    adjacent_south_box = Geomodel::GeoCell.compute_box(adjacent_south)
+    adjacent_north_box = Geomodel::GeoCell.compute_box(adjacent_north)
+    adjacent_west_box = Geomodel::GeoCell.compute_box(adjacent_west)
+    adjacent_east_box = Geomodel::GeoCell.compute_box(adjacent_east)
+    
+    all_adjacents = Geomodel::GeoCell.all_adjacents(cell)
+    
+    expect(adjacent_south_box.north).to be_within(0.00001).of(box.north)
+    expect(adjacent_north_box.south).to be_within(0.00001).of(box.south)
+    expect(adjacent_west_box.east).to be_within(0.00001).of(box.east)
+    expect(adjacent_east_box.west).to be_within(0.00001).of(box.west)
+    expect(all_adjacents.size).to eq(8)
+  end
+  
+  it "can determine collinearity" do
+    cell = Geomodel::GeoCell.compute(Geomodel::Types::Point.new(37, -122), 14)
+    
+    adjacent_south = Geomodel::GeoCell.adjacent(cell, [0, 1])
+    adjacent_west = Geomodel::GeoCell.adjacent(cell, [1, 0])
+
+    expect(Geomodel::GeoCell.collinear(cell, adjacent_south, true)).to be_true
+    expect(Geomodel::GeoCell.collinear(cell, adjacent_south, false)).to be_false
+    expect(Geomodel::GeoCell.collinear(cell, adjacent_west, false)).to be_true
+    expect(Geomodel::GeoCell.collinear(cell, adjacent_west, true)).to be_false
+  end
+
+  it "can be interpolated" do
+    cell = Geomodel::GeoCell.compute(Geomodel::Types::Point.new(37, -122), 14)
+    
+    sw_adjacent = Geomodel::GeoCell.adjacent(cell, [-1, -1])
+    sw_adjacent2 = Geomodel::GeoCell.adjacent(sw_adjacent, [-1, -1])
+    
+    # interpolate between a cell and south-west adjacent, should return
+    # 4 total cells
+    expect(Geomodel::GeoCell.interpolate(cell, sw_adjacent).size).to eq(4)
+    expect(Geomodel::GeoCell.interpolation_count(cell, sw_adjacent)).to eq(4)
+
+    # interpolate between a cell and the cell SW-adjacent twice over,
+    # should return 9 total cells
+    expect(Geomodel::GeoCell.interpolate(cell, sw_adjacent2).size).to eq(9)
+    expect(Geomodel::GeoCell.interpolation_count(cell, sw_adjacent2)).to eq(9)    
+  end
+  
+  it "can create the best bounding box across a major cell boundary" do
+    bbox = Geomodel::Types::Box.new(43.195111, -89.998193, 43.19302, -90.002356)
+    geocells = Geomodel::GeoCell.best_bbox_search_cells(bbox, Geomodel::DEFAULT_COST_FUNCTION)
+    
+    expect(geocells.size).to be(16)
+    expect(geocells).to include(
+      "8ff77dfd4", "8ff77dfd5", "8ff77dfd6", "8ff77dfd7", "8ff77dfdc", "8ff77dfdd", 
+      "8ff77dfde", "8ff77dfdf", "9aa228a80", "9aa228a81", "9aa228a82", "9aa228a83", 
+      "9aa228a88", "9aa228a89", "9aa228a8a", "9aa228a8b"
+    )
+  end
+  
+  it "can create the best bounding box at the maximum resolution" do
+    bbox = Geomodel::Types::Box.new(43.195110, -89.998193, 43.195110, -89.998193)
+    geocells = Geomodel::GeoCell.best_bbox_search_cells(bbox, lambda { |num_cells, resolution|
+      resolution <= Geomodel::GeoCell::MAX_GEOCELL_RESOLUTION ? 0 : Math.exp(10000)
+    })
+    
+    expect(geocells.size).to be(1)
+    expect(geocells).to include("9aa228a8b3b00")
+  end
+  
+  # TODO implement these tests!
+  
+  #   @Test
+  # public void testBestBoxSearchOnAntimeridian() {
+  #   float east = 64.576263f;
+  #   float west = 87.076263f;
+  #   float north = 76.043611f;
+  #   float south = -54.505934f;
+  #   Set<String> antimeridianSearch = new HashSet<String>(GeocellManager.bestBboxSearchCells(new BoundingBox(north,east,south,west), null));
+  #   
+  #   List<String> equivalentSearchPart1 = GeocellManager.bestBboxSearchCells(new BoundingBox(north,east,south,-180.0f), null);
+  #   List<String> equivalentSearchPart2 = GeocellManager.bestBboxSearchCells(new BoundingBox(north,180.0f,south,west), null);
+  #   Set<String> equivalentSearch = new HashSet<String>();
+  #   equivalentSearch.addAll(equivalentSearchPart1);
+  #   equivalentSearch.addAll(equivalentSearchPart2);
+  #   
+  #   assertEquals(equivalentSearch, antimeridianSearch);
+  # }
+  
+  #   @Test
+  # public void testBestBoxWithCustomCostFunction() {
+  #   final int numCellsMax = 30;
+  #   BoundingBox bb = new BoundingBox(38.912056, -118.40747, 35.263195, -123.88965);
+  # 
+  #   List<String> cells = GeocellManager.bestBboxSearchCells(bb, new CostFunction() {
+  # 
+  #   @Override
+  # 
+  #   public double defaultCostFunction(int numCells, int resolution)
+  # 
+  #   {
+  #   // Here we ensure that we do not try to query more than 30 cells, the limit of a gae IN filter
+  #   return numCells > numCellsMax ? Double.MAX_VALUE : 0;
+  #   }
+  # 
+  #   });
+  #   
+  #   assertTrue(cells != null);
+  #   assertTrue(cells.size() > 0);
+  #   assertTrue(cells.size() <= numCellsMax);
+  # }
+  
+end

data/spec/geomath_spec.rb

@@ -0,0 +1,55 @@
+require 'spec_helper'
+require 'hashie'
+
+describe 'Geomodel::Math' do
+  
+  it 'can compute the distance between two points' do
+    [ # lat a, lon a, lat b, lon b, distance
+      [ 37,     -122,   42,     -75,      4024365   ],
+      [ 36.12,  -86.67, 33.94,  -118.40,  2889677.0 ],
+    ].each do |lat_a, lon_a, lat_b, lon_b, expected_dist|
+      # known distances using GLatLng from the Maps API
+      point_a = Hashie::Mash.new
+      point_a.latitude = lat_a
+      point_a.longitude = lon_a
+    
+      point_b = Hashie::Mash.new
+      point_b.latitude = lat_b
+      point_b.longitude = lon_b    
+    
+      half_of_a_percent = expected_dist / 200
+    
+      calc_dist = Geomodel::Math.distance(point_a, point_b)
+
+      expect(calc_dist).to be_within(half_of_a_percent).of(expected_dist)
+    end
+  end
+  
+  # Test location that can cause math domain error (due to rounding) unless
+  # the distance function clamps the spherical law of cosines value between
+  # -1.0 and 1.0.  
+  it 'can compute the distance correctly for in spite of rounding errors' do
+    point_a = Hashie::Mash.new
+    point_a.latitude = 47.291288
+    point_a.longitude = 8.56613
+    
+    point_b = Hashie::Mash.new
+    point_b.latitude = 47.291288
+    point_b.longitude = 8.56613
+    
+    calc_dist = Geomodel::Math.distance(point_a, point_b)    
+    expected_dist = 0.0
+  
+    expect(calc_dist).to eq(expected_dist)
+  end
+  
+  # TODO: implement this test
+  
+  # 
+  # @Test
+  # public void testInterpolationForEdgeCase() {
+  #   
+  #   assertTrue(GeocellUtils.interpolationCount("8e6f727a6b0dd", "8e1d5c3ce9aff") > 0);
+  # }
+
+end

data/spec/geomodel_spec.rb

@@ -0,0 +1,89 @@
+require 'spec_helper'
+require 'hashie'
+
+describe 'Geomodel' do
+  
+  before(:all) do
+    class Entity
+      attr_accessor :id, :location, :geocells
+      
+      def to_s
+        self.id
+      end
+    end
+    
+    @flatiron = Entity.new
+    @flatiron.id = 'Flatiron'
+    @flatiron.location = Geomodel::Types::Point.new(40.7407092, -73.9894039)
+    
+    @outback = Entity.new
+    @outback.id = 'Outback Steakhouse'
+    @outback.location = Geomodel::Types::Point.new(40.7425610, -73.9922670)
+    
+    @museum_of_sex = Entity.new
+    @museum_of_sex.id = 'Museum of Sex'
+    @museum_of_sex.location = Geomodel::Types::Point.new(40.7440290, -73.9873500)
+    
+    @wolfgang = Entity.new
+    @wolfgang.id = 'Wolfgang Steakhouse'
+    @wolfgang.location = Geomodel::Types::Point.new(40.7466230, -73.9820620)
+    
+    @morgan = Entity.new
+    @morgan.id ='Morgan Library'
+    @morgan.location = Geomodel::Types::Point.new(40.7493672, -73.9817685)
+    
+    @places = [@flatiron, @outback, @museum_of_sex, @wolfgang, @morgan]
+    
+    @places.each do |place|
+      place.geocells = Geomodel::GeoCell.generate_geocells(place.location)
+    end
+    
+    @query_runner = lambda do |geocells|
+      result = @places.reject do |o| 
+        (o.geocells & geocells).length < 0
+      end 
+
+      result
+    end
+  end
+  
+  it "can calculate the geocells for a bounding box using the default cost function" do
+    cell = Geomodel::GeoCell.compute(Geomodel::Types::Point.new(37, -122), 14)
+    bounding_box = Geomodel::GeoCell.compute_box(cell)
+    geocells = Geomodel.geocells_for_bounding_box(bounding_box)
+    
+    expect(geocells.size).to be(2)
+    expect(geocells).to include("8e6187fe6187f", "8e6187fe618d5")
+  end
+  
+  it "can find nearby locations given a location (lat & lon) and a radius in meters" do
+    results = Geomodel.proximity_fetch(@flatiron.location, @query_runner, 5, 500)
+    places = results.map(&:first)
+    distances = results.map(&:last)
+    
+    expect(results.size).to be(3)
+    expect(places).to include(@flatiron, @outback, @museum_of_sex)
+    expect(distances.max).to be <= 500
+  end
+  
+  it "respects the max results parameters in a search by proximity" do
+    results = Geomodel.proximity_fetch(@flatiron.location, @query_runner, 2, 500)
+    places = results.map(&:first)
+    distances = results.map(&:last)
+    
+    expect(results.size).to be(2)
+    expect(places).to include(@flatiron, @outback)
+    expect(distances.max).to be <= 500
+  end
+  
+  it "respects the max results parameters in a search by proximity" do
+    results = Geomodel.proximity_fetch(@flatiron.location, @query_runner, 5, 1000)
+    places = results.map(&:first)
+    distances = results.map(&:last)
+    
+    expect(results.size).to be(4)
+    expect(places).to include(@flatiron, @outback, @museum_of_sex, @wolfgang)
+    expect(distances.max).to be <= 1000
+  end
+
+end