geospatial 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2a5d010173b1e91d60be3e2c07e0e89a95ccb000
-  data.tar.gz: 5df99174a2639bc48dca1b84f26a149e2c8b3e92
+  metadata.gz: 2f5c7adeba4a6c4c4773d3f05ce924da0287e1b4
+  data.tar.gz: f927b7952f48e67dd30df8c6076aa4d590d8f5cc
 SHA512:
-  metadata.gz: c4eb89aa1b47b77313d8c68abaa95d2d83660b040dead60be19823d69fc5aeb0b4c67d529caf573e677ab4eba7496673c3859797bafc2f0ba0cec3fd52bc31c9
-  data.tar.gz: 3177ebab37d176ec50b98db396ce0cb964a071e5f8994ae2d14f1da00d0ca4023a7aac13126cfaca96c5870cbae02d5b0544f321b79bde38793521edaf2057f8
+  metadata.gz: bb6ad414765df8a2c66706c1b157b51355b0e717fd1a9e779455bffc10c8d8a338c0f9c27171ca5023d78d5824414fe2c919be315c277380f4bebb73e6bda4c2
+  data.tar.gz: 4f1f8d46e132ec47cbb07ee5c361b5215088e816514e254d85f40405e8fb5fa0f77fd32cc1d696f73ac0c0a424a2dd7ebc1db6f5fb4c4136a3b10dd20289990a

data/.gitignore

@@ -20,3 +20,4 @@ tmp
 *.o
 *.a
 mkmf.log
+.tags*

data/.travis.yml

@@ -1,5 +1,14 @@
 language: ruby
+sudo: false
 rvm:
-  - "2.0"
-  - "2.1"
+  - 2.1.8
+  - 2.2.4
+  - 2.3.0
+  - ruby-head
+  - rbx-2
 env: COVERAGE=true
+matrix:
+  fast_finish: true
+  allow_failures:
+    - rvm: "ruby-head"
+    - rvm: "rbx-2"

data/Gemfile

@@ -1,4 +1,15 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in geospatial.gemspec
+# Specify your gem's dependencies in build.gemspec
 gemspec
+
+group :development do
+	gem 'pry'
+end
+
+group :test do
+	gem 'simplecov'
+	gem 'coveralls', require: false
+	
+	gem "prawn"
+end

data/README.md

@@ -1,28 +1,57 @@
 # Geospatial
 
-Geospatial provides abstractions for dealing with geographical locations efficiently.
+![Australia Hilbert Curve](australia.png?raw=true "Australia Hilbert Curve Visualisation")
 
