kookjr-geodesic 0.0.1 → 1.0.0

data/Changelog

@@ -1,5 +1,11 @@
 = Geodesic Changelog
 
+== Version 1.0.0
+
+* Changed API call, Geodesic.dest_point to Geodesic.dest_position to be more consistent.
+
+* Cleaned up and completed API and README documentation.
+
 == Version 0.0.1
 
 * Initial realease

data/README.rdoc

@@ -7,13 +7,19 @@ Geodesic contains the following features:
 
 * A Position class to encapsulate an Earth position (latitude and longitude)
 
-* A method to calculate the distance between two positions using Haversine formulat
+* A method to calculate the distance between two positions using Haversine formula
 
 * A method to calculate the distance between two positions using the Law of Cosines
 
-* A method to calculate the initial bearing between two points
+* A method to calculate the initial bearing between two positions
 
-* A method to calculate a point a given distance from another point along a bearing
+* A method to calculate a position a given distance from another position along a bearing
+
+All input parameters to these functions are Floats. Longitudes
+are expected to be in the range of -180.0 to 180.0 decimal degrees,
+latitudes in the range of -90.0 to 90.0 decimal degrees and bearings in
+the range of 0.0 to 360.0 (where 0.0 is North). Distances are measured in
+kilometers.
 
 == Installation
 
@@ -28,7 +34,26 @@ Then, install.
 
 == Sample Usage
 
-TBD.
+  require 'rubygems'
+  require 'geodesic'
+
+  fremont    = Geodesic::Position.new(37.549531, -121.998711)
+  farmington = Geodesic::Position.new(37.923482, -121.015263)
+
+  d = Geodesic::dist_haversine(fremont.lat, fremont.lon, farmington.lat, farmington.lon)
+  print "distance from Fremont to Farmington is ", d, " kilometers\n"
+
+  b = Geodesic::bearing(fremont.lat, fremont.lon, farmington.lat, farmington.lon)
+  print "bearing is ", b, " degrees\n"
+
+  p = Geodesic::dest_position(fremont.lat, fremont.lon, b, d + 10)
+  print "10 kilometers beyond farmington is ", p.lat, ", ", p.lon, "\n"
+
+The output is:
+
+  distance from Fremont to Farmington is 95.957632116596 kilometers
+  bearing is 64.0206814526114 degrees
+  10 kilometers beyond farmington is 37.9619800970259, -120.912203460738
 
 == Development
 === Source Repository
@@ -62,4 +87,4 @@ can be found at:
 == License
 
 GNU LGPL, Lesser General Public License version 2.1. For details,
-see file "COPYING.LESSER".
+see file "COPYING.LESSER".

data/lib/geodesic.rb

@@ -19,33 +19,34 @@
 
 # Additions to Float for conversion between various units.
 class Float
-  # convert degrees to radians
+  # Convert decimal degrees to radians. Input range is either -180.0 to 180.0
+  # for longitudes, or -90.0 to 90.0 for latitudes.
   def to_radians
-    self * Math::PI / 180
+    self * Math::PI / 180.0
   end
 
-  # convert radians to degrees (signed)
+  # Convert radians to degrees. Return range is -180.0 to 180.0.
   def to_degrees
     self * 180 / Math::PI
   end
 
-  # convert radians to degrees (as bearing: 0...360)
+  # Convert radians to bearing. Return degrees range 0.0 to 360.0.
   def to_bearing
-    (self.to_degrees()+360) % 360
+    (self.to_degrees()+360.0) % 360.0
   end
 end
 
 # Geodesic is a Ruby library for calculating distance and bearing on
-# the Earth's surface.  Points are defined by longitude and
+# the Earth's surface.  Positions are defined by longitude and
 # latitude. The API uses Float values for all input and returned
 # types. Distances are memasured in kilometers (km).
 module Geodesic
 
-  # Earth's radius in km
-  EARTH_RADIUS = 6371
+  # Earth's radius in kilometers
+  EARTH_RADIUS = 6371.0
 
 
-  # Class to hold the latitude and longitude of a point
+  # Class to hold the latitude and longitude of a position.
   class Position
     attr_accessor :lat
     attr_accessor :lon
