geo_calc 0.5.1

data/spec/geo_calc/calculations_spec.rb

@@ -0,0 +1,174 @@
+require 'spec_helper'
+
+# - www.movable-type.co.uk/scripts/latlong.html
+
+# Accuracy: since the earth is not quite a sphere, there are small errors in using spherical geometry; the earth is actually roughly ellipsoidal (or more precisely, oblate spheroidal) with a radius varying between about 6,378km (equatorial) and 6,357km (polar), and local radius of curvature varying from 6,336km (equatorial meridian) to 6,399km (polar). 6,371 km is the generally accepted value for the Earth’s mean radius. This means that errors from assuming spherical geometry might be up to 0.55% crossing the equator, though generally below 0.3%, depending on latitude and direction of travel. An accuracy of better than 3m in 1km is mostly good enough for me, but if you want greater accuracy, you could use the Vincenty formula for calculating geodesic distances on ellipsoids, which gives results accurate to within 1mm. (Out of sheer perversity – I’ve never needed such accuracy – I looked up this formula and discovered the JavaScript implementation was simpler than I expected).
+# Trig functions take arguments in radians, so latitude, longitude, and bearings in degrees (either decimal or degrees/minutes/seconds) need to be converted to radians, rad = π.deg/180. When converting radians back to degrees (deg = 180.rad/π), West is negative if using signed decimal degrees. For bearings, values in the range -π to +π [-180° to +180°] need to be converted to 0 to +2π [0°–360°]; this can be done by (brng+2.π)%2.π [or brng+360)%360] where % is the modulo operator.
+# 
+# The atan2() function widely used here takes two arguments, atan2(y, x), and computes the arc tangent of the ratio y/x. It is more flexible than atan(y/x), since it handles x=0, and it also returns values in all 4 quadrants -π to +π (the atan function returns values in the range -π/2 to +π/2).
+# All bearings are with respect to true north, 0°=N, 90°=E, etc; if you are working from a compass, magnetic north varies from true north in a complex way around the earth, and the difference has to be compensated for by variances indicated on local maps.
+# 
+# If you implement any formula involving atan2 in Microsoft Excel, you will need to reverse the arguments, as Excel has them the opposite way around from JavaScript – conventional order is atan2(y, x), but Excel uses atan2(x, y). To use atan2 in a (VBA) macro, you can use WorksheetFunction.Atan2().
+# If you are using Google Maps, several of these functions are now provided in the Google Maps API V3 ‘spherical’ library (computeDistanceBetween(), computeHeading(), computeOffset(), interpolate(), etc; 
+# note they use a default Earth radius of 6,378,137 meters).
+# 
+# I learned a lot from the US Census Bureau GIS FAQ which is no longer available, so I’ve made a copy.
+# Thanks to Ed Williams’ Aviation Formulary for many of the formulæ.
+# For miles, divide km by 1.609344
+# For nautical miles, divide km by 1.852
+
+describe GeoCalc do 
+
+  # Point 1: 50 03 59N, 005 42 53W
+  # Point 2: 58 38 38N, 003 04 12W
+  context 'p1= (50 03 59N, 005 42 53W) .. p2= (58 38 38N, 003 04 12W)' do
+    before do
+      @p1 = GeoPoint.new "50 03 59N", "005 42 53W"
+      @p2 = GeoPoint.new "58 38 38N, 003 04 12W"
+    end
+
+    # Distance: 968.9 km
+    describe '#distance_to' do      
+      it 'should return the distance from p1 to p2 as 968.9 km' do
+        @p1.distance_to(@p2).should be_within(0.5).of(968.9)
+      end
+    end
+
+    # Initial bearing:  009°07′11″
+    describe '#bearing_to' do      
+      it 'should return the initial bearing from p1 to p2 as 009 07 11' do
+        @p1.bearing_to(@p2).to_dms.should match /009.+07.+11/
+      end
+    end
+    
+    # Final bearing:  011°16′31″
+    describe '#final_bearing_to' do      
+      it 'should return the initial bearing from p1 to p2 as 011 16 31' do
+        @p1.final_bearing_to(@p2).to_dms.should match /011.+16.+31/
+      end
+    end
+    # 
+    # Midpoint: 54°21′44″N, 004°31′50″W
+    describe '#midpoint_to' do
+      it 'should return the initial bearing from p1 to p2 as 011 16 31' do
+        @p1.midpoint_to(@p2).to_dms.should match /54.+21.+44.+N, 004.+31.+50.+W/
+      end
+    end
+  end # context
+
+  # Start Point:  53°19′14″N, 001°43′47″W
+  # Bearing:      096°01′18″
+  # Distance:     124.8
+  
+  context 'Start Point: (53 19 14 N, 001 43 47 W)' do
+    before do
+      @p1 = GeoPoint.new "53 19 14 N, 001 43 47 W"
+    end
+  
+    # Destination point:  53°11′18″N, 000°08′00″E
+    # Final bearing:      097°30′52″
+    describe '#destination_point' do      
+      it 'should return the destination_point as (53 11 18 N, 000 08 00 E)' do
+        # Bearing:      096°01′18″
+        # Distance:     124.8
+        @p2 = @p1.destination_point("096 01 18", 124.8)
+        @p2.to_dms.should match /53.+11.+18.+N, 000.+08.+00.+E/
+  
+        # @p1.final_bearing_to(@p2).to_dms.should == "097°30′52″"
+      end
+    end
+  end
+  
+  # Intersection:
+  # Point 1: 51.885 N, 0.235 E; Brng 108.63°
+  # Point 2: 49.008 N, 2.549 E; Brng 32.72°
+  # Distance:     124.8 km
+  context 'Points: (51.885 N, 0.235 E) Brng 108.63 .. (49.008 N, 2.549 E) Brng 32.72' do
+    before do
+      @p1 = GeoPoint.new "51.885 N, 0.235 E"
+      @brng1 = "108.63"
+      @p2 = GeoPoint.new "49.008 N, 2.549 E"
+      @brng2 = "32.72"
+    end
+  
+    # Intersection point:   50°54′06″N, 004°29′39″E
+    describe '#intersection' do      
+      it 'should return the intersection between p1 and p2 as (50 54 06 N, 004 29 39 E)' do
+        GeoCalc.intersection(@p1, @brng1, @p2, @brng2).to_dms.should match /50.+54.+06.+N, 004.+29.+39.+E/
+      end
+    end
+  end
+  
+  # Rhumb lines:
+  # Point 1:  (50 21 50 N, 004 09 25 W)
+  # Point 2:  (42 21 04 N, 071 02 27 W)
+  context 'Points: (50 21 50N, 004 09 25W ) (42 21 04N, 071 02 27 W)' do
+    before do
+      @p1 = GeoPoint.new "50 21 50N, 004 09 25 W"
+      @p2 = GeoPoint.new "42 21 04N, 071 02 27 W"
+    end
+    
+    # Distance:   5196 km
+    describe '#rhumb_distance_to' do
+      it 'should return the distance from p1 to p2 as 5196 km' do
+        @p1.rhumb_distance_to(@p2).should be_within(1).of(5196)
+      end
+    end
+  
+    # Bearing:    260°07′38″
+    describe '#rhumb_bearing_to' do      
+      it 'should return the initial bearing from p1 to p2 as 260 07 38' do
+        @p1.rhumb_bearing_to(@p2).to_dms.should match /260.+07.+38/
+      end
+    end
+  end
+  
+  # Start Point:  (51 07 32N, 001 20 17E)
+  # Bearing:      116°38′10
+  # Distance:     40.23 km
+  context 'Start Point: (51 07 32N, 001 20 17E), Bearing: 116 38 10, Distance: 40.23 km' do
+    before do
+      @p1 = GeoPoint.new "51 07 32N, 001 20 17E"
+      @brng = "116 38 10" 
+      @dist = 40.23
+    end
+        
+    # Destination point:  50°57′48″N, 001°51′09″E
+    describe '#rhumb_destination_point' do      
+      it 'should return the destination_point as (50 57 48 N, 001 51 09 E)' do
+        @p2 = @p1.rhumb_destination_point(@brng, @dist)
+        @p2.to_dms.should match /50.+57.+48.+N, 001.+51.+09.+E/
+      end
+    end
+  end
+  
+  # Conversion
+  # Point: (52°12′17.0″N, 000°08′26.0″E)
+  # 52.20472 numeric deg (lat)
+  # 0.14056 numeric deg (lon)
+  context 'Point: (52 12 17.0 N, 000 08 26.0 E)' do
+    before do
+      @p = GeoPoint.new "52 12 17.0 N", "000 08 26.0 E"
+      @lat = 52.20472
+      @lon = 0.14056
+    end
+  
+    # 1° ≈ 111 km (110.57 eq’l — 111.70 polar)
+    # 1′ ≈ 1.85 km (= 1 nm)   0.01° ≈ 1.11 km
+    # 1″ ≈ 30.9 m   0.0001° ≈ 11.1 m
+  
+    # Convert numeric degrees to deg/min/sec longitude (suffixed with E/W)
+    describe '#to_lon' do      
+      it 'should Convert numeric degrees to deg/min/sec longitude (suffixed with E/W)' do
+        @lon.to_lon_dms.should match /000.+08.+26.+E/
+      end
+    end
+    
+    # Convert numeric degrees to deg/min/sec latitude (suffixed with N/S)
+    describe '#to_lat' do      
+      it 'should convert numeric degrees to deg/min/sec latitude (suffixed with N/S)' do
+        @lat.to_lat_dms.should match /52.+12.+17.+N/
+      end
+    end
+  end 
+end

