davetroy-geohash 1.1.0

data/Manifest.txt

@@ -0,0 +1,7 @@
+History.txt
+README.txt
+Rakefile
+extconf.rb
+geohash_native.c
+lib/geohash.rb
+test/test_geohash.rb

data/README

@@ -0,0 +1,91 @@
+= geohash
+
+* http://rubyforge.org/projects/geohash
+
+== DESCRIPTION:
+
+GeoHash Gem for Ruby (c) 2008 David Troy
+dave@roundhousetech.com
+
+Geohash is a latitude/longitude encoding system invented by Gustavo Niemeyer when writing the
+web service at geohash.org, and put into the public domain. Geohashes offer properties like
+arbitrary precision, similar prefixes for nearby positions, and the possibility of gradually
+removing characters from the end of the code to reduce its size (and gradually lose precision).
+
+See these resources online:
+http://geohash.org
+http://en.wikipedia.org/wiki/Geohash
+http://openlocation.org/geohash/geohash-js (javascript implementation and demo)
+
+== FEATURES/PROBLEMS:
+
+* Encode to Geohash Format to an arbitrary level of precision
+* Decode from Geohash Format to an arbitrary level of precision
+* C implementation is over 10 times faster than native Ruby code (we checked)
+* No known problems
+
+== SYNOPSIS:
+
+GeoHash is very easy to use (and fast) because it's written in C with Ruby bindings.
+
+  require 'rubygems'
+  require 'geohash'
+
+  GeoHash.decode('f77')
+  => [63.98438, -73.82813]
+
+  GeoHash.encode(39.51, -76.24)
+  => "dr1bc0edrj"
+  
+  # Decode a geohash to a bounding box
+  decode_bbox('dqcw4')
+  => [39.0234375, -76.552734375], [39.0673828125, -76.5087890625]]
+  
+You can encode or decode to an arbitrary level of precision:
+
+# Encode latitude and longitude to a geohash with precision digits
+encode(lat, lon, precision=10)
+
+# Decode a geohash to a latitude and longitude with decimals digits
+decode(geohash, decimals=5)
+
+Have fun with this!  GeoHash is the new black.
+
+== REQUIREMENTS:
+
+* GCC and a Gnu-ish build environment (for native extensions)
+
+== INSTALLATION
+
+1) Enable gems from github, if you haven't already done so (rubygems >= 1.2):
+    > sudo gem sources -a http://gems.github.com
+
+2) Install gem
+    > sudo gem install davetroy-geohash
+
+3) Profit!
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 David Troy, Roundhouse Technologies LLC
+
+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/ext/extconf.rb

@@ -0,0 +1,3 @@
+require 'mkmf'
+dir_config("geohash_native")
+create_makefile("geohash_native")

data/ext/geohash_native.c

