geo_calc 0.6.1 → 0.7.1

data/Gemfile

@@ -1,5 +1,8 @@
 source "http://rubygems.org"
 
+gem "require_all",    "~> 1.2.0"
+gem "sugar-high",     "~> 0.4.5.2"
+
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development do

data/README.textile

@@ -2,6 +2,18 @@ h1. Geo calculations
 
 Geo Calculation library. Useful functions to add to your geo arsenal, fx when designing your own Geo library. 
 
+h2. Status update (June 10, 2011)
+
+- Major refactoring splitting into more logical file/modular structure
+- Use autoload
+- Extract GeoUnits
+- Extract Dms with converter
+- GeoPoint can now have set :coords_mode which affects how Ruby Core objects such as String and Array are parsed into :lng and :lat. 
+
+TODO:
+- The GeoPoint class should be extracted into separate gem, then this geo_calc gem should only have the more generic geo functionality as modules to be included
+where needed in other gems!
+
 h2. Install
 
 @require 'geo_calc'@

data/VERSION

@@ -1 +1 @@
-0.6.1
+0.7.1

data/geo_calc.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{geo_calc}
-  s.version = "0.6.1"
+  s.version = "0.7.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = [%q{Kristian Mandrup}]
-  s.date = %q{2011-05-31}
+  s.date = %q{2011-06-11}
   s.description = %q{Geo calculations in ruby and javascript}
   s.email = %q{kmandrup@gmail.com}
   s.extra_rdoc_files = [
@@ -34,37 +34,58 @@ Gem::Specification.new do |s|
     "lib/geo_calc/calc/intersection.rb",
     "lib/geo_calc/calc/midpoint.rb",
     "lib/geo_calc/calc/rhumb.rb",
-    "lib/geo_calc/core_ext.rb",
-    "lib/geo_calc/geo.rb",
+    "lib/geo_calc/dms.rb",
+    "lib/geo_calc/dms/converter.rb",
+    "lib/geo_calc/extensions.rb",
+    "lib/geo_calc/extensions/array.rb",
+    "lib/geo_calc/extensions/hash.rb",
+    "lib/geo_calc/extensions/math.rb",
+    "lib/geo_calc/extensions/numeric.rb",
+    "lib/geo_calc/extensions/string.rb",
+    "lib/geo_calc/extensions/symbol.rb",
     "lib/geo_calc/geo_point.rb",
+    "lib/geo_calc/geo_point/class_methods.rb",
+    "lib/geo_calc/geo_point/core_extension.rb",
+    "lib/geo_calc/geo_point/shared.rb",
     "lib/geo_calc/pretty_print.rb",
+    "lib/geo_units.rb",
+    "lib/geo_units/converter.rb",
+    "lib/geo_units/numeric_ext.rb",
     "spec/geo_calc/calculations_spec.rb",
     "spec/geo_calc/core_ext/array_ext_spec.rb",
     "spec/geo_calc/core_ext/hash_ext_spec.rb",
     "spec/geo_calc/core_ext/numeric_geo_ext_spec.rb",
     "spec/geo_calc/core_ext/string_ext_spec.rb",
     "spec/geo_calc/core_ext_spec.rb",
+    "spec/geo_calc/dms/converter_spec.rb",
+    "spec/geo_calc/geo_point/class_methods_spec.rb",
+    "spec/geo_calc/geo_point/initializer_spec.rb",
+    "spec/geo_calc/geo_point/lat_lon.rb",
     "spec/geo_calc/geo_point_spec.rb",
-    "spec/geo_calc/geo_spec.rb",
+    "spec/geo_units/converter_spec.rb",
     "spec/spec_helper.rb",
     "vendor/assets/javascript/geo_calc.js"
   ]
   s.homepage = %q{http://github.com/kristianmandrup/geo_calc}
   s.licenses = [%q{MIT}]
   s.require_paths = [%q{lib}]
-  s.rubygems_version = %q{1.8.3}
+  s.rubygems_version = %q{1.8.5}
   s.summary = %q{Geo calculation library}
 
   if s.respond_to? :specification_version then
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<require_all>, ["~> 1.2.0"])
+      s.add_runtime_dependency(%q<sugar-high>, ["~> 0.4.5.2"])
       s.add_development_dependency(%q<rspec>, [">= 2.5.0"])
       s.add_development_dependency(%q<bundler>, [">= 1"])
       s.add_development_dependency(%q<jeweler>, [">= 1.5.2"])
       s.add_development_dependency(%q<rcov>, [">= 0"])
       s.add_development_dependency(%q<rake>, [">= 0.9"])
     else
