gis-distance 1.0.0

data/CHANGES

@@ -0,0 +1,2 @@
+== 0.1.0 - ???
+* Initial release

data/MANIFEST

@@ -0,0 +1,7 @@
+* CHANGES
+* MANIFEST
+* README
+* Rakefile
+* gis-distance.gemspec
+* lib/gis/distance.rb
+* test/test_gis_distance.rb

data/README

@@ -0,0 +1,22 @@
+== Description
+The gis-distance library allows you to calculate geographic distance between
+two points using the formula of your choice.
+
+== Installation
+gem install gis-distance
+
+== Synopsis
+require 'gis/distance'
+
+# New York to Los Angeles
+gis = GIS::Distance.new(40.47, 73.58, 34.3, 118.15)
+
+p gis.distance    # Kilometers
+p gis.distance.mi # Miles 
+
+== License
+Artistic 2.0
+
+== Authors
+* Daniel Berger
+* Ardith Faulkner

data/Rakefile

@@ -0,0 +1,27 @@
+require 'rake'
+require 'rake/testtask'
+include Config
+
+desc "Install the gis-distance library"
+task :install_lib do
+   dest = File.join(CONFIG['sitelibdir'], 'gis')
+   Dir.mkdir(dest) unless File.exists? dest
+   cp 'lib/gis/distance.rb', dest, :verbose => true
+end
+
+desc 'Build the gis-distance gem'
+task :gem do
+   spec = eval(IO.read('gis-distance.gemspec'))
+   Gem::Builder.new(spec).build
+end
+
+desc 'Install the gis-distance library as a gem'
+task :install_gem => [:gem] do
+   file = Dir["*.gem"].first
+   sh "gem install #{file}"
+end
+
+Rake::TestTask.new do |t|
+   t.warning = true
+   t.verbose = true
+end

data/gis-distance.gemspec

@@ -0,0 +1,22 @@
+require 'rubygems'
+
+Gem::Specification.new do |gem|
+   gem.name        = 'gis-distance'
+   gem.version     = '1.0.0' 
+   gem.authors     = ['Daniel J. Berger', 'Ardith Faulkner']
+   gem.license     = 'Artistic 2.0'
+   gem.description = 'Calculate the distance between 2 points on Earth'
+   gem.email       = 'djberg96@gmail.com'
+   gem.files       = Dir['**/*'].reject{ |f| f.include?('CVS') }
+   gem.test_files  = ['test/test_gis_distance.rb']
+   gem.has_rdoc    = true
+   gem.homepage    = 'http://github.com/djberg96/gis-distance'
+
+   gem.extra_rdoc_files  = ['README', 'CHANGES', 'MANIFEST']
+
+   gem.summary = <<-EOF
+      The gis-distance library provides a simple interface for
+      calculating the distance between two points on Earth using
+      latitude and longitude.
+   EOF
+end

data/lib/gis/distance.rb

@@ -0,0 +1,135 @@
+# The GIS module serves as a namespace only.
+module GIS
+   # The Distance class encapsulates methods related to geographic distance.
+   class Distance
+      # Error raised if latitude or longitude values are invalid.
+      class Error < StandardError; end
+
+      # The version of the gis-distance library
+      VERSION = '1.0.0'
+
+      # Create a new GIS::Distance object using the two sets of coordinates
+      # that are provided.
+      #
+      # If invalid coordinates are provided a GIS::Distance::Error is raised.
+      #
+      def initialize(latitude1, longitude1, latitude2, longitude2)
+         validate(latitude1, longitude1, latitude2, longitude2)
+
+         @latitude1  = latitude1
+         @longitude1 = longitude1
+         @latitude2  = latitude2
+         @longitude2 = longitude2
+
+         @radius   = 6367.45
+         @formula  = 'haversine'
+         @distance = nil
+      end
+
+      # Returns the radius of the Earth in kilometers. The default is 6367.45.
+      #
+      def radius
+         @radius
+      end
+
+      # Sets the radius of the Earth in kilometers. This is variable because
+      # the Earth is not perfectly spherical, and you may wish to adjust it.
+      #
+      # However, the possible range of values is limited from 6357.0 to 6378.0.
+      # If a value outside of this range is provided a GIS::Distance::Error
+      # is raised.
+      #
+      # The default value is 6367.45.
+      #
+      # See http://en.wikipedia.org/wiki/Earth_radius for more information.
+      #
+      def radius=(kms)
+         if kms < 6357.0 || kms > 6378.0
+            raise Error, "Proposed radius '#{kms}' is out of range" 
+         end
+         @radius = kms
+      end
+
+      # Returns the formula used to calculate the distance. The default formula
+      # is 'haversine'.
+      #--
+      # See http://en.wikipedia.org/wiki/Haversine_formula for details.
+      def formula
+         @formula
+      end
+
+      # Sets the formula to be used internally for calculating the distance.
+      # The default is 'haversine'.
+      #
+      # If an unsupported formula is provided a GIS::Distance::Error is raised.
+      #
+      def formula=(formula)
+         case formula.to_s.downcase
+            when 'haversine'
+               @formula = 'haversine'
+         else
+            raise Error, "Formula '#{formula}' not supported"
+         end
+      end
+
+      # Returns the distance (in kilometers) between the two coordinates
+      # provided in the constructor.
+      #
+      def distance
+         @distance =
+         case @formula.to_s.downcase
+            when 'haversine'
+               haversine_formula
+         end
+      end
+
+      private
+
+      # Validate the latitude and longitude values. Latitudes must be between
+      # 90.0 and -90.0 while longitudes must be between 180.0 and -180.0.
+      #
+      def validate(lat1, lon1, lat2, lon2)
+         [lat1, lat2].each{ |lat|
+            if lat > 90 || lat < -90
+               msg = "Latitude '#{lat}' is invalid - must be between -90 and 90"
+               raise Error, msg
+            end
+         }
+
+         [lon1, lon2].each{ |lon|
+            if lon > 180 || lon < -180
+               msg = "Longitude '#{lon}' is invalid - must be between -180 and 180"
+               raise Error, msg
+            end
+         }
+      end
+
+      # See http://en.wikipedia.org/wiki/Haversine_formula
+      #
+      def haversine_formula
+         lat1 = @latitude1  * Math::PI / 180
+         lon1 = @longitude1 * Math::PI / 180
+         lat2 = @latitude2  * Math::PI / 180
+         lon2 = @longitude2 * Math::PI / 180
+
+         dlat = lat2 - lat1
+         dlon = lon2 - lon1
+
+         a = ((Math.sin(dlat/2))**2) + (Math.cos(lat1) * Math.cos(lat2) * (Math.sin(dlon/2)) ** 2)
+         c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a))
+
+         @radius * c
+      end
+
+      # Add a custom method to the base Float class if it isn't already defined.
+      class ::Float
+         unless self.respond_to?(:mi)
+            # Convert miles to kilometers.
+            def mi
+               self * 0.621371192
+            end
+         end
+      end
+   end
+end
+

