geo_calc 0.5.1

data/lib/geo_calc/core_ext.rb

@@ -0,0 +1,228 @@
+module NumericCheckExt
+  def is_numeric? arg
+    arg.is_a? Numeric
+  end  
+
+  alias_method :is_num?, :is_numeric?
+  
+  def check_numeric! arg
+    raise ArgumentError, "Argument must be Numeric" if !is_numeric? arg
+  end  
+end
+
+module NumericGeoExt 
+  def to_dms format = :dms, dp = nil
+    Geo.to_dms self, format, dp
+  end
+
+  def to_lat_dms format = :dms, dp = nil
+    Geo.to_lat self, format, dp
+  end
+
+  def to_lon_dms format = :dms, dp = nil
+    Geo.to_lon self, format, dp
+  end
+  
+  # Converts numeric degrees to radians
+  def to_rad
+    self * Math::PI / 180
+  end
+  alias_method :to_radians, :to_rad
+  alias_method :as_rad,     :to_rad
+  alias_method :as_radians, :to_rad
+  alias_method :in_rad,     :to_rad
+  alias_method :in_radians, :to_rad
+
+
+  # Converts radians to numeric (signed) degrees
+  # latitude (north to south) from equator +90 up then -90 down (equator again) = 180 then 180 for south = 360 total 
+  # longitude (west to east)  east +180, west -180 = 360 total
+  def to_deg
+    self * 180 / Math::PI
+  end
+
+  alias_method :to_degrees, :to_deg
+  alias_method :as_deg,     :to_deg
+  alias_method :as_degrees, :to_deg
+  alias_method :in_deg,     :to_deg
+  alias_method :in_degrees, :to_deg
+
+   
+  # Formats the significant digits of a number, using only fixed-point notation (no exponential)
+  # 
+  # @param   {Number} precision: Number of significant digits to appear in the returned string
+  # @returns {String} A string representation of number which contains precision significant digits
+  def to_precision precision
+    self.round(precision).to_s
+
+    # numb = self.abs  # can't take log of -ve number...
+    # sign = self < 0 ? '-' : '';
+    # 
+    # # can't take log of zero
+    # if (numb == 0) 
+    #   n = '0.' 
+    #   while (precision -= 1) > 0
+    #     n += '0' 
+    #   end 
+    #   return n
+    # end
+    # 
+    # scale = (Math.log(numb) * Math.log10e).ceil # no of digits before decimal
+    # n = (numb * (precision - scale)**10).round.to_s
+    # if (scale > 0)   # add trailing zeros & insert decimal as required
+    #   l = scale - n.length
+    # 
+    #   while (l -= 1) > 0
+    #     n += '0' 
+    #   end
+    # 
+    #   if scale < n.length 
+    #     n = n.slice(0,scale) + '.' + n.slice(scale)
+    #   else # prefix decimal and leading zeros if required
+    #     while (scale += 1) < 0
+    #       n = '0' + n 
+    #     end
+    #     n = '0.' + n
+    #   end 
+    # end
+    # sign + n
+  end
+  alias_method :to_fixed, :to_precision
+
+  def normalize_deg shift = 0
+    (self + shift) % 360 
+  end
+  alias_method :normalize_degrees, :normalize_deg
+  
+end            
+
+module Math
+  def self.log10e
+    0.4342944819032518
+  end
+end
+
+module NumericLatLngExt
+  def to_lat 
+    normalize_deg
+  end
+  alias_method :to_lng, :to_lat
+    
+  def is_between? lower, upper
+    (lower..upper).cover? self
+  end
+end
+
+class Array
+  def geo_point
+    GeoPoint.new to_lat_lng
+  end  
+  
+  def to_lat_lng
+    raise "Array must contain at least two elements to be converted to latitude and longitude" if !(size >= 2)
+    [to_lat, to_lng]
+  end 
+
+  def to_lat
+    raise "Array must contain at least one element to return the latitude" if empty?
+    first.to_lat
+  end
+
+  def to_lng
+    raise "Array must contain at least two elements to return the longitude" if !self[1]
+    self[1].to_lng
+  end
+  
+  def trim
+    join.trim
+  end
+end
+
+class Symbol
+  def self.lng_symbols
+    [:lon, :long, :lng, :longitude]  
+  end
+
+  def self.lat_symbols
+    [:lat, :latitude]
+  end
+end
+
+class Hash
+  def to_lat_lng
+    [to_lat, to_lng]
+  end
+  
+  def to_lat
+    v = Symbol.lat_symbols.select {|key| self[key] }
+    return self[v.first].to_lat if !v.empty?
+    raise "Hash must contain either of the keys: [:lat, :latitude] to be converted to a latitude"
+  end
+
+  def to_lng
+    v = Symbol.lng_symbols.select {|key| self[key] }
+    return self[v.first].to_lng if !v.empty?
+    raise "Hash must contain either of the keys: [:lon, :long, :lng, :longitude] to be converted to a longitude"
+  end  
+  
+  def geo_point
+    GeoPoint.new to_lat_lng
+  end
+end  
+
+class String
+  def concat *args
+    args.inject(self) do |res, arg| 
+      x = arg.is_a?(String) ? arg : arg.to_s
+      res << x
+      res
+    end
+  end
+
+  def parse_dms
+    Geo.parse_dms self
+  end
+
+  def to_rad
+    parse_dms.to_rad
+  end
+
+  def trim
+    strip
+  end
+
+  def geo_clean
+    self.gsub(/^\(/, '').gsub(/\)$/, '').trim
+  end
+
+  def geo_point
+    GeoPoint.new to_lat_lng
+  end
+    
+  def to_lat_lng  
+    geo_clean.split(',').to_lat_lng
+  end
+  
+  def to_lat
+    raise "An empty String has no latitude" if empty?
+    geo_clean.parse_dms.to_f.to_lat
+  end
+
+  def to_lng
+    raise "An empty String has no latitude" if empty?
+    geo_clean.parse_dms.to_f.to_lng
+  end
+end
+
+
+
+class Fixnum
+  include NumericGeoExt 
+  include NumericLatLngExt  
+end
+
+class Float
+  include NumericGeoExt   
+  include NumericLatLngExt
+end
+  