-[![Build Status](https://secure.travis-ci.org/ioquatix/geospatial.png)](http://travis-ci.org/ioquatix/geospatial)
-[![Code Climate](https://codeclimate.com/github/ioquatix/geospatial.png)](https://codeclimate.com/github/ioquatix/geospatial)
+Geospatial provides abstractions for dealing with geographical locations efficiently. It is not a generic point/line/polygon handling library like [RGeo](https://github.com/rgeo/rgeo), but a specially crafted library to deal with querying for points on a map efficiently.
+
+[![Build Status](https://secure.travis-ci.org/ioquatix/geospatial.svg)](http://travis-ci.org/ioquatix/geospatial)
+[![Code Climate](https://codeclimate.com/github/ioquatix/geospatial.svg)](https://codeclimate.com/github/ioquatix/geospatial)
 [![Coverage Status](https://coveralls.io/repos/ioquatix/geospatial/badge.svg)](https://coveralls.io/r/ioquatix/geospatial)
 
+## Motivation
+
+We had a need to query a database of places efficiently using SQLite. We did some investigation and found that SQLite (at least at the time) couldn't use composite indexes efficiently. Our testing revealed that MySQL also didn't really do well with large amounts of data. We had a table with 5Gb of data, and 15Gb of indexes. Crazy.
+
+After researching geospatial hashing algorithms, I found [this blog post](http://blog.notdot.net/2009/11/Damn-Cool-Algorithms-Spatial-indexing-with-Quadtrees-and-Hilbert-Curves) and decided to implement a geospatial hash using the Hilbert curve. This library exposes a fast indexing and querying mechanism based on Hilbert curves, for points on a map, which can be integrated into a database or other systems as required.
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'geospatial'
+	gem 'geospatial'
 
 And then execute:
 
-    $ bundle
+	$ bundle
 
 Or install it yourself as:
 
-    $ gem install geospatial
+	$ gem install geospatial
 
 ## Usage
 
-...
+The simplest way to use this library is to use the built in `Map`:
+
+	map = Geospatial::Map.new
+	map << Geospatial::Location.new(170.53, -43.89) # Lake Tekapo, New Zealand.
+	map << Geospatial::Location.new(170.45, -43.94) # Lake Alex, New Zealand.
+	map << Geospatial::Location.new(151.21, -33.85) # Sydney, Australia.
+
+	map.sort! # or assume an ordered database index.
+
+	new_zealand = Geospatial::Box.from_bounds(Vector[166.0, -48.0], Vector[180.0, -34.0])
+
+	points = subject.query(new_zealand)
+	expect(points).to include(lake_tekapo, lake_alex)
+	expect(points).to_not include(sydney)
+
+At a lower level you can use the method in the `Geospatial::Hilbert` module to `map`, `unmap` and `traverse` the Hilbert mapping.
+
+### Geotemporal Indexes
+
+The Hilbert curve is multi-dimensional and therefore can represent multi-dimensional data, e.g. latitude, longitude and time, in a single index. The curve expands uniformly in all dimensions, so you can't control the precision of the dimensions independently.
+
+Mathematically speaking, it's possible to compose curves together to form curves of different precision/properties. However, how these fit together generally is a bit more complex, especially in terms of exploring the curve via traversal.
 
 ## Contributing
 
@@ -36,7 +65,7 @@ Or install it yourself as:
 
 Released under the MIT license.
 
-Copyright, 2015, by [Samuel G. D. Williams](http://www.codeotaku.com/samuel-williams).
+Copyright, 2016, by [Samuel G. D. Williams](http://www.codeotaku.com/samuel-williams).
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/Rakefile

@@ -6,3 +6,14 @@ RSpec::Core::RakeTask.new(:spec) do |task|
 end
 
 task :default => :spec
+
+task :console do
+	require 'pry'
+	
+	$LOAD_PATH.unshift(File.expand_path('lib', __dir__))
+	
+	require 'geospatial'
+	require 'geospatial/hilbert'
+	
+	Pry.start
+end

data/geospatial.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
 	spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
 	spec.require_paths = ["lib"]
 
-	spec.add_development_dependency "rspec", "~> 3.1.0"
+	spec.add_development_dependency "rspec", "~> 3.4"
 
 	spec.add_development_dependency "bundler", "~> 1.6"
 	spec.add_development_dependency "rake"

data/lib/geospatial/box.rb

@@ -0,0 +1,126 @@
+# Copyright, 2015, by Samuel G. D. Williams. <http://www.codeotaku.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 'matrix'
+
+module Geospatial
+	class Box
+		class << self
+			def from_bounds(min, max)
+				self.new(min, max-min, max)
+			end
+			
+			alias [] from_bounds
+			
+			def enclosing_points(points)
+				return nil unless points.any?
+				
+				min = points.first.to_a
+				max = points.first.to_a
+				
+				points.each do |point|
+					point.each_with_index do |value, index|
+						if value < min[index]
+							min[index] = value
+						elsif value > max[index]
+							max[index] = value
+						end
+					end
+				end
+				
+				return self.from_bounds(Vector.elements(min), Vector.elements(max))
+			end
+		end
+		
+		def initialize(origin, size, max = nil)
+			@origin = origin
+			@size = size
+			@max = max
+		end
+		
+		def freeze
+			self.max
+			
+			super
+		end
+		
+		attr :origin
+		attr :size
+		
+		def to_s
+			"#{self.class}[#{min.inspect}, #{max.inspect}]"
+		end
+		
+		def min
+			@origin
+		end
+		
+		def max
+			@max ||= @origin + @size
+		end
+		
+		# This yields the four corners of the box.
+		def corners
+			return to_enum(:corners) unless block_given?
+			
+			yield(@origin)
+			
+			max = self.max
+			yield(Vector[max[0], @origin[1]])
+			yield(max)
+			yield(Vector[@origin[0], max[1]])
+		end
+		
+		# This yields the midpoints of the four sides of the box.
+		def midpoints
+			return to_enum(:midpoints) unless block_given?
+			
+			size = self.size
+			
+			yield(Vector[@origin[0] + size[0] / 2, @origin[1]])
+			yield(Vector[@origin[0] + size[0], @origin[1] + size[1] / 2])
+			yield(Vector[@origin[0] + size[0] / 2, @origin[1] + size[1]])
+			yield(Vector[@origin[0], @origin[1] + size[1] / 2])
+		end
+		
+		def include_point?(point)
+			2.times do |i|
+				return false if point[i] < min[i] or point[i] >= max[i]
+			end
+			
+			return true
+		end
+		
+		def include?(other)
+			include_point?(other.min) && include_point?(other.max)
+		end
+		
+		def intersect?(other)
+			2.times do |i|
+				# Separating axis theorm, if the minimum of the other is past the maximum of self, or the maximum of other is less than the minimum of self, an intersection cannot occur.
+				if other.min[i] > self.max[i] or other.max[i] < self.min[i]
+					return false
+				end
+			end
+			
+			return true
+		end
+	end
+end

data/lib/geospatial/circle.rb

@@ -0,0 +1,109 @@
+# Copyright, 2015, by Samuel G. D. Williams. <http://www.codeotaku.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 'matrix'
+
+module Geospatial
+	# A circle is a geometric primative where the center is a location and the radius is in meters.
+	class Circle
+		class << self
+			alias [] new
+		end
+		
+		# Center must be a vector, radius must be a numeric value.
+		def initialize(center, radius)
+			@center = center
+			@radius = radius
+		end
+		
+		attr :center
+		attr :radius
+		
+		def to_s
+			"#{self.class}[#{@center}, #{@radius}]"
+		end
+		
+		def distance_from(point)
+			Location.new(point[0], point[1]).distance_from(@center)
+		end
+		
+		def include_point?(point, radius = @radius)
+			distance_from(point) <= radius
+		end
+		
+		def include_box?(other)
+			# We must contain the for corners of the other box:
+			other.corners do |corner|
+				return false unless include_point?(corner)
+			end
+			
+			return true
+		end
+		
+		def include_circle?(other)
+			# We must be big enough to contain the other point:
+			@radius >= other.radius && include_point?(other.center.to_a, @radius - other.radius)
+		end
+		
+		def include?(other)
+			case other
+			when Box
+				include_box?(other)
+			when Circle
+				include_circle?(other)
+			end
+		end
+		
+		def intersect?(other)
+			case other
+			when Box
+				intersect_with_box?(other)
+			when Circle
+				intersect_with_circle?(other)
+			end
+		end
+		
+		def midpoints
+			@bounds ||= @center.bounding_box(@radius)
+			
+			yield([@bounds[:longitude].begin, @center.latitude])
+			yield([@bounds[:longitude].end, @center.latitude])
+			yield([@center.longitude, @bounds[:latitude].begin])
+			yield([@center.longitude, @bounds[:latitude].end])
+		end
+		
+		def intersect_with_box?(other)
+			# If we contain any of the four corners:
+			other.corners do |corner|
+				return true if include_point?(corner)
+			end
+			
+			midpoints do |midpoint|
+				return true if other.include_point?(midpoint)
+			end
+			
+			return false
+		end
+		
+		def intersect_with_circle?(other)
+			include_point?(other.center.to_a, @radius + other.radius)
+		end
+	end
+end

data/lib/geospatial/dimensions.rb

@@ -0,0 +1,130 @@
+# Copyright, 2016, by Samuel G. D. Williams. <http://www.codeotaku.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 'matrix'
+
+module Geospatial
+	# An integral dimension which maps a continuous space into an integral space. The scale is the maximum integral unit.
+	class Dimension
+		def initialize(origin, size, scale = 1.0)
+			@origin = origin
+			@size = size
+			@scale = scale
+		end
+		
+		def to_s
+			if @scale != 1.0
+				"(#{min}..#{max} * #{@scale})"
+			else
+				"(#{min}..#{max})"
+			end
+		end
+		
+		def * factor
+			self.class.new(@origin, @size, @scale * factor)
+		end
+		
+		attr :origin
+		attr :size
+		attr :scale
+		
+		def min
+			@origin
+		end
+		
+		def max
+			@origin + @size
+		end
+		
+		# Normalize the value into the range 0..1 and then multiply by scale.
+		def map(value)
+			((value - @origin).to_f / @size) * @scale
+		end
+		
+		def unmap(value)
+			@origin + (value / @scale) * @size
+		end
+	end
+	
+	class Dimensions
+		def initialize(dimensions)
+			@dimensions = dimensions
+		end
+		
+		attr :dimensions
+		
+		def to_s
+			"[#{@dimensions.join(', ')}]"
+		end
+		
+		def freeze
+			@dimensions.freeze
+			
+			super
+		end
+		
+		def count
+			return @dimensions.count
+		end
+		
+		def * factor
+			self.class.new(@dimensions.collect{|dimension| dimension * factor})
+		end
+		
+		def origin
+			@dimensions.collect(&:origin)
+		end
+		
+		def size
+			@dimensions.collect(&:size)
+		end
+		
+		def scale
+			@dimensions.colect(&:scale)
+		end
+		
+		def min
+			@dimensions.collect(&:min)
+		end
+		
+		def max
+			@dimensions.collect(&:max)
+		end
+		
+		def map(values)
+			@dimensions.zip(values).collect{|d,v| d.map(v)}
+		end
+		
+		def unmap(values)
+			@dimensions.zip(values).collect{|d,v| d.unmap(v)}
+		end
+		
+		LATITUDE = Dimension.new(-90.0, 180.0).freeze
+		LONGITUDE = Dimension.new(-180.0, 360.0).freeze
+		
+		def self.for_earth
+			@for_earth ||= self.new([LONGITUDE, LATITUDE]).freeze
+		end
+		
+		def self.from_ranges(*ranges)
+			self.new ranges.collect{|range| Dimension.new(range.min, range.max - range.min)}
+		end
+	end
+end

data/lib/geospatial/filter.rb

@@ -0,0 +1,82 @@
+# Copyright, 2016, by Samuel G. D. Williams. <http://www.codeotaku.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.
+
+module Geospatial
+	class Filter
+		class Range
+			def initialize(prefix, order)
+				@min = prefix
+				update_max(prefix, order)
+			end
+			
+			attr :min
+			attr :max
+			
+			def to_s
+				"#{min.to_s(2)}..#{max.to_s(2)}"
+			end
+			
+			# Returns the new max if expansion was possible, or nil otherwise.
+			def expand!(prefix, order)
+				if @max < prefix and prefix == @max+1
+					update_max(prefix, order)
+				end
+			end
+			
+			def include?(hash)
+				hash >= min and hash <= max
+			end
+			
+			private
+			
+			def update_max(prefix, order)
+				# We set the RHS of the prefix to 1s, which is the maximum:
+				@max = prefix | ((1 << (order*2)) - 1)
+			end
+		end
+		
+		def initialize
+			@ranges = []
+		end
+		
+		attr :ranges
+		
+		def add(prefix, order)
+			if last = @ranges.last
+				raise ArgumentError.new("Cannot add non-sequential prefix") unless prefix > last.max
+			end
+			
+			unless last = @ranges.last and last.expand!(prefix, order)
+				@ranges << Range.new(prefix, order)
+			end
+		end
+		
+		def apply(points)
+			# This is a poor implementation.
+			points.select{|point| @ranges.any?{|range| range.include?(point.hash)}}
+		end
+		
+		alias & apply
+		
+		def include?(point)
+			@ranges.any?{|range| range.include?(point.hash)}
+		end
+	end
+end

data/lib/geospatial/hilbert/curve.rb

@@ -0,0 +1,79 @@
+# Copyright, 2015, by Samuel G. D. Williams. <http://www.codeotaku.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_relative '../dimensions'
+require_relative '../index'
+
+module Geospatial
+	module Hilbert
+		class Curve
+			def initialize(dimensions, order = 30)
+				raise ArgumentError("Order #{order} must be positive integer!") unless order >= 1
+				
+				# Order is the number of levels of the curve, which is equivalent to the number of bits per dimension.
+				@order = order
+				@scale = 2**@order
+				
+				@dimensions = dimensions * @scale
+				@origin = dimensions.origin
+				@size = dimensions.size
+			end
+			
+			attr :order
+			attr :scale
+			attr :dimensions
+			
+			def origin
+				@dimensions.origin
+			end
+			
+			def size
+				@dimensions.size
+			end
+			
+			def to_s
+				"\#<#{self.class} order=#{@order} dimensions=#{@dimensions}>"
+			end
+			
+			# This is a helper entry point for traversing Hilbert space.
+			def traverse(&block)
+				if block_given?
+					self.class.traverse_recurse(@order, @rotation, 0, @origin, @size, &block)
+				else
+					self.class.to_enum(:traverse_recurse, @order, @rotation, 0, @origin, @size)
+				end
+			end
+			
+			def map(coordinates)
+				axes = @dimensions.map(coordinates).map(&:floor)
+				
+				index = OrdinalIndex.new(axes, @order)
+				
+				return index.to_hilbert.to_i
+			end
+			
+			def unmap(value)
+				index = HilbertIndex.from_integral(value, @dimensions.count, @order)
+				
+				return @dimensions.unmap(index.to_ordinal.axes)
+			end
+		end
+	end
+end