data/test/test_gis_distance.rb

@@ -0,0 +1,98 @@
+require 'test/unit'
+require 'gis/distance'
+
+class TC_GIS_Distance < Test::Unit::TestCase
+   def setup
+      @gis = GIS::Distance.new(40.47, 73.58, 34.3, 118.15)
+   end
+
+   def test_version
+      assert_equal('1.0.0', GIS::Distance::VERSION)
+   end
+
+   def test_distance_basic_functionality
+      assert_respond_to(@gis, :distance)
+      assert_nothing_raised{ @gis.distance }
+      assert_kind_of(Float, @gis.distance)
+   end
+
+   def test_distance
+      assert_in_delta(0.01, 3952.39, @gis.distance)
+      assert_equal(0.0, GIS::Distance.new(40.47, 73.58, 40.47, 73.58).distance)
+   end
+
+   def test_distance_expected_argument_errors
+      assert_raise(ArgumentError){ GIS::Distance.new }
+      assert_raise(ArgumentError){ GIS::Distance.new(40.47) }
+      assert_raise(ArgumentError){ GIS::Distance.new(40.47, 73.58) }
+      assert_raise(ArgumentError){ GIS::Distance.new(40.47, 73.58, 34.3) }
+   end
+
+   def test_distance_expected_range_errors
+      assert_raise(GIS::Distance::Error){ GIS::Distance.new(91.0, 100.0, 45.0, 45.0) }
+      assert_raise(GIS::Distance::Error){ GIS::Distance.new(90.0, 190.0, 45.0, 45.0) }
+   end
+
+   def test_radius_basic_functionality
+      assert_respond_to(@gis, :radius)
+      assert_nothing_raised{ @gis.radius }
+      assert_kind_of(Float, @gis.radius)
+   end
+
+   def test_default_radius
+      assert_equal(6367.45, @gis.radius)
+   end
+
+   def test_radius_expected_errors
+      assert_raise(ArgumentError){ @gis.radius(1) }
+   end
+
+   def test_radius_setter_basic_functionality
+      assert_respond_to(@gis, :radius=)
+      assert_nothing_raised{ @gis.radius = 6368.0 }
+      assert_equal(6368.0, @gis.radius)
+   end
+
+   def test_radius_setter_expected_errors
+      assert_raise(GIS::Distance::Error){ @gis.radius = 6200 }
+      assert_raise(GIS::Distance::Error){ @gis.radius = 6400 }
+   end
+
+   def test_formula_basic_functionality
+      assert_respond_to(@gis, :formula)
+      assert_nothing_raised{ @gis.formula }
+      assert_kind_of(String, @gis.formula)
+   end
+
+   def test_formula
+      assert_equal('haversine', @gis.formula)
+   end
+
+   def test_formula_setter_basic_functionality
+      assert_respond_to(@gis, :formula=)
+      assert_nothing_raised{ @gis.formula = 'haversine' }
+   end
+
+   def test_formula_expected_errors
+      assert_raise(ArgumentError){ @gis.formula(1) }
+      assert_raise(GIS::Distance::Error){ @gis.formula = 'foo' }
+   end
+
+   def test_mi_basic_functionality
+      assert_respond_to(@gis.distance, :mi)
+      assert_nothing_raised{ @gis.distance.mi }
+      assert_kind_of(Float, @gis.distance.mi)
+   end
+
+   def test_mi
+      assert(@gis.distance > @gis.distance.mi)
+   end
+
+   def test_mi_expected_errors
+      assert_raise(ArgumentError){ @gis.distance.mi(1) }
+   end
+
+   def teardown
+      @gis = nil
+   end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification 
+name: gis-distance
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Daniel J. Berger
+- Ardith Faulkner
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-10 00:00:00 -06:00
+default_executable: 
+dependencies: []
+
+description: Calculate the distance between 2 points on Earth
+email: djberg96@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- CHANGES
+- MANIFEST
+files: 
+- CHANGES
+- gis-distance.gemspec
+- lib/gis/distance.rb
+- MANIFEST
+- Rakefile
+- README
+- test/test_gis_distance.rb
+has_rdoc: true
+homepage: http://github.com/djberg96/gis-distance
+licenses: 
+- Artistic 2.0
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: The gis-distance library provides a simple interface for calculating the distance between two points on Earth using latitude and longitude.
+test_files: 
+- test/test_gis_distance.rb