latitude 0.1.0 → 0.2.0

data/README.md

@@ -27,8 +27,35 @@ Or install it yourself as:
 
 Note that coordinates are positive for N/E and negative for S/W.
 
-`Latitude.great_circle_distance(start_latitude, start_longitude, end_latitude,
-end_longitude)`
+### Using Coordinate objects
+
+A `Coordinate` takes in a `:latitude` and `:longitude` in either decimal
+or DMS format. For example,
+
+```
+coordinate = Coordinate.new(:latitude => "10 S",
+                            :longitude => "9° 30′ E")
+coordinate.latitdue     #=> -10.0
+coordinate.longitude    #=> 9.5
+```
+
+`Coordinate`s have multiple helper methods:
+
+`#great_circle_distance_to(final_coordinate)` calculates the great
+circle distance between coordinates.
+
+`#initial_bearing_to(final_coordinate)` calculates the initial bearing
+if traveling along a great circle route to another coordinate.
+
+`#final_bearing_to(initial_coordinate)` calculates the final bearing if
+traveling along a great circle route from another coordinate.
+
+### Without Coordinate objects
+
+```
+Latitude.great_circle_distance(start_latitude, start_longitude, end_latitude,
+end_longitude)
+```
 
 Calculates the great circle distance in kilometers between two
 coordinates.

data/lib/latitude.rb

@@ -1,24 +1,38 @@
+#!/bin/env ruby
+# encoding: utf-8
 require "latitude/version"
 require "latitude/vincenty"
+require "latitude/coordinate"
 
 module Latitude
   extend self
   def great_circle_distance(start_latitude, start_longitude, end_latitude, end_longitude)
+    start_coordinate = Coordinate.new(:latitude => start_latitude,
+                                      :longitude => start_longitude)
+    end_coordinate = Coordinate.new(:latitude => end_latitude,
+                                    :longitude => end_longitude)
     # in kilometers
-    m_distance = Vincenty.great_circle_distance(start_latitude, start_longitude,
-                                                end_latitude, end_longitude)
+    m_distance = start_coordinate.great_circle_distance_to(end_coordinate)
 
     return m_distance / 1000.0
   end
 
   def initial_bearing(start_latitude, start_longitude, end_latitude, end_longitude)
-    Vincenty.initial_bearing(start_latitude, start_longitude,
-                            end_latitude, end_longitude)
+    start_coordinate = Coordinate.new(:latitude => start_latitude,
+                                      :longitude => start_longitude)
+    end_coordinate = Coordinate.new(:latitude => end_latitude,
+                                    :longitude => end_longitude)
+
+    start_coordinate.initial_bearing_to(end_coordinate)
   end
 
   def final_bearing(start_latitude, start_longitude, end_latitude, end_longitude)
-    Vincenty.final_bearing(start_latitude, start_longitude,
-                          end_latitude, end_longitude)
+    start_coordinate = Coordinate.new(:latitude => start_latitude,
+                                      :longitude => start_longitude)
+    end_coordinate = Coordinate.new(:latitude => end_latitude,
+                                    :longitude => end_longitude)
+
+    end_coordinate.final_bearing_from(start_coordinate)
   end
 
 end

data/lib/latitude/coordinate.rb