@@ -0,0 +1,212 @@
+// geohash-native.c
+// (c) 2008 David Troy
+// dave@roundhousetech.com
+// 
+// (The MIT License)
+// 
+// Copyright (c) 2008 David Troy, Roundhouse Technologies LLC
+// 
+// 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.
+
+#include "ruby.h"
+#include <ctype.h>
+
+static VALUE rb_cGeoHash;
+
+#define BASE32	"0123456789bcdefghjkmnpqrstuvwxyz"
+
+static void decode_geohash_bbox(char *geohash, double *lat, double *lon) {
+	int i, j, hashlen;
+	double lat_err, lon_err;
+	char c, cd, mask, is_even=1;
+	static char bits[] = {16,8,4,2,1};
+	
+	lat[0] = -90.0;  lat[1] = 90.0;
+	lon[0] = -180.0; lon[1] = 180.0;
+	lat_err = 90.0;  lon_err = 180.0;
+	hashlen = strlen(geohash);
+	
+	for (i=0; i<hashlen; i++) {
+		c = tolower(geohash[i]);
+		cd = strchr(BASE32, c)-BASE32;
+		for (j=0; j<5; j++) {
+			mask = bits[j];
+			if (is_even) {
+				lon_err /= 2;
+				lon[!(cd&mask)] = (lon[0] + lon[1])/2;
+			} else {
+				lat_err /= 2;
+				lat[!(cd&mask)] = (lat[0] + lat[1])/2;
+			}
+			is_even = !is_even;
+		}
+	}
+}
+
+static void decode_geohash(char *geohash, double *point) {
+	double lat[2], lon[2];
+
+	decode_geohash_bbox(geohash, lat, lon);
+
+	point[0] = (lat[0] + lat[1]) / 2;
+	point[1] = (lon[0] + lon[1]) / 2;
+}
+
+static void encode_geohash(double latitude, double longitude, int precision, char *geohash) {
+	int is_even=1, i=0;
+	double lat[2], lon[2], mid;
+	char bits[] = {16,8,4,2,1};
+	int bit=0, ch=0;
+
+	lat[0] = -90.0;  lat[1] = 90.0;
+	lon[0] = -180.0; lon[1] = 180.0;
+	
+	while (i < precision) {
+		if (is_even) {
+			mid = (lon[0] + lon[1]) / 2;
+			if (longitude > mid) {
+				ch |= bits[bit];
+				lon[0] = mid;
+			} else
+				lon[1] = mid;
+		} else {
+			mid = (lat[0] + lat[1]) / 2;
+			if (latitude > mid) {
+				ch |= bits[bit];
+				lat[0] = mid;
+			} else
+				lat[1] = mid;
+		}
+		
+		is_even = !is_even;
+		if (bit < 4)
+			bit++;
+		else {
+			geohash[i++] = BASE32[ch];
+			bit = 0;
+			ch = 0;
+		}
+	}
+	geohash[i] = 0;
+}
+
+static VALUE encode(VALUE self, VALUE lat, VALUE lon, VALUE precision)
+{
+	VALUE geohash;
+	char str[15];
+	int digits=10;
+	
+	digits = NUM2INT(precision);
+	
+	Check_Type(lat, T_FLOAT);
+	Check_Type(lon, T_FLOAT);
+	if (digits <3 || digits > 12)
+		digits = 12;
+	
+	encode_geohash(RFLOAT(lat)->value, RFLOAT(lon)->value, digits, str);
+
+	geohash = rb_str_new2(str);
+	return geohash;
+}
+
+static VALUE decode_bbox(VALUE self, VALUE str)
+{
+	VALUE ary, ret;
+	double lat[2], lon[2];
+	Check_Type(str, T_STRING);
+
+	decode_geohash_bbox(RSTRING(str)->ptr, lat, lon);
+
+	ret = rb_ary_new2(2); /* [[lat[0], lon[0]], [lat[1], lon[1]]] */
+
+	ary = rb_ary_new2(2); /* [lat[0], lon[0]] */
+	rb_ary_store(ary, 0, rb_float_new(lat[0]));
+	rb_ary_store(ary, 1, rb_float_new(lon[0]));
+	rb_ary_store(ret, 0, ary);
+
+	ary = rb_ary_new2(2); /* [lat[1], lon[1]] */
+	rb_ary_store(ary, 0, rb_float_new(lat[1]));
+	rb_ary_store(ary, 1, rb_float_new(lon[1]));
+	rb_ary_store(ret, 1, ary);
+
+	return ret;
+}
+
+static VALUE decode(VALUE self, VALUE str)
+{
+	VALUE ary;
+	double point[2];
+	Check_Type(str, T_STRING);
+	
+	decode_geohash(RSTRING(str)->ptr, point);
+	
+	ary = rb_ary_new2(2);
+	rb_ary_store(ary, 0, rb_float_new(point[0]));
+	rb_ary_store(ary, 1, rb_float_new(point[1]));
+	return ary;
+}
+
+// Given a particular geohash string, a direction, and a final length
+// Compute a neighbor using base32 lookups, recursively when necessary
+void get_neighbor(char *str, int dir, int hashlen)
+{
+	/* Right, Left, Top, Bottom */
+
+	static char *neighbors[] = { "bc01fg45238967deuvhjyznpkmstqrwx",
+														 	 "238967debc01fg45kmstqrwxuvhjyznp",
+														 	 "p0r21436x8zb9dcf5h7kjnmqesgutwvy",
+														   "14365h7k9dcfesgujnmqp0r2twvyx8zb" };
+												
+	static char *borders[] = { "bcfguvyz", "0145hjnp", "prxz", "028b" };
+
+	char last_chr, *border, *neighbor;
+	int index = ( 2 * (hashlen % 2) + dir) % 4;
+	neighbor = neighbors[index];
+	border = borders[index];
+	last_chr = str[hashlen-1];
+	if (strchr(border,last_chr))
+		get_neighbor(str, dir, hashlen-1);
+	str[hashlen-1] = BASE32[strchr(neighbor, last_chr)-neighbor];
+}
+
+// Acts as Ruby API wrapper to get_neighbor function, which is recursive and does nasty C things
+static VALUE calculate_adjacent(VALUE self, VALUE geohash, VALUE dir)
+{
+	char *str;
+	VALUE ret_val;
+	Check_Type(geohash, T_STRING);
+	Check_Type(dir, T_FIXNUM);
+	str = RSTRING(geohash)->ptr;
+	if (!strlen(str)) return Qnil;
+	ret_val = rb_str_new(str,strlen(str));
+	get_neighbor(RSTRING(ret_val)->ptr, NUM2INT(dir), strlen(str));
+	return ret_val;
+}
+
+void Init_geohash_native()
+{
+	rb_cGeoHash = rb_define_class("GeoHash", rb_cObject);
+	rb_define_singleton_method(rb_cGeoHash, "decode_bbox", decode_bbox, 1);
+	rb_define_singleton_method(rb_cGeoHash, "decode_base", decode, 1);
+	rb_define_singleton_method(rb_cGeoHash, "encode_base", encode, 3);
+	rb_define_singleton_method(rb_cGeoHash, "calculate_adjacent", calculate_adjacent, 2);
+}
+
+// end

