andre-geokit 1.2.0 → 1.2.1

data/Manifest.txt

@@ -1,17 +1,17 @@
-.loadpath
 .project
 Manifest.txt
 README.markdown
 Rakefile
 geokit.gemspec
-lib/geokit/geocoders.rb
 lib/geokit.rb
+lib/geokit/geocoders.rb
 lib/geokit/mappable.rb
 test/test_base_geocoder.rb
 test/test_bounds.rb
 test/test_ca_geocoder.rb
 test/test_geoloc.rb
 test/test_google_geocoder.rb
+test/test_google_reverse_geocoder.rb
 test/test_ipgeocoder.rb
 test/test_latlng.rb
 test/test_multi_geocoder.rb

data/README.markdown

@@ -1,12 +1,13 @@
 # Geokit gem
 
-[http://geokit.rubyforge.org](http://geokit.rubyforge.org)
+* Geokit Documentation at Rubyforge [http://geokit.rubyforge.org](http://geokit.rubyforge.org).
+* Repository at Github: [http://github.com/andre/geokit-gem/tree/master](http://github.com/andre/geokit-gem/tree/master).
 
 ## DESCRIPTION:
 
 The Geokit gem provides the following:
 
- * Distance calculations between two points on the earth. Calculate the distance in miles or KM, with all the trigonometry abstracted away by GeoKit.
+ * Distance calculations between two points on the earth. Calculate the distance in miles, kilometers, or nautical miles, with all the trigonometry abstracted away by GeoKit.
  * Geocoding from multiple providers. It currently supports Google, Yahoo, Geocoder.us, and Geocoder.ca geocoders, and it provides a uniform response structure from all of them. It also provides a fail-over mechanism, in case your input fails to geocode in one service.
  * Rectangular bounds calculations: is a point within a given rectangular bounds?
  * Heading and midpoint calculations
@@ -36,10 +37,12 @@ Combine this with gem with the [geokit-rails plugin](http://github.com/andre/geo
 
 FYI, that `.ll` method means "latitude longitude".
 
+See the RDOC more more ... there is also operations on rectangular bounds (e.g., determining if a point is within bounds, find the center, etc).
+
 ## INSTALL:
 
   * gem sources -a http://gems.github.com
-  * sudo gem install andre-geokit-gem
+  * sudo gem install andre-geokit
 
 ## Configuration
 

data/Rakefile

@@ -2,7 +2,7 @@
 
 require 'rubygems'
 require 'hoe'
-require './lib/geokit.rb'
+require './lib/geokit'
 
 Hoe.new('Geokit', Geokit::VERSION) do |p|
   # p.rubyforge_name = 'Geokitx' # if different than lowercase project name

data/lib/geokit.rb

@@ -25,6 +25,4 @@ require 'geokit/geocoders'
 require 'geokit/mappable'
 
 # make old-style module name "GeoKit" equivilent to new-style "Geokit"
-module GeoKit
-  include Geokit
-end
+GeoKit=Geokit

data/lib/geokit/geocoders.rb

@@ -95,6 +95,14 @@ module Geokit
         return res.success ? res : GeoLoc.new
       end  
       
+      # Main method which calls the do_reverse_geocode template method which subclasses
+      # are responsible for implementing.  Returns a populated GeoLoc or an
+      # empty one with a failed success code.
+      def self.reverse_geocode(latlng)
+        res = do_reverse_geocode(latlng)
+        return res.success ? res : GeoLoc.new        
+      end
+      
       # Call the geocoder service using the timeout if configured.
       def self.call_geocoder_service(url)
         timeout(Geokit::Geocoders::timeout) { return self.do_get(url) } if Geokit::Geocoders::timeout        
@@ -103,6 +111,13 @@ module Geokit
         return nil  
       end
 
+      # Not all geocoders can do reverse geocoding. So, unless the subclass explicitly overrides this method,
+      # a call to reverse_geocode will return an empty GeoLoc. If you happen to be using MultiGeocoder,
+      # this will cause it to failover to the next geocoder, which will hopefully be one which supports reverse geocoding.
+      def self.do_reverse_geocode(latlng)
+        return GeoLoc.new
+      end
+
       protected
 
       def self.logger() 
@@ -193,6 +208,16 @@ module Geokit
     class GoogleGeocoder < Geocoder
 
       private 
+      
+      # Template method which does the reverse-geocode lookup.
+      def self.do_reverse_geocode(latlng)
+        res = self.call_geocoder_service("http://maps.google.com/maps/geo?ll=#{Geokit::Inflector::url_escape(latlng)}&output=xml&key=#{Geokit::Geocoders::google}&oe=utf-8")
+  #        res = Net::HTTP.get_response(URI.parse("http://maps.google.com/maps/geo?ll=#{Geokit::Inflector::url_escape(address_str)}&output=xml&key=#{Geokit::Geocoders::google}&oe=utf-8"))
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+        xml = res.body
+        logger.debug "Google reverse-geocoding. LL: #{latlng}. Result: #{xml}"
+        return self.xml2GeoLoc(xml)        
+      end
 
       # Template method which does the geocode lookup.
       def self.do_geocode(address)
@@ -200,8 +225,12 @@ module Geokit
         res = self.call_geocoder_service("http://maps.google.com/maps/geo?q=#{Geokit::Inflector::url_escape(address_str)}&output=xml&key=#{Geokit::Geocoders::google}&oe=utf-8")
 #        res = Net::HTTP.get_response(URI.parse("http://maps.google.com/maps/geo?q=#{Geokit::Inflector::url_escape(address_str)}&output=xml&key=#{Geokit::Geocoders::google}&oe=utf-8"))
         return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
-        xml=res.body
+        xml = res.body
         logger.debug "Google geocoding. Address: #{address}. Result: #{xml}"
+        return self.xml2GeoLoc(xml)        
+      end
+      
+      def self.xml2GeoLoc(xml)
         doc=REXML::Document.new(xml)
 
         if doc.elements['//kml/Response/Status/code'].text == '200'
@@ -211,7 +240,7 @@ module Geokit
           #basics
           res.lat=coordinates[1]
           res.lng=coordinates[0]
-          res.country_code=doc.elements['//CountryNameCode'].text
+          res.country_code=doc.elements['//CountryNameCode'].text if doc.elements['//CountryNameCode']
           res.provider='google'
 
           #extended -- false if not not available

data/lib/geokit/mappable.rb

@@ -9,14 +9,17 @@ module Geokit
   # * Pythagorean Theory (flat Earth) - which assumes the world is flat and loses accuracy over long distances.
   # * Haversine (sphere) - which is fairly accurate, but at a performance cost.
   # 
-  # Distance units supported are :miles and :kms.
+  # Distance units supported are :miles, :kms, and :nms.
   module Mappable
     PI_DIV_RAD = 0.0174
     KMS_PER_MILE = 1.609
+    NMS_PER_MILE = 0.868976242
     EARTH_RADIUS_IN_MILES = 3963.19
     EARTH_RADIUS_IN_KMS = EARTH_RADIUS_IN_MILES * KMS_PER_MILE
+    EARTH_RADIUS_IN_NMS = EARTH_RADIUS_IN_MILES * NMS_PER_MILE
     MILES_PER_LATITUDE_DEGREE = 69.1
     KMS_PER_LATITUDE_DEGREE = MILES_PER_LATITUDE_DEGREE * KMS_PER_MILE
+    NMS_PER_LATITUDE_DEGREE = MILES_PER_LATITUDE_DEGREE * NMS_PER_MILE
     LATITUDE_DEGREES = EARTH_RADIUS_IN_MILES / MILES_PER_LATITUDE_DEGREE  
     
     # Mix below class methods into the includer.
@@ -27,7 +30,7 @@ module Geokit
     module ClassMethods #:nodoc:
       # Returns the distance between two points.  The from and to parameters are
       # required to have lat and lng attributes.  Valid options are:
-      # :units - valid values are :miles or :kms (Geokit::default_units is the default)
+      # :units - valid values are :miles, :kms, :nms (Geokit::default_units is the default)
       # :formula - valid values are :flat or :sphere (Geokit::default_formula is the default)
       def distance_between(from, to, options={})
         from=Geokit::LatLng.normalize(from)
@@ -36,11 +39,15 @@ module Geokit
         units = options[:units] || Geokit::default_units
         formula = options[:formula] || Geokit::default_formula
         case formula
-        when :sphere          
-          units_sphere_multiplier(units) * 
-              Math.acos( Math.sin(deg2rad(from.lat)) * Math.sin(deg2rad(to.lat)) + 
-              Math.cos(deg2rad(from.lat)) * Math.cos(deg2rad(to.lat)) * 
-              Math.cos(deg2rad(to.lng) - deg2rad(from.lng)))   
+        when :sphere
+          begin
+            units_sphere_multiplier(units) * 
+                Math.acos( Math.sin(deg2rad(from.lat)) * Math.sin(deg2rad(to.lat)) + 
+                Math.cos(deg2rad(from.lat)) * Math.cos(deg2rad(to.lat)) * 
+                Math.cos(deg2rad(to.lng) - deg2rad(from.lng)))
+          rescue Errno::EDOM
+            0.0
+          end
         when :flat
           Math.sqrt((units_per_latitude_degree(units)*(from.lat-to.lat))**2 + 
               (units_per_longitude_degree(from.lat, units)*(from.lng-to.lng))**2)
@@ -67,7 +74,11 @@ module Geokit
       # will be used instead of this method.
       def endpoint(start,heading, distance, options={})
         units = options[:units] || Geokit::default_units
-        radius = units == :miles ? EARTH_RADIUS_IN_MILES : EARTH_RADIUS_IN_KMS
+        radius = case units
+          when :kms: EARTH_RADIUS_IN_KMS
+          when :nms: EARTH_RADIUS_IN_NMS
+          else EARTH_RADIUS_IN_MILES
+        end
         start=Geokit::LatLng.normalize(start)        
         lat=deg2rad(start.lat)
         lng=deg2rad(start.lng)
@@ -86,7 +97,7 @@ module Geokit
       # Returns the midpoint, given two points. Returns a LatLng. 
       # Typically, the instance method will be used instead of this method.
       # Valid option:
-      #   :units - valid values are :miles or :kms (:miles is the default)
+      #   :units - valid values are :miles, :kms, or :nms (:miles is the default)
       def midpoint_between(from,to,options={})
         from=Geokit::LatLng.normalize(from)
 
@@ -120,18 +131,30 @@ module Geokit
 
       # Returns the multiplier used to obtain the correct distance units.
       def units_sphere_multiplier(units)
-        units == :miles ? EARTH_RADIUS_IN_MILES : EARTH_RADIUS_IN_KMS
+        case units
+          when :kms: EARTH_RADIUS_IN_KMS
+          when :nms: EARTH_RADIUS_IN_NMS
+          else EARTH_RADIUS_IN_MILES
+        end
       end
 
       # Returns the number of units per latitude degree.
       def units_per_latitude_degree(units)
-        units == :miles ? MILES_PER_LATITUDE_DEGREE : KMS_PER_LATITUDE_DEGREE
+        case units
+          when :kms: KMS_PER_LATITUDE_DEGREE
+          when :nms: NMS_PER_LATITUDE_DEGREE
+          else MILES_PER_LATITUDE_DEGREE
+        end
       end
     
       # Returns the number units per longitude degree.
       def units_per_longitude_degree(lat, units)
         miles_per_longitude_degree = (LATITUDE_DEGREES * Math.cos(lat * PI_DIV_RAD)).abs
-        units == :miles ? miles_per_longitude_degree : miles_per_longitude_degree * KMS_PER_MILE
+        case units
+          when :kms: miles_per_longitude_degree * KMS_PER_MILE
+          when :nms: miles_per_longitude_degree * NMS_PER_MILE
+          else miles_per_longitude_degree
+        end
       end  
     end
   
@@ -143,12 +166,12 @@ module Geokit
     def to_lat_lng
       return self if instance_of?(Geokit::LatLng) || instance_of?(Geokit::GeoLoc)
       return LatLng.new(send(self.class.lat_column_name),send(self.class.lng_column_name)) if self.class.respond_to?(:acts_as_mappable)
-      return nil
+      nil
     end
 
     # Returns the distance from another point.  The other point parameter is
     # required to have lat and lng attributes.  Valid options are:
-    # :units - valid values are :miles or :kms (:miles is the default)
+    # :units - valid values are :miles, :kms, :or :nms (:miles is the default)
     # :formula - valid values are :flat or :sphere (:sphere is the default)
     def distance_to(other, options={})
       self.class.distance_between(self, other, options)
@@ -169,14 +192,14 @@ module Geokit
  
     # Returns the endpoint, given a heading (in degrees) and distance.  
     # Valid option:
-    # :units - valid values are :miles or :kms (:miles is the default)
+    # :units - valid values are :miles, :kms, or :nms (:miles is the default)
     def endpoint(heading,distance,options={})
       self.class.endpoint(self,heading,distance,options)  
     end
 
     # Returns the midpoint, given another point on the map.  
     # Valid option:
-    # :units - valid values are :miles or :kms (:miles is the default)    
+    # :units - valid values are :miles, :kms, or :nms (:miles is the default)    
     def midpoint_to(other, options={})
       self.class.midpoint_between(self,other,options)
     end

data/test/test_bounds.rb

@@ -55,7 +55,7 @@ class BoundsTest < Test::Unit::TestCase #:nodoc: all
   
   def test_center
     assert_in_delta 32.939828,@bounds.center.lat,0.00005
-    assert_in_delta -96.9511763,@bounds.center.lng,0.00005
+    assert_in_delta(-96.9511763,@bounds.center.lng,0.00005)
   end
 
   def test_center_cross_meridian

data/test/test_latlng.rb

@@ -24,6 +24,11 @@ class LatLngTest < Test::Unit::TestCase #:nodoc: all
     assert_equal 0, @loc_a.distance_to(@loc_a, :units => :kms, :formula => :flat)
   end
   
+  def test_distance_between_same_with_nms_and_flat
+    assert_equal 0, Geokit::LatLng.distance_between(@loc_a, @loc_a, :units => :nms, :formula => :flat)
+    assert_equal 0, @loc_a.distance_to(@loc_a, :units => :nms, :formula => :flat)
+  end
+  
   def test_distance_between_same_with_miles_and_sphere
     assert_equal 0, Geokit::LatLng.distance_between(@loc_a, @loc_a, :units => :miles, :formula => :sphere)
     assert_equal 0, @loc_a.distance_to(@loc_a, :units => :miles, :formula => :sphere)
@@ -34,6 +39,11 @@ class LatLngTest < Test::Unit::TestCase #:nodoc: all
     assert_equal 0, @loc_a.distance_to(@loc_a, :units => :kms, :formula => :sphere)
   end
   
+  def test_distance_between_same_with_nms_and_sphere
+    assert_equal 0, Geokit::LatLng.distance_between(@loc_a, @loc_a, :units => :nms, :formula => :sphere)
+    assert_equal 0, @loc_a.distance_to(@loc_a, :units => :nms, :formula => :sphere)
+  end
+  
   def test_distance_between_diff_using_defaults
     assert_in_delta 3.97, Geokit::LatLng.distance_between(@loc_a, @loc_e), 0.01
     assert_in_delta 3.97, @loc_a.distance_to(@loc_e), 0.01
@@ -49,6 +59,11 @@ class LatLngTest < Test::Unit::TestCase #:nodoc: all
     assert_in_delta 6.39, @loc_a.distance_to(@loc_e, :units => :kms, :formula => :flat), 0.4
   end
   
+  def test_distance_between_diff_with_nms_and_flat
+    assert_in_delta 3.334, Geokit::LatLng.distance_between(@loc_a, @loc_e, :units => :nms, :formula => :flat), 0.4
+    assert_in_delta 3.334, @loc_a.distance_to(@loc_e, :units => :nms, :formula => :flat), 0.4
+  end
+  
   def test_distance_between_diff_with_miles_and_sphere
     assert_in_delta 3.97, Geokit::LatLng.distance_between(@loc_a, @loc_e, :units => :miles, :formula => :sphere), 0.01
     assert_in_delta 3.97, @loc_a.distance_to(@loc_e, :units => :miles, :formula => :sphere), 0.01
@@ -59,12 +74,18 @@ class LatLngTest < Test::Unit::TestCase #:nodoc: all
     assert_in_delta 6.39, @loc_a.distance_to(@loc_e, :units => :kms, :formula => :sphere), 0.01
   end
   
+  def test_distance_between_diff_with_nms_and_sphere
+    assert_in_delta 3.454, Geokit::LatLng.distance_between(@loc_a, @loc_e, :units => :nms, :formula => :sphere), 0.01
+    assert_in_delta 3.454, @loc_a.distance_to(@loc_e, :units => :nms, :formula => :sphere), 0.01
+  end
+  
   def test_manually_mixed_in
     assert_equal 0, Geokit::LatLng.distance_between(@point, @point)
     assert_equal 0, @point.distance_to(@point)
     assert_equal 0, @point.distance_to(@loc_a)
     assert_in_delta 3.97, @point.distance_to(@loc_e, :units => :miles, :formula => :flat), 0.2
     assert_in_delta 6.39, @point.distance_to(@loc_e, :units => :kms, :formula => :flat), 0.4
+    assert_in_delta 3.334, @point.distance_to(@loc_e, :units => :nms, :formula => :flat), 0.4
   end
   
   def test_heading_between

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: andre-geokit
 version: !ruby/object:Gem::Version 
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors: 
 - Andre Lewis and Bill Eisenhauer
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-11-30 00:00:00 -08:00
+date: 2009-02-01 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -52,7 +52,7 @@ homepage: http://geokit.rubyforge.org
 post_install_message: 
 rdoc_options: 
 - --main
-- README.txt
+- README.markdown
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement