geo-calculator 0.0.1

data/lib/geo-calculator/configuration.rb

@@ -0,0 +1,124 @@
+require 'singleton'
+require 'geo-calculator/configuration_hash'
+
+module Geocoder
+
+  ##
+  # Configuration options should be set by passing a hash:
+  #
+  #   Geocoder.configure(
+  #     :timeout  => 5,
+  #     :lookup   => :yandex,
+  #     :api_key  => "2a9fsa983jaslfj982fjasd",
+  #     :units    => :km
+  #   )
+  #
+  def self.configure(options = nil, &block)
+    if !options.nil?
+      Configuration.instance.configure(options)
+    end
+  end
+
+  ##
+  # Read-only access to the singleton's config data.
+  #
+  def self.config
+    Configuration.instance.data
+  end
+
+  ##
+  # Read-only access to lookup-specific config data.
+  #
+  def self.config_for_lookup(lookup_name)
+    data = config.clone
+    data.reject!{ |key,value| !Configuration::OPTIONS.include?(key) }
+    if config.has_key?(lookup_name)
+      data.merge!(config[lookup_name])
+    end
+    data
+  end
+
+  class Configuration
+    include Singleton
+
+    OPTIONS = [
+      :timeout,
+      :lookup,
+      :ip_lookup,
+      :language,
+      :http_headers,
+      :use_https,
+      :http_proxy,
+      :https_proxy,
+      :api_key,
+      :cache,
+      :cache_prefix,
+      :always_raise,
+      :units,
+      :distances
+    ]
+
+    attr_accessor :data
+
+    def self.set_defaults
+      instance.set_defaults
+    end
+
+    OPTIONS.each do |o|
+      define_method o do
+        @data[o]
+      end
+      define_method "#{o}=" do |value|
+        @data[o] = value
+      end
+    end
+
+    def configure(options)
+      @data.rmerge!(options)
+    end
+
+    def initialize # :nodoc
+      @data = Geocoder::ConfigurationHash.new
+      set_defaults
+    end
+
+    def set_defaults
+
+      # geocoding options
+      @data[:timeout]      = 3           # geocoding service timeout (secs)
+      @data[:lookup]       = :google     # name of street address geocoding service (symbol)
+      @data[:ip_lookup]    = :freegeoip  # name of IP address geocoding service (symbol)
+      @data[:language]     = :en         # ISO-639 language code
+      @data[:http_headers] = {}          # HTTP headers for lookup
+      @data[:use_https]    = false       # use HTTPS for lookup requests? (if supported)
+      @data[:http_proxy]   = nil         # HTTP proxy server (user:pass@host:port)
+      @data[:https_proxy]  = nil         # HTTPS proxy server (user:pass@host:port)
+      @data[:api_key]      = nil         # API key for geocoding service
+      @data[:cache]        = nil         # cache object (must respond to #[], #[]=, and #keys)
+      @data[:cache_prefix] = "geocoder:" # prefix (string) to use for all cache keys
+
+      # exceptions that should not be rescued by default
+      # (if you want to implement custom error handling);
+      # supports SocketError and TimeoutError
+      @data[:always_raise] = []
+
+      # calculation options
+      @data[:units]     = :mi      # :mi or :km
+      @data[:distances] = :linear  # :linear or :spherical
+    end
+
+    instance_eval(OPTIONS.map do |option|
+      o = option.to_s
+      <<-EOS
+      def #{o}
+        instance.data[:#{o}]
+      end
+
+      def #{o}=(value)
+        instance.data[:#{o}] = value
+      end
+      EOS
+    end.join("\n\n"))
+
+  end
+end

data/lib/geo-calculator/configuration_hash.rb

@@ -0,0 +1,11 @@
+require 'geo-calculator/hash_recursive_merge'
+
+module Geocoder
+  class ConfigurationHash < Hash
+    include HashRecursiveMerge
+
+    def method_missing(meth, *args, &block)
+      has_key?(meth) ? self[meth] : super
+    end
+  end
+end

data/lib/geo-calculator/hash_recursive_merge.rb

@@ -0,0 +1,74 @@
+# 
+# = Hash Recursive Merge
+# 
+# Merges a Ruby Hash recursively, Also known as deep merge.
+# Recursive version of Hash#merge and Hash#merge!.
+# 
+# Category::    Ruby
+# Package::     Hash
+# Author::      Simone Carletti <weppos@weppos.net>
+# Copyright::   2007-2008 The Authors
+# License::     MIT License
+# Link::        http://www.simonecarletti.com/
+# Source::      http://gist.github.com/gists/6391/
+#
+module HashRecursiveMerge
+
+  #
+  # Recursive version of Hash#merge!
+  # 
+  # Adds the contents of +other_hash+ to +hsh+, 
+  # merging entries in +hsh+ with duplicate keys with those from +other_hash+.
+  # 
+  # Compared with Hash#merge!, this method supports nested hashes.
+  # When both +hsh+ and +other_hash+ contains an entry with the same key,
+  # it merges and returns the values from both arrays.
+  # 
+  #    h1 = {"a" => 100, "b" => 200, "c" => {"c1" => 12, "c2" => 14}}
+  #    h2 = {"b" => 254, "c" => {"c1" => 16, "c3" => 94}}
+  #    h1.rmerge!(h2)   #=> {"a" => 100, "b" => 254, "c" => {"c1" => 16, "c2" => 14, "c3" => 94}}
+  #    
+  # Simply using Hash#merge! would return
+  # 
+  #    h1.merge!(h2)    #=> {"a" => 100, "b" = >254, "c" => {"c1" => 16, "c3" => 94}}
+  # 
+  def rmerge!(other_hash)
+    merge!(other_hash) do |key, oldval, newval|
+      oldval.class == self.class ? oldval.rmerge!(newval) : newval
+    end
+  end
+
+  #
+  # Recursive version of Hash#merge
+  # 
+  # Compared with Hash#merge!, this method supports nested hashes.
+  # When both +hsh+ and +other_hash+ contains an entry with the same key,
+  # it merges and returns the values from both arrays.
+  # 
+  # Compared with Hash#merge, this method provides a different approch
+  # for merging nasted hashes.
+  # If the value of a given key is an Hash and both +other_hash+ abd +hsh
+  # includes the same key, the value is merged instead replaced with
+  # +other_hash+ value.
+  # 
+  #    h1 = {"a" => 100, "b" => 200, "c" => {"c1" => 12, "c2" => 14}}
+  #    h2 = {"b" => 254, "c" => {"c1" => 16, "c3" => 94}}
+  #    h1.rmerge(h2)    #=> {"a" => 100, "b" => 254, "c" => {"c1" => 16, "c2" => 14, "c3" => 94}}
+  #    
+  # Simply using Hash#merge would return
+  # 
+  #    h1.merge(h2)     #=> {"a" => 100, "b" = >254, "c" => {"c1" => 16, "c3" => 94}}
+  # 
+  def rmerge(other_hash)
+    r = {}
+    merge(other_hash) do |key, oldval, newval|
+      r[key] = oldval.class == self.class ? oldval.rmerge(newval) : newval
+    end
+  end
+
+end
+
+
+class Hash
+  include HashRecursiveMerge
+end

data/lib/geo-calculator/sql.rb

@@ -0,0 +1,107 @@
+module Geocoder
+  module Sql
+    extend self
+
+    ##
+    # Distance calculation for use with a database that supports POWER(),
+    # SQRT(), PI(), and trigonometric functions SIN(), COS(), ASIN(),
+    # ATAN2(), DEGREES(), and RADIANS().
+    #
+    # Based on the excellent tutorial at:
+    # http://www.scribd.com/doc/2569355/Geo-Distance-Search-with-MySQL
+    #
+    def full_distance(latitude, longitude, lat_attr, lon_attr, options = {})
+      units = options[:units] || Geocoder.config.units
+      earth = Geocoder::Calculations.earth_radius(units)
+
+      "#{earth} * 2 * ASIN(SQRT(" +
+        "POWER(SIN((#{latitude.to_f} - #{lat_attr}) * PI() / 180 / 2), 2) + " +
+        "COS(#{latitude.to_f} * PI() / 180) * COS(#{lat_attr} * PI() / 180) * " +
+        "POWER(SIN((#{longitude.to_f} - #{lon_attr}) * PI() / 180 / 2), 2)" +
+      "))"
+    end
+
+    ##
+    # Distance calculation for use with a database without trigonometric
+    # functions, like SQLite. Approach is to find objects within a square
+    # rather than a circle, so results are very approximate (will include
+    # objects outside the given radius).
+    #
+    # Distance and bearing calculations are *extremely inaccurate*. To be
+    # clear: this only exists to provide interface consistency. Results
+    # are not intended for use in production!
+    #
+    def approx_distance(latitude, longitude, lat_attr, lon_attr, options = {})
+      units = options[:units] || Geocoder.config.units
+      dx = Geocoder::Calculations.longitude_degree_distance(30, units)
+      dy = Geocoder::Calculations.latitude_degree_distance(units)
+
+      # sin of 45 degrees = average x or y component of vector
+      factor = Math.sin(Math::PI / 4)
+
+      "(#{dy} * ABS(#{lat_attr} - #{latitude.to_f}) * #{factor}) + " +
+        "(#{dx} * ABS(#{lon_attr} - #{longitude.to_f}) * #{factor})"
+    end
+
+    def within_bounding_box(sw_lat, sw_lng, ne_lat, ne_lng, lat_attr, lon_attr)
+      spans = "#{lat_attr} BETWEEN #{sw_lat} AND #{ne_lat} AND "
+      # handle box that spans 180 longitude
+      if sw_lng.to_f > ne_lng.to_f
+        spans + "#{lon_attr} BETWEEN #{sw_lng} AND 180 OR " +
+        "#{lon_attr} BETWEEN -180 AND #{ne_lng}"
+      else
+        spans + "#{lon_attr} BETWEEN #{sw_lng} AND #{ne_lng}"
+      end
+    end
+
+    ##
+    # Fairly accurate bearing calculation. Takes a latitude, longitude,
+    # and an options hash which must include a :bearing value
+    # (:linear or :spherical).
+    #
+    # Based on:
+    # http://www.beginningspatial.com/calculating_bearing_one_point_another
+    #
+    def full_bearing(latitude, longitude, lat_attr, lon_attr, options = {})
+      degrees_per_radian = Geocoder::Calculations::DEGREES_PER_RADIAN
+      case options[:bearing] || Geocoder.config.distances
+      when :linear
+        "MOD(CAST(" +
+          "(ATAN2( " +
+            "((#{lon_attr} - #{longitude.to_f}) / #{degrees_per_radian}), " +
+            "((#{lat_attr} - #{latitude.to_f}) / #{degrees_per_radian})" +
+          ") * #{degrees_per_radian}) + 360 " +
+        "AS decimal), 360)"
+      when :spherical
+        "MOD(CAST(" +
+          "(ATAN2( " +
+            "SIN( (#{lon_attr} - #{longitude.to_f}) / #{degrees_per_radian} ) * " +
+            "COS( (#{lat_attr}) / #{degrees_per_radian} ), (" +
+              "COS( (#{latitude.to_f}) / #{degrees_per_radian} ) * SIN( (#{lat_attr}) / #{degrees_per_radian})" +
+            ") - (" +
+              "SIN( (#{latitude.to_f}) / #{degrees_per_radian}) * COS((#{lat_attr}) / #{degrees_per_radian}) * " +
+              "COS( (#{lon_attr} - #{longitude.to_f}) / #{degrees_per_radian})" +
+            ")" +
+          ") * #{degrees_per_radian}) + 360 " +
+        "AS decimal), 360)"
+      end
+    end
+
+    ##
+    # Totally lame bearing calculation. Basically useless except that it
+    # returns *something* in databases without trig functions.
+    #
+    def approx_bearing(latitude, longitude, lat_attr, lon_attr, options = {})
+      "CASE " +
+        "WHEN (#{lat_attr} >= #{latitude.to_f} AND " +
+          "#{lon_attr} >= #{longitude.to_f}) THEN  45.0 " +
+        "WHEN (#{lat_attr} <  #{latitude.to_f} AND " +
+          "#{lon_attr} >= #{longitude.to_f}) THEN 135.0 " +
+        "WHEN (#{lat_attr} <  #{latitude.to_f} AND " +
+          "#{lon_attr} <  #{longitude.to_f}) THEN 225.0 " +
+        "WHEN (#{lat_attr} >= #{latitude.to_f} AND " +
+          "#{lon_attr} <  #{longitude.to_f}) THEN 315.0 " +
+      "END"
+    end
+  end
+end

data/lib/geo-calculator/store/active_record.rb

@@ -0,0 +1,290 @@
+# -*- coding: utf-8 -*-
+require 'geo-calculator/sql'
+require 'geo-calculator/store/base'
+require 'byebug'
+
+##
+# Add geocoding functionality to any ActiveRecord object.
+#
+module Geocoder::Store
+  module ActiveRecord
+    include Base
+
+    ##
+    # Implementation of 'included' hook method.
+    #
+    def self.included(base)
+      base.extend ClassMethods
+      base.class_eval do
+
+        # scope: geocoded objects
+        scope :geocoded, lambda {
+          where("#{table_name}.#{geocoder_options[:latitude]} IS NOT NULL " +
+            "AND #{table_name}.#{geocoder_options[:longitude]} IS NOT NULL")
+        }
+
+        # scope: not-geocoded objects
+        scope :not_geocoded, lambda {
+          where("#{table_name}.#{geocoder_options[:latitude]} IS NULL " +
+            "OR #{table_name}.#{geocoder_options[:longitude]} IS NULL")
+        }
+
+        ##
+        # Find all objects within a radius of the given location.
+        # Location may be either a string to geocode or an array of
+        # coordinates (<tt>[lat,lon]</tt>). Also takes an options hash
+        # (see Geocoder::Store::ActiveRecord::ClassMethods.near_scope_options
+        # for details).
+        #
+        scope :near, lambda{ |location, *args|
+          latitude, longitude = Geocoder::Calculations.extract_coordinates(location)
+          if Geocoder::Calculations.coordinates_present?(latitude, longitude)
+            options = near_scope_options(latitude, longitude, *args)
+            select(options[:select]).where(options[:conditions]).
+              order(options[:order])
+          else
+            # If no lat/lon given we don't want any results, but we still
+            # need distance and bearing columns so you can add, for example:
+            # .order("distance")
+            select(select_clause(nil, null_value, null_value)).where(false_condition)
+          end
+        }
+
+        ##
+        # Find all objects within the area of a given bounding box.
+        # Bounds must be an array of locations specifying the southwest
+        # corner followed by the northeast corner of the box
+        # (<tt>[[sw_lat, sw_lon], [ne_lat, ne_lon]]</tt>).
+        #
+        scope :within_bounding_box, lambda{ |bounds|
+          sw_lat, sw_lng, ne_lat, ne_lng = bounds.flatten if bounds
+          if sw_lat && sw_lng && ne_lat && ne_lng
+            where(Geocoder::Sql.within_bounding_box(
+              sw_lat, sw_lng, ne_lat, ne_lng,
+              full_column_name(geocoder_options[:latitude]),
+              full_column_name(geocoder_options[:longitude])
+            ))
+          else
+            select(select_clause(nil, null_value, null_value)).where(false_condition)
+          end
+        }
+      end
+    end
+
+    ##
+    # Methods which will be class methods of the including class.
+    #
+    module ClassMethods
+
+      def distance_from_sql(location, *args)
+        latitude, longitude = Geocoder::Calculations.extract_coordinates(location)
+        if Geocoder::Calculations.coordinates_present?(latitude, longitude)
+          distance_sql(latitude, longitude, *args)
+        end
+      end
+
+      private # ----------------------------------------------------------------
+
+      ##
+      # Get options hash suitable for passing to ActiveRecord.find to get
+      # records within a radius (in kilometers) of the given point.
+      # Options hash may include:
+      #
+      # * +:units+   - <tt>:mi</tt> or <tt>:km</tt>; to be used.
+      #   for interpreting radius as well as the +distance+ attribute which
+      #   is added to each found nearby object.
+      #   Use Geocoder.configure[:units] to configure default units.
+      # * +:bearing+ - <tt>:linear</tt> or <tt>:spherical</tt>.
+      #   the method to be used for calculating the bearing (direction)
+      #   between the given point and each found nearby point;
+      #   set to false for no bearing calculation. Use
+      #   Geocoder.configure[:distances] to configure default calculation method.
+      # * +:select+          - string with the SELECT SQL fragment (e.g. “id, name”)
+      # * +:select_distance+ - whether to include the distance alias in the
+      #                        SELECT SQL fragment (e.g. <formula> AS distance)
+      # * +:select_bearing+  - like +:select_distance+ but for bearing.
+      # * +:order+           - column(s) for ORDER BY SQL clause; default is distance;
+      #                        set to false or nil to omit the ORDER BY clause
+      # * +:exclude+         - an object to exclude (used by the +nearbys+ method)
+      # * +:distance_column+ - used to set the column name of the calculated distance.
+      # * +:bearing_column+  - used to set the column name of the calculated bearing.
+      # * +:min_radius+      - the value to use as the minimum radius.
+      #                        ignored if database is sqlite.
+      #                        default is 0.0
+      #
+      def near_scope_options(latitude, longitude, radius = 20, options = {})
+        if options[:units]
+          options[:units] = options[:units].to_sym
+        end
+        latitude_attribute = options[:latitude] || geocoder_options[:latitude]
+        longitude_attribute = options[:longitude] || geocoder_options[:longitude]
+        options[:units] ||= (geocoder_options[:units] || Geocoder.config.units)
+        select_distance = options.fetch(:select_distance)  { true }
+        options[:order] = "" if !select_distance && !options.include?(:order)
+        select_bearing = options.fetch(:select_bearing) { true }
+        bearing = bearing_sql(latitude, longitude, options)
+        distance = distance_sql(latitude, longitude, options)
+        distance_column = options.fetch(:distance_column) { 'distance' }
+        bearing_column = options.fetch(:bearing_column)  { 'bearing' }
+
+        b = Geocoder::Calculations.bounding_box([latitude, longitude], radius, options)
+        args = b + [
+          full_column_name(latitude_attribute),
+          full_column_name(longitude_attribute)
+        ]
+        bounding_box_conditions = Geocoder::Sql.within_bounding_box(*args)
+
+        if using_sqlite?
+          conditions = bounding_box_conditions
+        else
+          min_radius = options.fetch(:min_radius, 0).to_f
+          conditions = [bounding_box_conditions + " AND (#{distance}) BETWEEN ? AND ?", min_radius, radius]
+        end
+        {
+          :select => select_clause(options[:select],
+                                   select_distance ? distance : nil,
+                                   select_bearing ? bearing : nil,
+                                   distance_column,
+                                   bearing_column),
+          :conditions => add_exclude_condition(conditions, options[:exclude]),
+          :order => options.include?(:order) ? options[:order] : "#{distance_column} ASC"
+        }
+      end
+
+      ##
+      # SQL for calculating distance based on the current database's
+      # capabilities (trig functions?).
+      #
+      def distance_sql(latitude, longitude, options = {})
+        method_prefix = using_sqlite? ? "approx" : "full"
+        Geocoder::Sql.send(
+          method_prefix + "_distance",
+          latitude, longitude,
+          full_column_name(options[:latitude] || geocoder_options[:latitude]),
+          full_column_name(options[:longitude]|| geocoder_options[:longitude]),
+          options
+        )
+      end
+
+      ##
+      # SQL for calculating bearing based on the current database's
+      # capabilities (trig functions?).
+      #
+      def bearing_sql(latitude, longitude, options = {})
+        if !options.include?(:bearing)
+          options[:bearing] = Geocoder.config.distances
+        end
+        if options[:bearing]
+          method_prefix = using_sqlite? ? "approx" : "full"
+          Geocoder::Sql.send(
+            method_prefix + "_bearing",
+            latitude, longitude,
+            full_column_name(options[:latitude] || geocoder_options[:latitude]),
+            full_column_name(options[:longitude]|| geocoder_options[:longitude]),
+            options
+          )
+        end
+      end
+
+      ##
+      # Generate the SELECT clause.
+      #
+      def select_clause(columns, distance = nil, bearing = nil, distance_column = 'distance', bearing_column = 'bearing')
+        if columns == :id_only
+          return full_column_name(primary_key)
+        elsif columns == :geo_only
+          clause = ""
+        else
+          clause = (columns || full_column_name("*"))
+        end
+        if distance
+          clause += ", " unless clause.empty?
+          clause += "#{distance} AS #{distance_column}"
+        end
+        if bearing
+          clause += ", " unless clause.empty?
+          clause += "#{bearing} AS #{bearing_column}"
+        end
+        clause
+      end
+
+      ##
+      # Adds a condition to exclude a given object by ID.
+      # Expects conditions as an array or string. Returns array.
+      #
+      def add_exclude_condition(conditions, exclude)
+        conditions = [conditions] if conditions.is_a?(String)
+        if exclude
+          conditions[0] << " AND #{full_column_name(primary_key)} != ?"
+          conditions << exclude.id
+        end
+        conditions
+      end
+
+      def using_sqlite?
+        connection.adapter_name.match(/sqlite/i)
+      end
+
+      def using_postgres?
+        connection.adapter_name.match(/postgres/i)
+      end
+
+      ##
+      # Use OID type when running in PosgreSQL
+      #
+      def null_value
+        using_postgres? ? 'NULL::text' : 'NULL'
+      end
+
+      ##
+      # Value which can be passed to where() to produce no results.
+      #
+      def false_condition
+        using_sqlite? ? 0 : "false"
+      end
+
+      ##
+      # Prepend table name if column name doesn't already contain one.
+      #
+      def full_column_name(column)
+        column = column.to_s
+        column.include?(".") ? column : [table_name, column].join(".")
+      end
+    end
+
+    ##
+    # Look up coordinates and assign to +latitude+ and +longitude+ attributes
+    # (or other as specified in +geocoded_by+). Returns coordinates (array).
+    #
+    def geocode
+      do_lookup(false) do |o,rs|
+        if r = rs.first
+          unless r.latitude.nil? or r.longitude.nil?
+            o.__send__  "#{self.class.geocoder_options[:latitude]}=",  r.latitude
+            o.__send__  "#{self.class.geocoder_options[:longitude]}=", r.longitude
+          end
+          r.coordinates
+        end
+      end
+    end
+
+    alias_method :fetch_coordinates, :geocode
+
+    ##
+    # Look up address and assign to +address+ attribute (or other as specified
+    # in +reverse_geocoded_by+). Returns address (string).
+    #
+    def reverse_geocode
+      do_lookup(true) do |o,rs|
+        if r = rs.first
+          unless r.address.nil?
+            o.__send__ "#{self.class.geocoder_options[:fetched_address]}=", r.address
+          end
+          r.address
+        end
+      end
+    end
+
+    alias_method :fetch_address, :reverse_geocode
+  end
+end