data/spec/geo_calc/core_ext_spec.rb

@@ -0,0 +1,272 @@
+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
+
+        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
+      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
+
+        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
+      end
+      
+      describe '#to_degrees' do      
+        it 'should alias to_deg' do
+          360.to_deg.should == 360.to_degrees
+        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
+      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
+      end
+    end # NumericGeoExt
+    
+    describe NumericLatLngExt do
+      describe 'Fixnum extension' do
+        describe '#to_lat' do              
+          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 'Array extension' do
+        describe '#to_lat' do              
+          it 'should return latitude as first element' do
+            @arr = [4, 27]
+            @arr.to_lat.should == 4
+          end
+
+          it 'should return latitude as #to_lng of first element' do
+            @arr = ["4.1", 27]
+            @arr.to_lat.should == 4.1
+          end
+        end      
+
+        describe '#to_lng' do              
+          it 'should return latitude degree value for 360' do
+            @arr = [4, 27]            
+            @arr.to_lng.should == 27
+          end
+
+          it 'should return latitude as #to_lng of first element' do
+            @arr = [4, "27.2"]            
+            @arr.to_lng.should == 27.2
+          end
+        end   
+
+        describe '#to_lat_lng' do              
+          it 'should return Array with lat, lng' do
+            @arr = ["3", {:lng => "2"}]
+            @arr.to_lat_lng.should == [3, 2]
+          end
+        end 
+        
+        describe '#geo_point' do              
+          it 'should return a GeoPoint' do
+            @p = [3, 2].geo_point
+            @p.should be_a(GeoPoint)
+            @p.to_lat_lng.should == [3, 2]
+          end
+        end                            
+      end # Array
+
+      describe 'Hash extension' do
+        describe '#to_lat' do              
+          it 'should return latitude as #to_lat on the value for key :lat' do
+            @hash = {:lat => 4}
+            @hash.to_lat.should == 4
+          end
+
+          it 'should return latitude as #to_lat on the value for key :latitude' do
+            @hash = {:latitude => "7"}
+            @hash.to_lat.should == 7
+          end
+        end      
+
+        describe '#to_lng' do              
+          it 'should return latitude as #to_lng on the value for key :lng' do
+            @hash = {:lng => 2}
+            @hash.to_lng.should == 2
+          end
+
+          it 'should return latitude as #to_lng on the value for key :longitude' do
+            @hash = {:longitude => "3.1"}
+            @hash.to_lng.should == 3.1
+          end 
+        end
+
+        describe '#to_lat_lng' do              
+          it 'should return Array with lat, lng' do
+            @hash = {:lng => 2, :lat => "3"}
+            @hash.to_lat_lng.should == [3, 2]
+          end
+        end 
+        
+        describe '#geo_point' do              
+          it 'should return a GeoPoint' do
+            @p = {:lng => 2, :lat => "3"}.geo_point
+            @p.should be_a(GeoPoint)            
+            @p.to_lat_lng.should == [3, 2]
+          end
+        end         
+      end # Hash 
+      
+      describe 'String extension' do
+        describe '#to_lat' do              
+          it 'should not return latitude on empty String' do
+            @str = ""
+            lambda { @str.to_lat}.should raise_error
+          end
+
+          it 'should return latitude' do
+            @str = "4"
+            @str.to_lat.should == 4
+          end
+
+          it 'should convert to latitude' do
+            @str = "50 03 59N"
+            @str.to_lat.should be_within(0.4).of(50)
+          end
+        end      
+
+        describe '#to_lng' do              
+          it 'should not return longitude on empty String' do
+            @str = ""
+            lambda { @str.to_lng}.should raise_error
+          end
+
+          it 'should return latitude' do
+            @str = "4"
+            @str.to_lat.should == 4
+          end
+
+          it 'should convert to latitude' do
+            @str = "50 03 59E"
+            @str.to_lat.should be_within(0.4).of(50)
+          end
+        end
+
+        describe '#to_lat_lng' do              
+          it 'should return Array with lat, lng' do
+            @str = "4, 3"
+            @str.to_lat_lng.should == [4, 3]
+          end
+
+          it 'should raise error if only latitude' do
+            @str = "4"
+            lambda { @str.to_lat_lng}.should raise_error
+          end
+
+          it 'should raise error if "," but only latitude' do
+            @str = "4,"
+            lambda { @str.to_lat_lng}.should raise_error
+          end
+
+          it 'should raise error if "," in bad position' do
+            @str = ", 4 3"
+            lambda { @str.to_lat_lng}.should raise_error
+          end
+
+          it 'should raise error if not using "," as seperator' do
+            @str = "4; 3"
+            lambda { @str.to_lat_lng}.should raise_error
+          end
+        end 
+        
+        describe '#geo_point' do              
+          it 'should return a GeoPoint' do
+            @p = "3, 2".geo_point
+            @p.should be_a(GeoPoint)            
+            @p.to_lat_lng.should == [3, 2]
+          end
+        end                 
+      end # String      
+    end
+  end
+end