+      s.add_dependency(%q<require_all>, ["~> 1.2.0"])
+      s.add_dependency(%q<sugar-high>, ["~> 0.4.5.2"])
       s.add_dependency(%q<rspec>, [">= 2.5.0"])
       s.add_dependency(%q<bundler>, [">= 1"])
       s.add_dependency(%q<jeweler>, [">= 1.5.2"])
@@ -72,6 +93,8 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<rake>, [">= 0.9"])
     end
   else
+    s.add_dependency(%q<require_all>, ["~> 1.2.0"])
+    s.add_dependency(%q<sugar-high>, ["~> 0.4.5.2"])
     s.add_dependency(%q<rspec>, [">= 2.5.0"])
     s.add_dependency(%q<bundler>, [">= 1"])
     s.add_dependency(%q<jeweler>, [">= 1.5.2"])

data/lib/geo_calc/calc/destination.rb

@@ -14,7 +14,7 @@ module GeoCalc::Calc
     # Returns GeoPoint: Destination point
 
     def self.destination_point base_point, brng, dist
-      dist = dist / base_point.radius  # convert dist to angular distance in radians
+      dist = dist / base_point.earth_radius_km  # convert dist to angular distance in radians
       brng = brng.to_rad 
       lat1 = base_point.lat.to_rad
       lon1 = base_point.lon.to_rad

data/lib/geo_calc/calc/distance.rb

@@ -35,7 +35,7 @@ module GeoCalc::Calc
 
       a = Math.sin(dlat/2) * Math.sin(dlat/2) + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dlon/2) * Math.sin(dlon/2)
       c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a))
-      d = base_point.radius * c
+      d = base_point.earth_radius_km * c
       d.round(precision)
     end
   end

data/lib/geo_calc/calc/rhumb.rb

@@ -29,7 +29,7 @@ module GeoCalc::Calc
       # if dlon over 180° take shorter rhumb across 180° meridian:
       dlon = 2*Math::PI - dlon if (dlon > Math::PI)
 
-      dist = Math.sqrt(dlat*dlat + q*q*dlon*dlon) * base_point.radius; 
+      dist = Math.sqrt(dlat*dlat + q*q*dlon*dlon) * base_point.earth_radius_km; 
 
       dist.round(4)  # 4 sig figures reflects typical 0.3% accuracy of spherical model
     end
@@ -69,7 +69,7 @@ module GeoCalc::Calc
     # @returns {LatLon} Destination point
 
     def self.rhumb_destination_point base_point, brng, dist
-      d = dist / base_point.radius  # d = angular distance covered on earth's surface
+      d = dist / base_point.earth_radius_km  # d = angular distance covered on earth's surface
       lat1 = base_point.lat.to_rad
       lon1 = base_point.lon.to_rad
       brng = brng.to_rad

data/lib/geo_calc/calc.rb

@@ -1,27 +1,26 @@
 module GeoCalc
   autoload :PrettyPrint,  'geo_calc/pretty_print'
-  
-  module Calc
-  end
 end
 
-module GeoCalc::Calc
-  autoload :Bearing,      'geo_calc/calc/bearing'
-  autoload :Destination,  'geo_calc/calc/destination'
-  autoload :Distance,     'geo_calc/calc/distance'
-  autoload :Intersection, 'geo_calc/calc/intersection'
-  autoload :Midpoint,     'geo_calc/calc/midpoint'  
-  autoload :Rhumb,        'geo_calc/calc/rhumb'    
+module GeoCalc
+  module Calc
+    autoload :Bearing,      'geo_calc/calc/bearing'
+    autoload :Destination,  'geo_calc/calc/destination'
+    autoload :Distance,     'geo_calc/calc/distance'
+    autoload :Intersection, 'geo_calc/calc/intersection'
+    autoload :Midpoint,     'geo_calc/calc/midpoint'  
+    autoload :Rhumb,        'geo_calc/calc/rhumb'    
   
