geo_calc 0.6.1 → 0.7.1

data/lib/geo_units/converter.rb

@@ -0,0 +1,123 @@
+require 'geo_calc/calc'
+require 'geo_calc/extensions'
+
+module GeoUnits
+  module Converter
+    # 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
+      deg = deg.normalize_lat
+      _lat = GeoCalc::Dms::Converter.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 = deg.normalize_lng
+      lon = GeoCalc::Dms::Converter.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 = GeoCalc::Dms::Converter.to_dms deg, format, dp
+      brng.gsub /360/, '0'  # just in case rounding took us up to 360º!
+    end 
+
+    protected
+
+    include ::GeoCalc::NumericCheckExt    
+    
+    # Converts numeric degrees to radians
+    def to_rad degrees
+      degrees * 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 radians
+      radians * 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
+    
+    extend self    
+  end 
+
+  # all degrees between -180 and 180
+  def normalize_lng deg
+    case deg 
+    when -360..-180
+      deg % 180      
+    when -180..0 
+      -180 + (deg % 180) 
+    when 0..180
+      deg
+    when 180..360
+      deg % 180
+    else
+      raise ArgumentError, "Degrees #{deg} out of range, must be between -360 to 360"
+    end
+  end
+
+  # all degrees between -90 and 90
+  def normalize_lat deg
+    case deg 
+    when -360..-270
+      deg % 90      
+    when -270..-180
+      90 - (deg % 90)
+    when -180..-90
+      - (deg % 90)
+    when -90..0 
+      -90 + (deg % 90) 
+    when 0..90
+      deg
+    when 90..180 
+      deg % 90
+    when 180..270 
+      - (deg % 90)
+    when 270..360 
+      - 90 + (deg % 90)
+    else
+      raise ArgumentError, "Degrees #{deg} out of range, must be between -360 to 360"    
+    end 
+  end
+  
+  def normalize_deg degrees, shift = 0
+    (degrees + shift) % 360 
+  end
+  alias_method :normalize_degrees, :normalize_deg  
+  
+  extend self
+end

data/lib/geo_units/numeric_ext.rb

@@ -0,0 +1,117 @@
+module GeoUnits
+  module NumericExt
+    def to_lat 
+      normalize_lat
+    end
+
+    def to_lng 
+      normalize_lng
+    end
+
+    def is_between? lower, upper
+      (lower..upper).cover? self
+    end
+
+    
+    def to_dms format = :dms, dp = nil
+      GeoCalc::Dms::Converter.to_dms self, format, dp
+    end
+
+    def to_lat_dms format = :dms, dp = nil
+      GeoUnits::Converter.to_lat self, format, dp
+    end
+
+    def to_lon_dms format = :dms, dp = nil
+      GeoUnits::Converter.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
+    end
+    alias_method :to_fixed, :to_precision
+
+    # all degrees between -180 and 180
+    def normalize_lng
+      case self 
+      when -360, 0, 360
+        0
+      when -360..-180
+        self % 180      
+      when -180..0 
+        -180 + (self % 180) 
+      when 0..180
+        self
+      when 180..360
+        self % 180
+      else
+        return (self % 360).normalize_lng if self > 360
+        return (360 - (self % 360)).normalize_lng if self < -360
+        raise ArgumentError, "Degrees #{self} out of range"
+      end
+    end
+
+    # all degrees between -90 and 90
+    def normalize_lat
+      case self 
+      when -360, 0, 360
+        0
+      when -180, 180
+        0
+      when -360..-270
+        self % 90      
+      when -270..-180
+        90 - (self % 90)
+      when -180..-90
+        - (self % 90)
+      when -90..0 
+        -90 + (self % 90) 
+      when 0..90
+        self
+      when 90..180 
+        self % 90
+      when 180..270 
+        - (self % 90)
+      when 270..360 
+        - 90 + (self % 90)
+      else
+        return (self % 360).normalize_lat if self > 360
+        return (360 - (self % 360)).normalize_lat if self < -360
+        raise ArgumentError, "Degrees #{self} out of range"      
+      end
+    end
+
+    def normalize_deg shift = 0
+      (self + shift) % 360 
+    end
+    alias_method :normalize_degrees, :normalize_deg  
+  end
+end

data/lib/geo_units.rb

@@ -0,0 +1,21 @@
+ # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  
+ #  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 GeoUnits
+  autoload :Converter,  'geo_units/converter'
+  autoload :NumericExt,    'geo_units/numeric_ext'
+end  

data/spec/geo_calc/core_ext/numeric_geo_ext_spec.rb

@@ -3,71 +3,69 @@ require 'spec_helper'
 # - www.movable-type.co.uk/scripts/latlong.html
 describe GeoPoint do 
   describe 'ruby core Class extensions' do