@@ -0,0 +1,108 @@
+#!/bin/env ruby
+# encoding: utf-8
+
+class Coordinate
+  COORDINATE_CHARS = "0-9.\'\"°′″"
+  attr_reader :latitude, :longitude
+
+  def initialize(params = {})
+    self.latitude  = params[:latitude]
+    self.longitude = params[:longitude]
+  end
+
+  def latitude=(val)
+    @latitude = convert_degree_input_to_decimal(val, ["N","S"], ["S"])
+  end
+
+  def longitude=(val)
+    @longitude = convert_degree_input_to_decimal(val, ["E","W"], ["W"])
+  end
+
+  def valid?
+    latitude && longitude && (latitude.abs <= 90) && (longitude.abs <= 180)
+  end
+
+  def great_circle_distance_to(final_coordinate)
+    Vincenty.great_circle_distance(latitude, longitude,
+                                   final_coordinate.latitude,
+                                   final_coordinate.longitude)
+  end
+
+  def initial_bearing_to(final_coordinate)
+    Vincenty.initial_bearing(latitude, longitude,
+                             final_coordinate.latitude,
+                             final_coordinate.longitude)
+  end
+
+  def final_bearing_from(start_coordinate)
+    Vincenty.final_bearing(start_coordinate.latitude,
+                           start_coordinate.longitude,
+                           latitude, longitude)
+  end
+
+private
+  def convert_degree_input_to_decimal(input, valid_directions, negative_directions)
+    return if input.nil? || (input.is_a?(String) && input.empty?)
+    input.strip! if input.is_a? String
+
+    return Float(input) if is_number?(input)
+
+    raise ArgumentError unless input.gsub(valid_char_regexp(valid_directions), "").empty?
+    raise ArgumentError unless valid_end_char_regexp(valid_directions).match(input)
+
+    if valid_directions.map(&:upcase).include? input[-1].upcase
+      direction = input[-1].upcase
+      convert_to_negative = negative_directions.map(&:upcase).include? direction
+      input = input[0...-1].strip
+    else
+      convert_to_negative = false
+    end
+
+    return (convert_to_negative ? -1 : 1) * Float(input) if is_number?(input)
+
+    degrees = minutes = seconds = 0
+    # first, get the degrees
+    if degree_location = input.index(/°/)
+      degree_input = input[0...degree_location].strip
+      input = input[degree_location+1..-1].strip
+      degrees = Float(degree_input)
+    end
+
+    if minute_location = input.index(/[′\']/)
+      minute_input = input[0...minute_location].strip
+      input = input[minute_location+1..-1].strip
+      minutes = Float(minute_input)
+    end
+
+    if second_location = input.index(/[″\"]/)
+      second_input = input[0...second_location].strip
+      input = input[second_location+1..-1].strip
+      seconds = Float(second_input)
+    end
+
+    decimal_input = degrees + minutes/60 + seconds/3600
+
+    return (convert_to_negative ? -1 : 1) * decimal_input
+  end
+
+  def is_number?(val)
+    begin
+      Float(val)
+      return true
+    rescue
+      return false
+    end
+  end
+
+  def basic_char_regexp
+    Regexp.new("[" + COORDINATE_CHARS + "]")
+  end
+
+  def valid_char_regexp(additional_chars = [])
+    Regexp.new("[" + COORDINATE_CHARS + additional_chars.join + ", ]")
+  end
+
+  def valid_end_char_regexp(additional_chars = [])
+    Regexp.new("[" + COORDINATE_CHARS + additional_chars.join + "$]")
+  end
+end

data/lib/latitude/version.rb

@@ -1,3 +1,3 @@
 module Latitude
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/latitude/vincenty.rb

@@ -44,8 +44,8 @@ private
 
   def iterative_solver(phi_1, lambda_1, phi_2, lambda_2, a, b, f)
     l = lambda_2 - lambda_1
-    sin_u1, cos_u1, tan_u1 = get_trig_trio(phi_1, f)
-    sin_u2, cos_u2, tan_u2 = get_trig_trio(phi_2, f)
+    sin_u1, cos_u1 = get_trig_trio(phi_1, f)
+    sin_u2, cos_u2 = get_trig_trio(phi_2, f)
 
     lam = l
     iterations = 0

data/spec/coordinate_spec.rb

@@ -0,0 +1,170 @@
+#!/bin/env ruby
+# encoding: utf-8
+require 'spec_helper'
+
+describe Coordinate do
+  let(:coordinate) { Coordinate.new(:latitude => 0, :longitude => 0) }
+  let(:blank_coordinate) { Coordinate.new }
+
+  describe "initialization" do
+    it "should initialize with provided parameters" do
+      new_coordinate = Coordinate.new(:latitude => 10,
+                                      :longitude => 20)
+      expect(new_coordinate.latitude).to eq(10)
+      expect(new_coordinate.longitude).to eq(20)
+    end
+  end
+
+  describe "coordinate parsing" do
+    it "should accept a simple string for latitudes and longitudes" do
+      coordinate.latitude = "-10"
+      coordinate.longitude = "10"
+      expect(coordinate.latitude).to eq(-10)
+      expect(coordinate.longitude).to eq(10)
+    end
+
+    it "should accept a decimal string for latitudes and longitudes" do
+      coordinate.latitude = "-10.5"
+      coordinate.longitude = "10.5"
+      expect(coordinate.latitude).to eq(-10.5)
+      expect(coordinate.longitude).to eq(10.5)
+    end
+
+    describe "with cardinal directions" do
+      it "should save the latitude if given N as cardinal direction" do
+        coordinate.latitude = "10.5 N"
+        expect(coordinate.latitude).to eq(10.5)
+      end
+
+      it "should make the latitude negative if given S as a cardinal direction" do
+        coordinate.latitude = "10.5 S"
+        expect(coordinate.latitude).to eq(-10.5)
+      end
+
+      it "should handle spaces around things" do
+        coordinate.latitude = "  10.5   N  "
+        expect(coordinate.latitude).to eq(10.5)
+      end
+
+      it "should throw an exception if given E or W as a direction for latitude" do
+        expect { coordinate.latitude = "10 E" }.to raise_error(ArgumentError)
+        expect { coordinate.latitude = "10 W" }.to raise_error(ArgumentError)
+      end
+
+      it "should save the longitude if given E as a cardinal direction" do
+        coordinate.longitude = "10.5 E"
+        expect(coordinate.longitude).to eq(10.5)
+      end
+
+      it "should make the longitude negative if given W as a cardinal direction" do
+        coordinate.longitude = "10.5 W"
+        expect(coordinate.longitude).to eq(-10.5)
+      end
+
+      it "should throw an exception if given N or S as a direction for longitude" do
+        expect { coordinate.longitude = "10 N" }.to raise_error(ArgumentError)
+        expect { coordinate.longitude = "10 S" }.to raise_error(ArgumentError)
+      end
+    end
+
+    describe "parsing degrees minutes and seconds" do
+      it "should take simple degrees input and set as decimal" do
+        coordinate.latitude = "50°"
+        expect(coordinate.latitude).to eq(50)
+
+        coordinate.longitude = "10.5 °"
+        expect(coordinate.longitude).to eq(10.5)
+      end
+
+      it "should take degrees and minutes" do
+        coordinate.latitude = "50° 0'"
+        expect(coordinate.latitude).to eq(50)
+
+        coordinate.latitude = "50° 0′"
+        expect(coordinate.latitude).to eq(50)
+      end
+
+      it "should convert minutes to 1/60ths of degrees" do
+        coordinate.latitude = "50° 30'"
+        expect(coordinate.latitude).to eq(50.5)
+      end
+
+      it "should take degrees, minutes, and seconds" do
+        coordinate.latitude = "50° 0' 0\""
+        expect(coordinate.latitude).to eq(50)
+
+        coordinate.latitude = "50° 0' 0″"
+        expect(coordinate.latitude).to eq(50)
+      end
+
+      it "should take degrees and seconds" do
+        coordinate.latitude = "50° 0\""
+        expect(coordinate.latitude).to eq(50)
+      end
+
+      it "should convert seconds to 1/60ths of minutes" do
+        coordinate.latitude = "50° 0' 36\""
+        expect(coordinate.latitude).to eq(50.01)
+      end
+    end
+  end
+
+  describe "validation" do
+    it "should be valid if given valid lat and long" do
+      expect(coordinate).to be_valid
+    end
+
+    it "should be invalid unless latitude provided" do
+      blank_coordinate.longitude = 0
+      expect(blank_coordinate).to_not be_valid
+    end
+
+    it "should be invalid unless longitude provided" do
+      blank_coordinate.latitude = 0
+      expect(blank_coordinate).to_not be_valid
+    end
+
+    it "should be invalid unless latitude is between -90 and 90" do
+      coordinate.latitude = -100
+      expect(blank_coordinate).to_not be_valid
+
+      coordinate.latitude = 100
+      expect(blank_coordinate).to_not be_valid
+    end
+
+    it "should be invalid unless longitude is between -180 and 180" do
+      coordinate.longitude = -190
+      expect(blank_coordinate).to_not be_valid
+
+      coordinate.longitude = 190
+      expect(blank_coordinate).to_not be_valid
+    end
+  end
+
+  describe "#great_circle_distance_to" do
+    it "should call the vincenty formulae to calculate the great circle distances" do
+      expect(Vincenty).to receive(:great_circle_distance).with(10, 20, 30, 40)
+      start_coordinate = Coordinate.new(:latitude => 10, :longitude => 20)
+      end_coordinate = Coordinate.new(:latitude => 30, :longitude => 40)
+      start_coordinate.great_circle_distance_to(end_coordinate)
+    end
+  end
+
+  describe "#initial_bearing_to" do
+    it "should call the vincenty formulae to calculate the initial bearing" do
+      expect(Vincenty).to receive(:initial_bearing).with(10, 20, 30, 40)
+      start_coordinate = Coordinate.new(:latitude => 10, :longitude => 20)
+      end_coordinate = Coordinate.new(:latitude => 30, :longitude => 40)
+      start_coordinate.initial_bearing_to(end_coordinate)
+    end
+  end
+
+  describe "#final_bearing_from" do
+    it "should call the vincenty formulae to calculate the final bearing" do
+      expect(Vincenty).to receive(:final_bearing).with(10, 20, 30, 40)
+      start_coordinate = Coordinate.new(:latitude => 10, :longitude => 20)
+      end_coordinate = Coordinate.new(:latitude => 30, :longitude => 40)
+      end_coordinate.final_bearing_from(start_coordinate)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: latitude
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-15 00:00:00.000000000 Z
+date: 2014-06-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -77,8 +77,10 @@ files:
 - Rakefile
 - latitude.gemspec
 - lib/latitude.rb
+- lib/latitude/coordinate.rb
 - lib/latitude/version.rb
 - lib/latitude/vincenty.rb
+- spec/coordinate_spec.rb
 - spec/latitude_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/umtrey/latitude-gem
@@ -107,5 +109,6 @@ signing_key:
 specification_version: 3
 summary: Calculates distances between two geographic coordinates.
 test_files:
+- spec/coordinate_spec.rb
 - spec/latitude_spec.rb
 - spec/spec_helper.rb