data/spec/geo_calc/geo_point_spec.rb

@@ -0,0 +1,228 @@
+require 'spec_helper'
+
+# - www.movable-type.co.uk/scripts/latlong.html
+describe GeoPoint do 
+  describe '#initializer' do
+    describe '1 argument' do
+      describe 'single String' do
+        describe '50.1, 5.0 ' do
+          it 'should create a GeoPoint' do
+            p1 = GeoPoint.new "50.1, 5.0"
+            p1.should be_a(GeoPoint)
+            p1.lat.should == 50.1
+            p1.lon.should == 5.0
+            p1.unit.should == :degrees
+            p1.radius.should == 6371
+          end
+        end    
+
+        describe '(50.1, 5.0)' do
+          it 'should create a GeoPoint' do
+            p1 = GeoPoint.new "(50.1, 5.2)"
+            p1.should be_a(GeoPoint)
+            p1.lat.should == 50.1
+            p1.lon.should == 5.2
+            p1.unit.should == :degrees
+            p1.radius.should == 6371
+          end
+        end 
+        
+        describe '58 38 38N, 003 04 12W' do
+          it 'should create a GeoPoint' do
+            p1 = GeoPoint.new "58 38 38N, 003 04 12W"
+            p1.should be_a(GeoPoint)
+            p1.lat.should be_within(0.5).of(58.38)
+            p1.lon.should be_within(0.5).of(356.5)
+            p1.unit.should == :degrees
+            p1.radius.should == 6371
+          end
+        end 
+
+        describe '(58 38 38N, 003 04 12W)' do
+          it 'should create a GeoPoint' do
+            p1 = GeoPoint.new "(58 38 38N, 003 04 12W)"
+            p1.should be_a(GeoPoint)
+            p1.lat.should be_within(0.5).of(58.38)
+            p1.lon.should be_within(0.5).of(356.5) # W is negative, then normalize
+            p1.unit.should == :degrees
+            p1.radius.should == 6371
+          end
+        end
+      end
+      
+      describe 'single Array' do
+        describe '2 Fixed numbers: 50,5 ' do
+          it 'should create a GeoPoint' do
+            p1 = GeoPoint.new [50, 5]
+            p1.should be_a(GeoPoint)
+            p1.lat.should == 50
+            p1.lon.should == 5
+            p1.unit.should == :degrees        
+            p1.radius.should == 6371
+          end
+        end
+        
+        describe '2 Float numbers: 50.1, 5.0 ' do
+          it 'should create a GeoPoint' do
+            p1 = GeoPoint.new [50.1, 5.0]
+            p1.should be_a(GeoPoint)
+            p1.lat.should == 50.1
+            p1.lon.should == 5.0
+            p1.unit.should == :degrees
+            p1.radius.should == 6371
+          end
+        end            
+        
+        describe 'single Hash' do
+          describe 'with: {:lat => 50.1, :lng => 5.1}' do
+            it 'should create a GeoPoint' do
+              p1 = GeoPoint.new :lat => 50.1, :lng => 5.1
+              p1.should be_a(GeoPoint)
+              p1.lat.should == 50.1
+              p1.lon.should == 5.1
+              p1.unit.should == :degrees
+              p1.radius.should == 6371
+            end
+          end            
+    
+          describe 'with: {:lat => 50.1, :long => 5.1}' do
+            it 'should create a GeoPoint' do
+              p1 = GeoPoint.new :lat => 50.1, :long => 5.1
+              p1.should be_a(GeoPoint)
+              p1.lat.should == 50.1
+              p1.lon.should == 5.1
+              p1.unit.should == :degrees
+              p1.radius.should == 6371
+            end
+          end            
+    
+          describe 'with: {:latitude => 50.1, :longitude => 5.1}' do
+            it 'should create a GeoPoint' do
+              p1 = GeoPoint.new :latitude => 50.1, :longitude => 5.1
+              p1.should be_a(GeoPoint)
+              p1.lat.should == 50.1
+              p1.lon.should == 5.1
+              p1.unit.should == :degrees
+              p1.radius.should == 6371
+            end
+          end
+        end
+      end     
+    end 
+    
+    describe 'with 2 arguments' do
+      describe '2 Fixed numbers (Fixnum)' do
+        it 'should create a GeoPoint' do
+          p1 = GeoPoint.new 50, 5
+          p1.should be_a(GeoPoint)
+          p1.lat.should == 50
+          p1.lon.should == 5
+          p1.unit.should == :degrees        
+          p1.radius.should == 6371
+        end
+      end
+  
+      describe '2 Float numbers' do
+        it 'should create a GeoPoint' do
+          p1 = GeoPoint.new 50.1, 5.0
+          p1.should be_a(GeoPoint)
+          p1.lat.should == 50.1
+          p1.lon.should == 5.0
+          p1.unit.should == :degrees
+          p1.radius.should == 6371
+        end
+      end    
+      
+      describe '2 Strings: "58 38 38N", "003 04 12W"' do
+        it 'should create a GeoPoint' do
+          p1 = GeoPoint.new "58 38 38N", "003 04 12W"
+          p1.should be_a(GeoPoint)
+          p1.lat.should be_within(0.5).of(58.38)
+          p1.lon.should be_within(0.5).of(356.5)
+          p1.unit.should == :degrees
+          p1.radius.should == 6371
+        end
+      end  
+    end
+  end # initializer  
+
+  describe '#to_s' do
+    before :each do
+      @p1 = GeoPoint.new 50.1, 5
+    end
+  
+    it 'should return GeoPoint as a dms formatted String' do
+      @p1.to_s.should match /50.+5/
+    end
+  
+    it 'should return GeoPoint as a dms formatted String' do
+      @p1.to_s(:dm, 2).should match /50.+5/
+    end
+  end
+
+  describe '#lat' do
+    before :each do
+      @p1 = GeoPoint.new 50, 5
+    end
+  
+    it 'should return latitude' do
+      @p1.lat.should == 50
+    end
+
+    describe '#latitude (alias)' do
+      it 'should return latitude' do
+        @p1.latitude.should == 50
+      end
+    end
+  end
+
+  describe '#[]' do
+    before :each do
+      @p1 = GeoPoint.new 50, 5
+    end
+  
+    it 'index of 0 should return latitude' do
+      @p1[0].should == 50
+    end
+
+    it 'index of 1 should return longitude' do
+      @p1[1].should == 5
+    end
+
+    it 'index of 2 should raise error' do
+      lambda {@p1[2]}.should raise_error
+    end
+
+    it ':lat should return latitude' do
+      @p1[:lat].should == 50
+    end
+
+    it ':long should return longitude' do
+      @p1[:long].should == 5
+    end
+  end
+  
+  describe '#to_arr' do
+    before :each do
+      @p1 = GeoPoint.new 50, 5
+    end
+  
+    it 'should return GeoPoint as an array depending on state of reverse_arr' do
+      @p1.to_arr.should == [50, 5]
+    end
+  
+    describe '#reverse_arr!' do    
+      it 'should reverse the array returned by #to_arr to [lng, lat]' do
+        @p1.reverse_arr!
+        @p1.to_arr.should == [5, 50]
+      end
+    end
+      
+    describe '#reverse_arr!' do    
+      it 'should turn effect of #to_arr back to normal [lat, lng]' do
+        @p1.normal_arr!
+        @p1.to_arr.should == [50, 5]      
+      end
+    end
+  end
+end