data/lib/geohash.rb

@@ -0,0 +1,62 @@
+require 'geohash_native'
+
+class Float
+  def decimals(places)
+    n = (self * (10 ** places)).round
+    n.to_f/(10**places)
+  end
+end
+
+class GeoHash
+  
+  VERSION = '1.1.0'
+
+  NEIGHBOR_DIRECTIONS = [ [0, 1], [2, 3] ]
+  
+  # Encode latitude and longitude to a geohash with precision digits
+  def self.encode(lat, lon, precision=10)
+    encode_base(lat, lon, precision)
+  end
+
+  # Decode a geohash to a latitude and longitude with decimals digits
+  def self.decode(geohash, decimals=5)
+    lat, lon = decode_base(geohash)
+    [lat.decimals(decimals), lon.decimals(decimals)]
+  end
+  
+  # Create a new GeoHash object from a geohash or from a latlon
+  def initialize(*params)
+    if params.first.is_a?(Float)
+      @value = GeoHash.encode(*params)
+      @latitude, @longitude = params
+    else
+      @value = params.first
+      @latitude, @longitude = GeoHash.decode(@value)
+    end
+    @bounding_box = GeoHash.decode_bbox(@value)
+  end
+  
+  def to_s
+    @value
+  end
+  
+  def to_bbox
+    GeoHash.decode_bbox(@value)
+  end
+  
+  def neighbor(dir)
+    GeoHash.calculate_adjacent(@value, dir)
+  end
+  
+  def neighbors
+    immediate = NEIGHBOR_DIRECTIONS.flatten.map do |d|
+      neighbor(d)
+    end
+    diagonals = NEIGHBOR_DIRECTIONS.first.map do |y|
+      NEIGHBOR_DIRECTIONS.last.map do |x|
+        GeoHash.calculate_adjacent(GeoHash.calculate_adjacent(@value, x), y)
+      end
+    end.flatten
+    immediate + diagonals
+  end
+end