-  module All
-    def self.included base
-      base.send :include, GeoCalc::Calc::Bearing
-      base.send :include, GeoCalc::Calc::Destination
-      base.send :include, GeoCalc::Calc::Distance
-      base.send :include, GeoCalc::Calc::Intersection
-      base.send :include, GeoCalc::Calc::Midpoint
-      base.send :include, GeoCalc::Calc::Rhumb
-      base.send :include, GeoCalc::PrettyPrint
-    end
-  end  
+    module All
+      def self.included base
+        base.send :include, GeoCalc::Calc::Bearing
+        base.send :include, GeoCalc::Calc::Destination
+        base.send :include, GeoCalc::Calc::Distance
+        base.send :include, GeoCalc::Calc::Intersection
+        base.send :include, GeoCalc::Calc::Midpoint
+        base.send :include, GeoCalc::Calc::Rhumb
+        base.send :include, GeoCalc::PrettyPrint
+      end
+    end  
+  end
 end

data/lib/geo_calc/dms/converter.rb

@@ -0,0 +1,106 @@
+module GeoCalc
+  module Dms
+    module Converter
+      include GeoCalc::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
+      
+      extend self
+    end
+  end
+end

data/lib/geo_calc/dms.rb

@@ -0,0 +1,5 @@
+module GeoCalc
+  module Dms
+    autoload :Converter, 'geo_calc/dms/converter'
+  end
+end

data/lib/geo_calc/extensions/array.rb

@@ -0,0 +1,26 @@
+class Array
+  include ::GeoPoint::CoreExtension
+  
+  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_lng_lat
+    to_lat_lng.reverse
+  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

data/lib/geo_calc/extensions/hash.rb

@@ -0,0 +1,23 @@
+class Hash
+  include GeoPoint::CoreExtension  
+  
+  def to_lat_lng
+    [to_lat, to_lng]
+  end
+
+  def to_lng_lat
+    to_lat_lng.reverse
+  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  
+end

data/lib/geo_calc/extensions/math.rb

@@ -0,0 +1,6 @@
+module Math
+  def self.log10e
+    0.4342944819032518
+  end
+end
+  

data/lib/geo_calc/extensions/numeric.rb

@@ -0,0 +1,24 @@
+require 'geo_units'
+
+module GeoCalc
+  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
+end
+
+class Fixnum
+  include ::GeoUnits::NumericExt 
+end
+
+class Float
+  include ::GeoUnits::NumericExt
+end
+

data/lib/geo_calc/extensions/string.rb

@@ -0,0 +1,44 @@
+class String
+  include ::GeoPoint::CoreExtension
+  
+  def concat *args
+    args.inject(self) do |res, arg| 
+      res << arg.to_s
+      res
+    end
+  end
+
+  def parse_dms
+    GeoCalc::Dms::Converter.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 to_lat_lng  
+    geo_clean.split(',').to_lat_lng
+  end
+
+  def to_lng_lat  
+    geo_clean.split(',').to_lng_lat
+  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

data/lib/geo_calc/extensions/symbol.rb

@@ -0,0 +1,9 @@
+class Symbol
+  def self.lng_symbols
+    [:lon, :long, :lng, :longitude]  
+  end
+
+  def self.lat_symbols
+    [:lat, :latitude]
+  end
+end

data/lib/geo_calc/extensions.rb

@@ -0,0 +1,4 @@
+require 'require_all'
+require 'geo_calc/geo_point/core_extension'
+
+require_all File.dirname(__FILE__) + '/extensions'

data/lib/geo_calc/geo_point/class_methods.rb

@@ -0,0 +1,15 @@
+require 'geo_calc/geo_point/shared'
+
+class GeoPoint
+  module ClassMethods
+    def earth_radius_km  
+      @earth_radius_km ||= 6371
+    end    
+
+    def coord_mode  
+      @coord_mode ||= :lat_lng
+    end    
+           
+    include Shared
+  end
+end

data/lib/geo_calc/geo_point/core_extension.rb

@@ -0,0 +1,11 @@
+class GeoPoint
+  module CoreExtension
+    def to_coords    
+      send(:"to_#{GeoPoint.coord_mode}")
+    end
+
+    def geo_point
+      GeoPoint.new to_coords
+    end
+  end
+end

data/lib/geo_calc/geo_point/shared.rb