-    describe NumericGeoExt do
-      describe '#to_rad' do
-        it 'should convert 0 degrees to 0 radians' do
-          0.to_rad.should == 0
-        end
+    describe '#to_rad' do
+      it 'should convert 0 degrees to 0 radians' do
+        0.to_rad.should == 0
+      end
 
-        it 'should convert 180 degrees to PI radians' do
-          180.to_rad.should == Math::PI        
-        end
+      it 'should convert 180 degrees to PI radians' do
+        180.to_rad.should == Math::PI        
+      end
 
-        it 'should convert 360 degrees to 6.28 radians' do
-          360.to_rad.should == Math::PI*2                
-        end
+      it 'should convert 360 degrees to 6.28 radians' do
+        360.to_rad.should == Math::PI*2                
       end
+    end
 
-      describe '#to_radians' do      
-        it 'should alias to_rad' do
-          360.to_rad.should == 360.to_radians
-        end
+    describe '#to_radians' do      
+      it 'should alias to_rad' do
+        360.to_rad.should == 360.to_radians
       end
+    end
 
-      describe '#to_deg' do
-        it 'should convert 0 radians to 0 degrees' do
-          0.to_deg.should == 0
-        end
+    describe '#to_deg' do
+      it 'should convert 0 radians to 0 degrees' do
+        0.to_deg.should == 0
+      end
 
-        it 'should convert PI radians to 180 degrees' do
-          180.to_rad.to_deg.should be_within(0.01).of(180)
-        end
+      it 'should convert PI radians to 180 degrees' do
+        180.to_rad.to_deg.should be_within(0.01).of(180)
+      end
 
-        it 'should convert 6.28 radians to 360 degrees' do
-          360.to_rad.to_deg.should be_within(0.01).of(360)
-        end
+      it 'should convert 6.28 radians to 360 degrees' do
+        360.to_rad.to_deg.should be_within(0.01).of(360)
       end
-      
-      describe '#to_degrees' do      
-        it 'should alias to_deg' do
-          360.to_deg.should == 360.to_degrees
-        end
+    end
+    
+    describe '#to_degrees' do      
+      it 'should alias to_deg' do
+        360.to_deg.should == 360.to_degrees
       end
-      
-      describe '#to_fixed' do
-        it 'should make precision 4' do
-          1.123456.to_fixed(2).should == '1.12'
-        end
+    end
+    
+    describe '#to_fixed' do
+      it 'should make precision 4' do
+        1.123456.to_fixed(2).should == '1.12'
       end
+    end
 
-      describe '#to_precision' do
-        it 'should alis to_fixed' do
-          1.123456.to_precision(4).should == '1.1235'
-        end
+    describe '#to_precision' do
+      it 'should alis to_fixed' do
+        1.123456.to_precision(4).should == '1.1235'
       end
+    end
 
-      describe '#normalize' do
-        it 'should turn 180 deg and normalize' do
-          361.normalize_deg(180).should == 181
-        end
-        it 'should normalize deg' do
-          361.normalize_deg.should == 1
-        end
+    describe '#normalize' do
+      it 'should turn 180 deg and normalize' do
+        361.normalize_deg(180).should == 181
+      end
+      it 'should normalize deg' do
+        361.normalize_deg.should == 1
+      end
 
-        it 'should alias with #normalize_degrees' do
-          362.normalize_degrees.should == 2
-        end
+      it 'should alias with #normalize_degrees' do
+        362.normalize_degrees.should == 2
       end
-    end # NumericGeoExt
+    end
   end
 end

data/spec/geo_calc/core_ext_spec.rb

@@ -3,56 +3,54 @@ require 'spec_helper'
 # - www.movable-type.co.uk/scripts/latlong.html
 describe GeoPoint do 
   describe 'ruby core Class extensions' do
-    describe NumericLatLngExt do
-      describe 'Fixnum extension' do
-        describe '#to_lat' do              
-          it 'should set origin at 0,0' do
-            origin = [0, 0].geo_point
-            origin.lat.should == 0       
-            origin.lng.should == 0
-          end
-
-          it 'should return latitude degree value for 360' do
-            360.to_lat.should == 0
-          end
-
-          it 'should normalize degrees before converting to latitude, so 361 becomes 1' do
-            361.to_lat.should == 1
-          end
-        end      
-
-        describe '#to_lng' do              
-          it 'should return latitude degree value for 360' do
-            90.to_lng.should == 90
-          end
-
-          it 'should normalize degrees before converting to latitude, so 361 becomes 1' do
-            91.to_lng.should == 91
-          end
-        end      
-      end
-
-      describe 'Float extension' do
-        describe '#to_lat' do              
-          it 'should return latitude degree value for 360' do
-            (360.0).to_lat.should == 0
-          end
-
-          it 'should normalize degrees before converting to latitude, so 361 becomes 1' do
-            (361.1).to_lat.should be_within(0.01).of(1.1)
-          end
-        end      
-
-        describe '#to_lng' do              
-          it 'should return latitude degree value for 360' do
-            (360.0).to_lng.should == 0
-          end
-
-          it 'should normalize degrees before converting to latitude, so 361 becomes 1' do
-            (361.1).to_lng.should be_within(0.01).of(1.1)
-          end
-        end      
-      end
+    describe 'Fixnum extension' do
+      describe '#to_lat' do              
+        it 'should set origin at 0,0' do
+          origin = [0, 0].geo_point
+          origin.lat.should == 0       
+          origin.lng.should == 0
+        end
+
+        it 'should return latitude degree value for 360' do
+          360.to_lat.should == 0
+        end
+
+        it 'should normalize degrees before converting to latitude, so 361 becomes 1' do
+          361.to_lat.should == 1
+        end
+      end      
+
+      describe '#to_lng' do              
+        it 'should return latitude degree value for 360' do
+          90.to_lng.should == 90
+        end
+
+        it 'should normalize degrees before converting to latitude, so 361 becomes 1' do
+          91.to_lng.should == 91
+        end
+      end      
     end