data/lib/geo_calc/geo.rb

@@ -0,0 +1,170 @@
+require 'geo_calc/core_ext'
+
+ # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  
+ #  Geodesy representation conversion functions (c) Chris Veness 2002-2010
+ #   - www.movable-type.co.uk/scripts/latlong.html
+ #
+ # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  
+
+# Parses string representing degrees/minutes/seconds into numeric degrees
+# 
+# This is very flexible on formats, allowing signed decimal degrees, or deg-min-sec optionally
+# suffixed by compass direction (NSEW). A variety of separators are accepted (eg 3º 37' 09"W) 
+# or fixed-width format without separators (eg 0033709W). Seconds and minutes may be omitted. 
+# (Note minimal validation is done).
+# 
+# @param   {String|Number} dmsStr: Degrees or deg/min/sec in variety of formats
+# @returns {Number} Degrees as decimal number
+# @throws  ArgumentError
+
+module Geo
+  extend self  
+  extend ::NumericCheckExt
+  include ::NumericCheckExt
+  
+  def parse_dms dms_str  
+    # check for signed decimal degrees without NSEW, if so return it directly
+    return dms_str if is_numeric?(dms_str)
+  
+    # strip off any sign or compass dir'n & split out separate d/m/s
+    dms = dms_str.trim.gsub(/^-/,'').gsub(/[NSEW]$/i,'').split(/[^0-9.,]+/).map(&:trim).map(&:to_f)
+    return nil if dms.empty?
+  
+    # and convert to decimal degrees...
+    deg = case dms.length      
+    when 3 # interpret 3-part result as d/m/s
+       dms[0]/1 + dms[1]/60 + dms[2]/3600
+    when 2 # interpret 2-part result as d/m
+      dms[0]/1 + dms[1]/60        
+    when 1 # just d (possibly decimal) or non-separated dddmmss        
+      d = dms[0];
+      # check for fixed-width unseparated format eg 0033709W
+      d = "0#{d}" if (/[NS]/i.match(dms_str)) # - normalise N/S to 3-digit degrees
+      d = "#{d.slice(0,3)/1}#{deg.slice(3,5)/60}#{deg.slice(5)/3600}" if (/[0-9]{7}/.match(deg)) 
+      d
+    else
+      nil
+    end
+    return nil if !deg
+    deg = (deg * -1) if (/^-|[WS]$/i.match(dms_str.trim)) # take '-', west and south as -ve
+    deg.to_f
+  end
+
+  # Convert decimal degrees to deg/min/sec format
+  #  - degree, prime, double-prime symbols are added, but sign is discarded, though no compass
+  #    direction is added
+  # 
+  # 
+  # @param   {Number} deg: Degrees
+  # @param   {String} [format=dms]: Return value as 'd', 'dm', 'dms'
+  # @param   {Number} [dp=0|2|4]: No of decimal places to use - default 0 for dms, 2 for dm, 4 for d
+  # @returns {String} deg formatted as deg/min/secs according to specified format
+  # @throws  {TypeError} deg is an object, perhaps DOM object without .value?
+
+  def to_dms deg, format = :dms, dp = nil
+    deg = begin
+      deg.to_f
+    rescue
+      nil
+    end
+    return nil if !deg # give up here if we can't make a number from deg   
+  
+    # default values
+    format ||= :dms
+    dp = if dp.nil?
+      case format.to_sym
+      when :d 
+        4
+      when :dm 
+        2
+      else
+        0 # default
+      end
+    end
+    dp ||= 0
+  
+    deg = deg.abs # (unsigned result ready for appending compass dir'n)
+  
+    case format
+    when :d
+      d = deg.round(dp)       # round degrees
+      ds = "0#{d}" if (d <100)    # pad with leading zeros
+      ds = "0#{ds}" if (d <10) 
+      dms = ds.to_s.concat("\u00B0")  # add º symbol
+    when :dm            
+      min = (deg*60).round(dp)   # convert degrees to minutes & round
+      d = d.to_i
+      d = (min / 60).floor          # get component deg/min
+      m = (min % 60).round(dp)   # pad with trailing zeros
+      ds = d
+      ms = m
+      ds = "0#{d}" if (d<100)        # pad with leading zeros
+      ds = "0#{d}" if (d<10)
+      ms = "0#{m}" if (m<10)               
+      dms = ds.to_s.concat("\u00B0", ms, "\u2032") # add º, ' symbols
+    when :dms
+      sec = (deg * 3600).round   # convert degrees to seconds & round
+      d = (sec / 3600).floor          # get component deg/min/sec
+      m = ((sec / 60) % 60).floor
+      s = (sec % 60).round(dp)     # pad with trailing zeros
+      ds = d
+      ms = m
+      ss = s
+      ds = "0#{d}" if (d < 100)          # pad with leading zeros
+      ds = "0#{ds}" if (d < 10) 
+      ms = "0#{m}" if (m < 10) 
+      ss = "0#{s}" if (s < 10) 
+      dms = ds.to_s.concat("\u00B0", ms, "\u2032", ss, "\u2033")  # add º, ', " symbols
+    end
+    return dms
+  end
+
+
+  # Convert numeric degrees to deg/min/sec latitude (suffixed with N/S)
+  # 
+  # @param   {Number} deg: Degrees
+  # @param   {String} [format=dms]: Return value as 'd', 'dm', 'dms'
+  # @param   {Number} [dp=0|2|4]: No of decimal places to use - default 0 for dms, 2 for dm, 4 for d
+  # @returns {String} Deg/min/seconds
+
+  def to_lat deg, format = :dms, dp = 0
+    _lat = to_dms deg, format, dp
+    _lat == '' ? '' : _lat[1..-1] + (deg<0 ? 'S' : 'N')  # knock off initial '0' for lat!
+  end
+
+
+  # Convert numeric degrees to deg/min/sec longitude (suffixed with E/W)
+  # 
+  # @param   {Number} deg: Degrees
+  # @param   {String} [format=dms]: Return value as 'd', 'dm', 'dms'
+  # @param   {Number} [dp=0|2|4]: No of decimal places to use - default 0 for dms, 2 for dm, 4 for d
+  # @returns {String} Deg/min/seconds
+
+  def to_lon deg, format = :dms, dp = 0
+    deg = (360 - deg) * -1 if deg % 360 > 180
+    lon = to_dms deg, format, dp
+    lon == '' ? '' : lon + (deg<0 ? 'W' : 'E')
+  end
+
+
+  # Convert numeric degrees to deg/min/sec as a bearing (0º..360º)
+  # 
+  # @param   {Number} deg: Degrees
+  # @param   {String} [format=dms]: Return value as 'd', 'dm', 'dms'
+  # @param   {Number} [dp=0|2|4]: No of decimal places to use - default 0 for dms, 2 for dm, 4 for d
+  # @returns {String} Deg/min/seconds
+
+  def to_brng deg, format = :dms, dp = 0
+    deg = (deg.to_f + 360) % 360  # normalise -ve values to 180º..360º
+    brng =  to_dms deg, format, dp
+    brng.gsub /360/, '0'  # just in case rounding took us up to 360º!
+  end 
+  
+  protected
+
+  include NumericCheckExt
+end
+
+# class String
+#   include ::Geo
+# end