data/test/test_geohash.rb

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+$LOAD_PATH << "#{File.dirname(__FILE__)}/../ext"
+require "#{File.dirname(__FILE__)}/../lib/geohash"
+require 'test/unit'
+
+class GeoHashTest < Test::Unit::TestCase
+  
+  def test_decoding
+    assert_equal [39.02474, -76.51100], GeoHash.decode("dqcw4bnrs6s7")
+    assert_equal [37.791562, -122.398541], GeoHash.decode("9q8yyz8pg3bb", 6)
+    assert_equal [37.791562, -122.398541], GeoHash.decode("9Q8YYZ8PG3BB", 6)
+    assert_equal [42.60498046875, -5.60302734375], GeoHash.decode("ezs42", 11)
+    assert_equal [-25.382708, -49.265506], GeoHash.decode("6gkzwgjzn820",6)
+    assert_equal [-25.383, -49.266], GeoHash.decode("6gkzwgjz", 3)
+    assert_equal [37.8565, -122.2554], GeoHash.decode("9q9p658642g7", 4)
+  end
+
+  def test_encoding
+    assert_equal "dqcw4bnrs6s7", GeoHash.encode(39.0247389581054, -76.5110040642321, 12)
+    assert_equal "dqcw4bnrs6", GeoHash.encode(39.0247389581054, -76.5110040642321, 10)
+    assert_equal "6gkzmg1u", GeoHash.encode(-25.427, -49.315, 8)
+    assert_equal "ezs42", GeoHash.encode(42.60498046875, -5.60302734375, 5)
+  end
+
+  def check_decoding(gh)
+    exact = GeoHash.decode(gh, 20)
+    bbox = GeoHash.decode_bbox(gh)
+
+    # check that the bbox is centered on the decoded point
+    bbox_center = [(bbox[0][0] + bbox[1][0]) / 2, (bbox[0][1] + bbox[1][1]) / 2]
+    assert_equal exact, bbox_center
+
+    # check that the bounding box is the expected size
+    bits = gh.size * 5
+    lon_bits = (bits.to_f/2).ceil
+    lat_bits = (bits.to_f/2).floor
+    correct_size = [180.0/2**lat_bits, 360.0/2**lon_bits]
+    bbox_size = [bbox[1][0] - bbox[0][0], bbox[1][1] - bbox[0][1]]
+    assert_equal bbox_size, correct_size
+  end
+
+  def test_decoding_bbox
+    s = "dqcw4bnrs6s7"
+    (s.length).downto(0) do |l|
+      check_decoding(s[0..l])
+    end
+  end
+  
+  def test_specific_bbox
+    assert_equal [[39.0234375, -76.552734375], [39.0673828125, -76.5087890625]], GeoHash.decode_bbox('dqcw4')
+  end
+  
+  def test_neighbors
+    assert_equal ["dqcjr1", "dqcjq9", "dqcjqf", "dqcjqb", "dqcjr4", "dqcjr0", "dqcjqd", "dqcjq8"], GeoHash.new("dqcjqc").neighbors
+
+    assert_equal "dqcw5", GeoHash.calculate_adjacent("dqcw4", 0)  # right
+    assert_equal "dqcw1", GeoHash.calculate_adjacent("dqcw4", 1)  # left
+    
+    assert_equal "dqctc", GeoHash.calculate_adjacent("dqcw1", 3)  # bottom
+
+    assert_equal "dqcwh", GeoHash.calculate_adjacent("dqcw5", 0)  # right
+    assert_equal "dqcw4", GeoHash.calculate_adjacent("dqcw5", 1)  # left
+    assert_equal "dqcw7", GeoHash.calculate_adjacent("dqcw5", 2)  # top
+    assert_equal "dqctg", GeoHash.calculate_adjacent("dqcw5", 3)  # bottom
+    assert_equal 8, (["dqcw7", "dqctg", "dqcw4", "dqcwh", "dqcw6", "dqcwk", "dqctf", "dqctu"] & GeoHash.new("dqcw5").neighbors).size
+  end
+  
+  # require 'benchmark'
+  # def test_multiple
+  #   Benchmark.bmbm(30) do |bm|
+  #     bm.report("encoding") {30000.times { test_encoding }}
+  #     bm.report("decoding") {30000.times { test_decoding }}
+  #     #bm.report("neighbors") {30000.times { test_neighbors }}
+  #   end
+  # end
+end
+

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification 
+name: davetroy-geohash
+version: !ruby/object:Gem::Version 
+  version: 1.1.0
+platform: ruby
+authors: 
+- David Troy
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-11-27 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: Geohash provides support for manipulating GeoHash strings in Ruby. See http://geohash.org.
+email: dave@roundhousetech.com
+executables: []
+
+extensions: 
+- ext/extconf.rb
+extra_rdoc_files: 
+- Manifest.txt
+- README
+files: 
+- ext/extconf.rb
+- ext/geohash_native.c
+- lib/geohash.rb
+- Manifest.txt
+- README
+has_rdoc: true
+homepage: http://github.com/davetroy/geohash
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: GeoHash Library for Ruby, per http://geohash.org implementation.
+test_files: 
+- test/test_geohash.rb