-  end
+
+    describe 'Float extension' do
+      describe '#to_lat' do              
+        it 'should return latitude degree value for 360' do
+          (360.0).to_lat.should == 0
+        end
+
+        it 'should normalize degrees before converting to latitude, so 361 becomes 1' do
+          (361.1).to_lat.should be_within(0.01).of(1.1)
+        end
+      end      
+
+      describe '#to_lng' do              
+        it 'should return latitude degree value for 360' do
+          (360.0).to_lng.should == 0
+        end
+
+        it 'should normalize degrees before converting to latitude, so 361 becomes 1' do
+          (361.1).to_lng.should be_within(0.01).of(1.1)
+        end
+      end      
+    end
+  end 
 end

data/spec/geo_calc/dms/converter_spec.rb

@@ -0,0 +1,60 @@
+require 'spec_helper'
+
+class Parser
+  include GeoCalc::Dms::Converter
+end
+
+def parser
+  Parser.new
+end
+
+# - www.movable-type.co.uk/scripts/latlong.html
+describe GeoCalc::Dms::Converter do
+  # # @param   {String|Number} dmsStr: Degrees or deg/min/sec in variety of formats
+  # @returns {Number} Degrees as decimal number
+  describe '#parse_dms' do
+    it 'should convert "58 38 38N" to a Float of degrees (58..59)' do
+      deg = parser.parse_dms("58 38 38N")
+      deg.should be_a(Float)
+      deg.should be_between(58, 59)
+    end
+
+    it 'should convert "01 38 38W" to a Float of degrees (1..2)' do
+      deg = parser.parse_dms("01 38 38W")
+      deg.should be_a(Float)
+      deg.should < 0
+      deg.should > -2       
+    end
+
+    it 'should convert "005 38 E" to a Float of degrees (5..6)' do
+      deg = parser.parse_dms("005 38 E")
+      deg.should be_a(Float)
+      deg.should be_between(5, 6)
+    end
+  end
+
+  # deg, format = :dms, dp = 0
+  describe '#to_dms' do
+    it 'should convert 58.3 to a String in DMS format' do
+      dms = parser.to_dms(58.3)
+      dms.should be_a(String)
+      expr = Regexp.escape "058".concat("\u00B0", "18", "\u2032", "00", "\u2033")
+      dms.should match expr
+    end
+  
+    it 'should convert 58.3 to a String in DM format' do
+      dm = parser.to_dms(58.3, :dm, 2)
+      dm.should be_a(String)
+      expr = Regexp.escape "058".concat("\u00B0", "18", "\u2032")
+      dm.should match expr
+    end
+  
+    it 'should convert 58.3 to a String in D format' do
+      d = parser.to_dms(58.3, :d, 2)
+      d.should be_a(String)
+      m = Regexp.escape "058".concat("\u00B0")
+      d.should match m
+    end
+  end  
+end
+

data/spec/geo_calc/geo_point/class_methods_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+
+# - www.movable-type.co.uk/scripts/latlong.html
+describe GeoPoint do  
+  describe 'Class methods' do     
+    describe '#coord_mode' do
+      it 'should change global coordinates mode' do
+        GeoPoint.coord_mode = :lng_lat
+        GeoPoint.coord_mode.should == :lng_lat        
+
+        GeoPoint.coord_mode = :lat_lng
+        GeoPoint.coord_mode.should == :lat_lng                        
+      end
+      
+      it 'shoould not allow setting invalid coord mode' do
+        lambda { GeoPoint.coord_mode = :blip }.should raise_error
+      end
+    end
+    
+    describe '#earth_radius_km' do
+      it 'should change global earth_radius_km' do
+        GeoPoint.earth_radius_km = 6360
+        GeoPoint.earth_radius_km.should == 6360
+      end
+      
+      it 'shoould not allow setting invalid earth radius' do
+        lambda { GeoPoint.earth_radius_km = 6100 }.should raise_error
+      end    
+    end
+  end
+end