@@ -0,0 +1,29 @@
+class GeoPoint
+  module Shared
+    def unit
+      :degrees
+    end
+
+    def earth_radius_km= radius_km
+      raise ArgumentException, "Not a valid earth km radius: #{radius_km}" unless valid_earth_radius? radius_km
+      @earth_radius_km = radius_km
+    end
+
+    def coord_mode= mode
+      raise ArgumentException, "Not a valid coordinates mode: #{mode}" unless valid_mode? mode
+      @coord_mode = mode
+    end
+  
+    protected
+
+    include GeoCalc::NumericCheckExt
+
+    def valid_earth_radius? radius_km
+      is_numeric?(radius_km) && radius_km.is_between?(6350, 6380)            
+    end           
+
+    def valid_mode? mode 
+      [:lng_lat, :lat_lng].include? mode
+    end    
+  end
+end

data/lib/geo_calc/geo_point.rb

@@ -1,5 +1,7 @@
-require 'geo_calc/geo'
+require 'sugar-high/arguments'
 require 'geo_calc/calc'
+require 'geo_calc/extensions'
+require 'geo_calc/geo_point/shared'
 
  #  Sample usage:                                                                                 
  #    p1 = GeoPoint.new(51.5136, -0.0983)                                                      
@@ -8,38 +10,48 @@ require 'geo_calc/calc'
  #    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::Calc::All
+
+  autoload :Shared,         'geo_calc/geo_point/shared'
+  autoload :ClassMethods,   'geo_calc/geo_point/class_methods'
+  autoload :CoreExtension,  'geo_calc/geo_point/core_extension'
+
+  attr_reader   :lat, :lon  
+
   # 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
+  # - Numeric latitude in numeric degrees
+  # - Numeric longitude in numeric degrees  
 
-  attr_reader   :lat, :lon
-  attr_accessor :radius
-  
+  # Optional options
+  # - :radius - earth radius in km
+  # - :mode - coordinates mode, either :lng_lat or :lat_lng, otherwise uses global setting as per GeoPoint.coord_mode
   def initialize *args
-    rad = args.delete(args.size) if is_numeric?(args.last) && args.last.is_between?(6350, 6380)
-    rad ||= 6371 # default
+    options = args.is_a?(GeoPoint) ? {} : args.last_option
+    earth_radius_km = options[:radius]
+    coord_mode = options[:mode]
+    
     case args.size
     when 1
-      create_from_one *args, rad
+      create_from_one args
     when 2
-      create_from_two *args, rad
+      create_from_two *args
     else
       raise "GeoPoint must be initialized with either one or to arguments defining the (latitude, longitude) coordinate on the map"
     end
   end
 
-  def unit
-    :degrees
+  extend ClassMethods
+  include Shared
+
+  def coord_mode
+    @coord_mode ||= GeoPoint.coord_mode
+  end
+
+  def earth_radius_km  
+    @earth_radius_km ||= GeoPoint.earth_radius_km  # default
   end
 
   def lat= value 
@@ -70,7 +82,7 @@ class GeoPoint
     case key
     when Fixnum   
       raise ArgumentError, "Index must be 0 or 1" if !(0..1).cover?(key)
-      to_arr[key] 
+      to_a[key] 
     when String, Symbol
       send(key) if respond_to? key
     else
@@ -98,36 +110,26 @@ class GeoPoint
     [lng, lat]
   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
+  def to_a
+    send(:"to_#{coord_mode}")
   end
   
   protected
 
-  include NumericCheckExt
+  include ::GeoCalc::NumericCheckExt
+
+  def to_coords points
+    points.send(:"to_#{coord_mode}")
+  end
   
-  def create_from_one points, rad = 6371
-    create_from_two *points.to_lat_lng, rad
+  def create_from_one args
+    args = args.first
+    create_from_two *to_coords(args)
   end
   
-  def create_from_two lat, lon, rad = 6371  
-    rad ||= 6371  # earth's mean radius in km
+  def create_from_two lat, lon
     @lat    = lat.to_lat
     @lon    = lon.to_lng
-    @radius = rad    
   end  
 end
 

data/lib/geo_calc/pretty_print.rb

@@ -43,8 +43,8 @@ module GeoCalc
 
       return '-,-' if !lat || !lon
 
-      _lat = Geo.to_lat lat, format, dp
-      _lon = Geo.to_lon lon, format, dp
+      _lat = GeoUnits::Converter.to_lat lat, format, dp
+      _lon = GeoUnits::Converter.to_lon lon, format, dp
 
       "#{_lat}, #{_lon}"
     end

data/lib/geo_calc.rb

@@ -1 +1,6 @@
 require 'geo_calc/geo_point'
+require 'geo_units'
+
+module GeoCalc
+  autoload :Dms, 'geo_calc/dms'
+end