@@ -57,8 +58,8 @@ module Geodesic
     end
   end
 
-  # Use Haversine formula to Calculate distance (in km) between two points specified by 
-  # latitude/longitude (in numeric degrees).
+  # Use Haversine formula to Calculate distance (in kilometers) between two positions specified by 
+  # latitude/longitude in numeric degrees of type Float.
   def Geodesic.dist_haversine(lat1, lon1, lat2, lon2)
     dLat = (lat2-lat1).to_radians()
     dLon = (lon2-lon1).to_radians()
@@ -73,8 +74,8 @@ module Geodesic
     return d
   end
 
-  # Use Law of Cosines formula to Calculate distance (in km) between two points specified by 
-  # latitude/longitude (in numeric degrees).
+  # Use Law of Cosines formula to calculate distance (in kilometers) between two positions specified by 
+  # latitude/longitude in numeric degrees of type Float.
   def Geodesic.dist_cosine_law(lat1, lon1, lat2, lon2)
     d = Math::acos(Math::sin(lat1.to_radians())*Math::sin(lat2.to_radians()) +
                    Math::cos(lat1.to_radians())*Math::cos(lat2.to_radians()) *
@@ -82,8 +83,9 @@ module Geodesic
     return d
   end
 
-  # Calculate (initial) bearing between two points (0 to 360)
-  #   see http:#williams.best.vwh.net/avform.htm#Crs
+  # Calculate (initial) bearing in degrees between two positions. Return
+  # range is 0.0 to 360.0. Latitudes and longitudes are of type Float.
+  #   see http://williams.best.vwh.net/avform.htm#Crs
   def Geodesic.bearing(lat1, lon1, lat2, lon2)
     lat1 = lat1.to_radians()
     lat2 = lat2.to_radians()
@@ -95,9 +97,11 @@ module Geodesic
     return Math::atan2(y, x).to_bearing()
   end
 
-  # Calculate destination point given start point, initial bearing (deg) and distance (km)
-  #   see http:#williams.best.vwh.net/avform.htm#LL
-  def Geodesic.dest_point(lat1, lon1, brng, d)
+  # Calculate destination position given start position, initial bearing (degrees 0.0 to 
+  # 360.0) and distance (kilometers).
+  # All values of type Float. Return a Position class or nil.
+  #   see http://williams.best.vwh.net/avform.htm#LL
+  def Geodesic.dest_position(lat1, lon1, brng, d)
     lat1 = lat1.to_radians()
     lon1 = lon1.to_radians()
     brng = brng.to_radians()
@@ -106,7 +110,7 @@ module Geodesic
                       Math::cos(lat1)*Math::sin(d/EARTH_RADIUS)*Math::cos(brng) )
     lon2 = lon1 + Math::atan2(Math::sin(brng)*Math::sin(d/EARTH_RADIUS)*Math::cos(lat1), 
                               Math::cos(d/EARTH_RADIUS)-Math::sin(lat1)*Math::sin(lat2))
-    lon2 = (lon2+Math::PI)%(2*Math::PI) - Math::PI  # normalise to -180...+180
+    lon2 = (lon2+Math::PI)%(2*Math::PI) - Math::PI  # normalise to +/-radians
 
     return nil if lat2.nan? || lon2.nan?
     return Position.new(lat2.to_degrees(), lon2.to_degrees())

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: kookjr-geodesic
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors: 
 - Mathew Cucuzella
@@ -9,11 +9,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-08 00:00:00 -07:00
+date: 2009-05-16 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
-description: Geodesic is a Ruby library for calculating distance and bearing on the Earth's surface.  Points are defined by longitude and latitude. The API uses Float values for all input and returned types. Distances are memasured in kilometers (km).
+description: Geodesic is a Ruby library for calculating distance and bearing on the Earth's surface.  Positions are defined by longitude and latitude. The API uses Float values for all input and returned types. Distances are memasured in kilometers (km).
 email: kookjr@gmail.com
 executables: []