geomodel 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b8914e3d585af5281290b7a854cb1eec6d7a566c
+  data.tar.gz: 30b52b4cb9989bf752dbe9fb426f71607ef5858c
+SHA512:
+  metadata.gz: b170a8372a165c3bdad452588f7ffad1174996b448076f8a139bd0ee48bd83924ef1a4420734d9c98f8106239ce2fb601d0cd525350a4b692662f68847d61e80
+  data.tar.gz: 13298af29d84898c152475a74ffc11d917507224a5f2a36b5e2cd3bc0c6e4e0e18fbca99366c8c545771c0076e5daf02421d53d2200d92e2ec2d1a63e6cda41f

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--format documentation

data/.ruby-gemset

@@ -0,0 +1 @@
+geomodel

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+notifications:
+  email:
+    - bsbodden@integrallis.com

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+### 0.0.1 (January 2, 2014)
+  * Initial release - Straight port from Python, Java and JS implementations

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in geomodel.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Integrallis Software & Brian Sam-Bodden
+
+MIT License
+
+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.md

@@ -0,0 +1,192 @@
+# Geomodel
+
+[![Build Status](https://secure.travis-ci.org/integrallis/geomodel.png?branch=master)](http://travis-ci.org/integrallis/geomodel) 
+[![Gem Version](https://badge.fury.io/rb/geomodel.png)](http://badge.fury.io/rb/geomodel)
+[![Dependency Status](https://gemnasium.com/integrallis/geomodel.png)](https://gemnasium.com/integrallis/geomodel) 
+[![Code Climate](https://codeclimate.com/github/integrallis/geomodel.png)](https://codeclimate.com/github/integrallis/geomodel)
+[![Coverage Status](https://coveralls.io/repos/integrallis/geomodel/badge.png?branch=master)](https://coveralls.io/r/integrallis/geomodel?branch=master)
+
+Geomodel aims to provide a generalized solution for performing basic indexing 
+and querying of geospatial data in non-relation environments. At the core, this 
+solution utilizes geohash-like objects called geocells.
+
+A geocell is a hexadecimal string that defines a two dimensional rectangular
+region inside the [-90,90] x [-180,180] latitude/longitude space. A geocell's
+'resolution' is its length. For most practical purposes, at high resolutions,
+geocells can be treated as single points.
+
+Much like geohashes (see http://en.wikipedia.org/wiki/Geohash), geocells are 
+hierarchical, in that any prefix of a geocell is considered its ancestor, with
+geocell[:-1] being geocell's immediate parent cell.
+
+To calculate the rectangle of a given geocell string, first divide the
+[-90,90] x [-180,180] latitude/longitude space evenly into a 4x4 grid like so:
+
+<pre>
+               +---+---+---+---+ (90, 180)
+               | a | b | e | f |
+               +---+---+---+---+
+               | 8 | 9 | c | d |
+               +---+---+---+---+
+               | 2 | 3 | 6 | 7 |
+               +---+---+---+---+
+               | 0 | 1 | 4 | 5 |
+    (-90,-180) +---+---+---+---+
+</pre>
+
+NOTE: The point (0, 0) is at the intersection of grid cells 3, 6, 9 and c. And,
+for example, cell 7 should be the sub-rectangle from (-45, 90) to (0, 180).   
+
+Calculate the sub-rectangle for the first character of the geocell string and
+re-divide this sub-rectangle into another 4x4 grid. For example, if the geocell
+string is '78a', we will re-divide the sub-rectangle like so:
+
+<pre>
+                 .                   .
+                 .                   .
+             . . +----+----+----+----+ (0, 180)
+                 | 7a | 7b | 7e | 7f |
+                 +----+----+----+----+
+                 | 78 | 79 | 7c | 7d |
+                 +----+----+----+----+
+                 | 72 | 73 | 76 | 77 |
+                 +----+----+----+----+
+                 | 70 | 71 | 74 | 75 |
+    . . (-45,90) +----+----+----+----+
+                 .                   .
+                 .                   .
+</pre>
+
+Continue to re-divide into sub-rectangles and 4x4 grids until the entire
+geocell string has been exhausted. The final sub-rectangle is the rectangular
+region for the geocell.
+
+A geocell can be associated with a single geographic point and subsequently 
+indexed and filtered by either conformance to a bounding box or by proximity 
+(nearest-n) to a search center point.
+
+# Approach
+
+This Ruby implementation of GeoModel is based on the Python, Java and JavaScript implementations. 
+It's implemented as class level methods contained modules and a few datatype classes. So the 'model' 
+part isn't quite there and I don't really see a need for it. Since the library is meant to be use in 
+Non-Relational/Non-ORM environmets, binding the functions/methods to a model does not make much sense. 
+The model part was mostly implemented in the other libraries to bind directly to Google App Engine.
+
+# References
+
+- http://code.google.com/p/javageomodel/
+- http://code.google.com/p/geomodel/
+- https://github.com/danieldkim/geomodel
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'geomodel'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install geomodel
+
+## Usage
+
+Currently, only single-point entities and two types of basic geospatial queries
+on those entities are supported.
+
+### Representing your locations
+
+You'll need a class to hold a geolocation. It assumes that an "entity" has a unique 
+"id" (specific field can be configure), a latitude/longitude combination stored in 
+a "location" field (a Geomodel::Types::Point) and a collection of "geocells".
+
+```ruby
+class Entity
+  attr_accessor :id, :location, :geocells
+  
+  def to_s
+    self.id
+  end
+end
+```
+
+An instance of one of these entities can be instantiated as shown next. Let's say we
+wanted to create an entity for the Frank Lloyd Wright Iconic Desert Spire in Scottsdale, AZ
+(http://livebetterinscottsdale.com/2012/02/things-to-see-in-scottsdale-az-the-frank-lloyd-wright-spire/):
+
+```ruby
+flw_spire = Entity.new
+flw_spire.id = 'Flatiron'
+flw_spire.location = Geomodel::Types::Point.new(33.633406, -111.916803)
+flw_spire.geocells = Geomodel::GeoCell.generate_geocells(flw_spire.location)
+```
+
+### Bounding Box Queries
+
+```ruby
+# compute a geocell for the location using a resolution of 14
+cell = Geomodel::GeoCell.compute(flw_spire.location, 14)
+
+# create a bounding box for the cell
+bounding_box = Geomodel::GeoCell.compute_box(cell)
+
+# get a list of geocells for the given bounding box
+geocells = Geomodel.geocells_for_bounding_box(bounding_box)
+
+# use the bounding box geocells to do a key lookup in your database assuming that there is
+# a location_geocell 'column' and you can do an IN query like:
+result_set = my_db.query('SELECT * WHERE location_geocells IN (?)', query_geocells)
+
+# the results then can be filtered by whether they fall inside the bounding box using:
+matches = Geomodel.filter_result_set_by_bounding_box(bounding_box, result_set)
+```
+
+### proximity (nearest-n) queries
+
+Find nearby locations given a location (lat & lon) and a radius in meters:
+
+```ruby
+
+# a list of places (instance of Entity or object that responds to :id, :location, :geocells)
+places = [place1, place2, place3, ...]
+
+# a function that can query your database. It takes as a parameter an array of geocells (strings)
+# that are used to filter the query (below is an in-memory implementation using the 'places' array
+# as our datasource)
+query_runner = lambda do |geocells|
+  result = places.reject do |o| 
+    (o.geocells & geocells).length < 0
+  end 
+
+  result
+end
+
+# query for a maximum of 20 results, 15 miles (~24140 meters) from the Frank Lloyd Wright Spire
+# results are tuples (2 element arrays) with the matching entity and its distance from the location
+results = Geomodel.proximity_fetch(flw_spire.location, query_runner, 20, 24140)
+
+# extract the matching places
+places = results.map(&:first)
+
+# extract the distances
+distances = results.map(&:last)
+
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+MIT License

data/Rakefile

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+ 
+#--
+# Copyright &169;2001-2014 Integrallis Software, LLC. 
+# All Rights Reserved.
+# 
+# Permission is granted for use, copying, modification, distribution,
+# and distribution of modified versions of this work as long as the
+# above copyright notice is included.
+#++
+
+# encoding: utf-8
+
+# --------------------------------------------------------------------
+require 'rubygems'
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/geomodel.gemspec

@@ -0,0 +1,35 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'geomodel/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'geomodel'
+  spec.version       = Geomodel::VERSION
+  spec.authors       = ['Brian Sam-Bodden']
+  spec.email         = ['bsbodden@integrallis.com']
+  spec.description   = %q{A Ruby implementation of the Geomodel concept}
+  spec.summary       = %q{Geomodel aims to provide a generalized solution for performing basic indexing 
+  and querying of geospatial data in non-relation environments. At the core, this 
+  solution utilizes geohash-like objects called geocells.}
+  spec.homepage      = 'https://github.com/integrallis/geomodel'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+  
+  spec.add_dependency 'geocoder', '~> 1.1.9'
+  spec.add_dependency 'hashie', '~> 2.0.5'
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'hashie'
+  spec.add_development_dependency 'debugger'
+  spec.add_development_dependency 'launchy'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'coveralls'
+end

data/lib/geomodel.rb

@@ -0,0 +1,158 @@
+require "geomodel/version"
+require "geomodel/geomath"
+require "geomodel/geotypes"
+require "geomodel/geocell"
+require "geomodel/util"
+require 'set'
+
+module Geomodel
+  
+  # The default cost function, used if none is provided              
+  DEFAULT_COST_FUNCTION = lambda do |num_cells, resolution|
+    num_cells > (Geomodel::GeoCell::GEOCELL_GRID_SIZE ** 2) ? 1e10000 : 0
+  end
+  
+  # Retrieve the geocells to be used in a bounding box query
+  # Something like geocells IN (...)
+  # 
+  # Args:
+  #
+  #   bbox: A geotypes.Box indicating the bounding box to filter entities by.
+  #   cost_function: An optional function that accepts two arguments:
+  #       * num_cells: the number of cells to search
+  #       * resolution: the resolution of each cell to search
+  #       and returns the 'cost' of querying against this number of cells
+  #       at the given resolution.
+  def self.geocells_for_bounding_box(bounding_box, cost_function = nil)
+    cost_function = DEFAULT_COST_FUNCTION if cost_function.nil?
+    Geomodel::GeoCell.best_bbox_search_cells(bounding_box, cost_function)
+  end
+  
+  # Given a result set from your datastore (a query you filtered with
+  # #geocells_for_bounding_box) it will filter the records that land outside
+  # of the given bounding box (generally you'll use the same bounding box used
+  # in #geocells_for_bounding_box)
+  def self.filter_result_set_by_bounding_box(bounding_box, result_set)
+    result_set.select do |row|
+      row.latitude >= bounding_box.south &&
+      row.latitude <= bounding_box.north &&
+      row.longitude >= bounding_box.west &&
+      row.longitude <= bounding_box.east
+    end
+  end
+  
+  #   center: A geotypes.Point or db.GeoPt indicating the center point around
+  #       which to search for matching entities.
+  #   max_results: An int indicating the maximum number of desired results.
+  #       The default is 10, and the larger this number, the longer the fetch
+  #       will take.
+  #   max_distance: An optional number indicating the maximum distance to
+  #       search, in meters.
+  def self.proximity_fetch(center, query_runner, max_results = 10, max_distance = 0)
+    results = []
+  
+    searched_cells = Set.new
+    
+    # The current search geocell containing the lat,lon.
+    cur_containing_geocell = Geomodel::GeoCell.compute(center)
+    
+    # The currently-being-searched geocells.
+    # NOTES:
+    #     * Start with max possible.
+    #     * Must always be of the same resolution.
+    #     * Must always form a rectangular region.
+    #     * One of these must be equal to the cur_containing_geocell.
+    cur_geocells = [cur_containing_geocell]
+  
+    closest_possible_next_result_dist = 0
+    
+    # Assumes both a and b are lists of (entity, dist) tuples, *sorted by dist*.
+    # NOTE: This is an in-place merge, and there are guaranteed
+    # no duplicates in the resulting list.
+    
+    cmp_fn = lambda do |x, y| 
+      (!x.empty? && !y.empty?) ? x[1] <=> y[1] : 0
+    end
+    
+    dup_fn = lambda do |x| 
+      (x.nil? || x.empty?) ? nil : x[0].id 
+    end # assuming the the element responds to #id
+  
+    sorted_edges = [[0,0]]
+    sorted_edge_distances = [0]
+    
+    while !cur_geocells.empty?
+      closest_possible_next_result_dist = sorted_edge_distances[0]
+      
+      next if max_distance and closest_possible_next_result_dist > max_distance
+  
+      cur_geocells_unique = cur_geocells - searched_cells.to_a
+  
+      # Run query on the next set of geocells.
+      cur_resolution = cur_geocells[0].size
+
+      # Update results and sort.
+      new_results = query_runner.call(cur_geocells_unique)
+  
+      searched_cells.merge(cur_geocells)
+  
+      # Begin storing distance from the search result entity to the
+      # search center along with the search result itself, in a tuple.
+      new_results = new_results.map { |entity|  [entity, Geomodel::Math.distance(center, entity.location)] }
+      new_results.sort! { |x, y| (!x.empty? && !y.empty?) ? x[1] <=> y[1] : 0 }
+      new_results = new_results[0...max_results]
+  
+      # Merge new_results into results or the other way around, depending on
+      # which is larger.
+      if results.size > new_results.size
+        Geomodel::Util.merge_in_place(results, [new_results], dup_fn, cmp_fn)
+      else
+        Geomodel::Util.merge_in_place(new_results, [results], dup_fn, cmp_fn)
+        results = new_results
+      end
+
+      results = results[0...max_results]
+  
+      sorted_edges, sorted_edge_distances = Geomodel::Util.distance_sorted_edges(cur_geocells, center)
+  
+      if results.empty? || cur_geocells.size == 4
+        # Either no results (in which case we optimize by not looking at adjacents, go straight to the parent) 
+        # or we've searched 4 adjacent geocells, in which case we should now search the parents of those
+        # geocells.
+        cur_containing_geocell = cur_containing_geocell[0...-1]
+        cur_geocells = cur_geocells.map { |cell| cell[0...-1] }   
+        break if !cur_geocells.empty? || !cur_geocells[0] # Done with search, we've searched everywhere.
+      elsif cur_geocells.size == 1
+        # Get adjacent in one direction.
+        # TODO(romannurik): Watch for +/- 90 degree latitude edge case geocells.
+        nearest_edge = sorted_edges[0]
+        cur_geocells << Geomodel::GeoCell.adjacent(cur_geocells[0], nearest_edge)
+      elsif cur_geocells.size == 2
+        # Get adjacents in perpendicular direction.
+        nearest_edge = Geomodel::Util.distance_sorted_edges([cur_containing_geocell], center)[0][0]
+        if nearest_edge[0] == 0
+          # Was vertical, perpendicular is horizontal.
+          perpendicular_nearest_edge = sorted_edges.keep_if { |x| x[0] != 0 }.first
+        else
+          # Was horizontal, perpendicular is vertical.
+          perpendicular_nearest_edge = sorted_edges.keep_if { |x| x[0] == 0 }.first
+        end
+        
+        cur_geocells.concat(
+          cur_geocells.map { |cell| Geomodel::GeoCell.adjacent(cell, perpendicular_nearest_edge) } 
+        )
+      end
+      
+      # We don't have enough items yet, keep searching.
+      next if results.size < max_results
+  
+      # If the currently max_results'th closest item is closer than any
+      # of the next test geocells, we're done searching.
+      current_farthest_returnable_result_dist = Geomodel::Math.distance(center, results[max_results - 1][0].location)
+      break if (closest_possible_next_result_dist >= current_farthest_returnable_result_dist)
+    end
+    
+    results[0...max_results].keep_if { |result| max_distance == 0 || result.last < max_distance }  
+  end
+  
+end