data/lib/geo_calc/geo_point.rb

@@ -0,0 +1,103 @@
+require 'geo_calc/calculations'
+
+ #  Sample usage:                                                                                 
+ #    p1 = GeoPoint.new(51.5136, -0.0983)                                                      
+ #    p2 = GeoPoint.new(51.4778, -0.0015)                                                      
+ #    dist = p1.distance_to(p2)          # in km                                             
+ #    brng = p1.bearing_to(p2)           # in degrees clockwise from north                   
+ #    ... etc                                                                                     
+ # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  
+ #                                                                                                
+ # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  
+ #  Note that minimal error checking is performed in this example code!                           
+ # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  
+
+class GeoPoint
+  include GeoCalc
+  # Creates a point on the earth's surface at the supplied latitude / longitude
+  # 
+  # Constructor
+  # - Numeric lat: latitude in numeric degrees
+  # - Numeric lon: longitude in numeric degrees
+  # - Numeric [rad=6371]: radius of earth if different value is required from standard 6,371km
+
+  attr_reader :lat, :lon, :unit, :radius
+  
+  (Symbol.lng_symbols - [:lon]).each do |sym|
+    class_eval %{
+      alias_method :#{sym}, :lon
+    }
+  end    
+
+  (Symbol.lat_symbols - [:lat]).each do |sym|
+    class_eval %{
+      alias_method :#{sym}, :lat
+    }
+  end    
+
+
+  def initialize *args
+    rad = args.delete(args.size) if is_numeric?(args.last) && args.last.is_between?(6350, 6380)
+    rad ||= 6371 # default
+    case args.size
+    when 1
+      create_from_one *args, rad
+    when 2
+      create_from_two *args, rad
+    else
+      raise "GeoPoint must be initialized with either one or to arguments defining the (latitude, longitude) coordinate on the map"
+    end
+  end
+
+  def [] key
+    case key
+    when Fixnum   
+      raise ArgumentError, "Index must be 0 or 1" if !(0..1).cover?(key)
+      to_arr[key] 
+    when String, Symbol
+      send(key) if respond_to? key
+    else
+      raise ArgumentError, "Key must be a Fixnum (index) or a method name"  
+    end    
+  end
+
+  alias_method :to_dms, :to_s
+
+  def to_lat_lng
+    [lat, lng]
+  end
+
+  def to_arr
+    a = to_lat_lng
+    reverse_arr? ? a.reverse : a
+  end
+
+  def reverse_arr?
+    @reverse_arr
+  end
+
+  def reverse_arr!
+    @reverse_arr = true
+  end
+
+  def normal_arr!
+    @reverse_arr = false
+  end
+  
+  protected
+
+  include NumericCheckExt
+  
+  def create_from_one points, rad = 6371
+    create_from_two *points.to_lat_lng, rad
+  end
+  
+  def create_from_two lat, lon, rad = 6371  
+    rad ||= 6371  # earth's mean radius in km
+    @lat    = lat.to_lat
+    @lon    = lon.to_lng
+    @radius = rad
+    @unit = :degrees
+  end  
+end
+