vector_geometry 0.0.1

data/COPYING

@@ -0,0 +1,20 @@
+Copyright (c) 2012 by Andrew Berkeley (andrew.berkeley.is@googlemail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "jeweler", "~> 1.6.4"
+  gem 'rspec', '~> 2.6.0'
+  gem 'rdoc'
+end

data/README.md

@@ -0,0 +1,153 @@
+Vector geometry
+========
+
+Author: Andrew Berkeley (andrew.berkeley.is@googlemail.com)
+
+Introduction
+------------
+This library provides an interface for handling vector geometry in 2- and 3-dimensional space.
+
+The following classes are defined
+
+<table>
+  <tr>
+    <td>Geometry::Vector</td>
+    <td> Basic 2- or 3D vector and operations</td>
+  </tr>
+  <tr>
+    <td>Geometry::GeoVector</td>
+    <td>Subclass of Vector providing additional geometric operations relating to the surface of a spheroid</td>
+  </tr>
+  <tr>
+    <td>Geometry::EarthVector</td>
+    <td>Subclass of GeoVector relating specifically to Earth</td>
+  </tr>
+  <tr>
+    <td>Geometry::Spheroid::Base</td>
+    <td>Create a representation of an arbitrary spheriod for associating with a given instance of GeoVector</td>
+  </tr>
+</table>
+
+For example, calculating the distance between two points on the Earth's surface
+
+```ruby
+  # Instantiate using geographic coordinates.
+  vector_1 = Geometry::EarthVector.from_geographic(80.0,0.0)  #=> <EarthVector [1111.1648732245053, 0.0, 6259.542946575613]>
+  vector_2 = Geometry::EarthVector.from_geographic(80.0,1.0)  #=> <EarthVector [1110.9956374322653, 19.392500986346672, 6259.542946575613]>
+
+  # Distance across 1 degree longitude at latitude of 80 degrees (km)
+  vector_1.great_circle_distance(vector_2)     #=> 19.43475314292549
+```
+
+Or the distance of point from a line described by two points
+```ruby
+  vector_3 = Geometry::EarthVector.from_geographic(75.0,5.0)  #=> <EarthVector [1649.6615168294907, 144.3266813775607, 6138.7656676742445]>
+  
+  vector_3.great_circle_distance_from_arc(vector_1,vector_2)  #=> 567.3634356328112
+ 
+```
+
+Vector
+------
+
+Basic vector operations can be performed as follows.
+
+Initialize a vector.
+
+```ruby
+  # 2D - pass x, y
+  vector = Geometry::Vector.new(15,20)
+
+  # 3D - pass x, y, z
+  vector = Geometry::Vector.new(15,20,4)
+
+  # 2D - pass magnitude and angle 
+  vector = Geometry::Vector.from_polar(25, Math::PI)
+```
+
+Vector attributes.
+
+```ruby
+  vector = Geometry::Vector.new(15,20,4)
+
+  vector.x                  #=> 15
+  vector.y                  #=> 20
+  vector.z                  #=> 4
+
+```
+
+Vector operations.
+
+```ruby
+
+  vector = Geometry::Vector.new(3,4,5)
+
+  # Magnitude
+  vector.magnitude                      #=> 7.0710678118654755
+
+  # Normalize
+  vector.normalize                      #=> <Vector [0.4242640687119285, 0.565685424949238, 0.7071067811865475]>
+
+  vector_1 = Geometry::Vector.new(2,2,1)
+  vector_2 = Geometry::Vector.new(2,3,10)
+
+  # Addition
+  vector_1 + vector_2                   #=> <Vector [4.0, 5.0, 11.0]>
+
+  # Subtraction
+  vector_1 - vector_2                   #=> <Vector [0.0, -1.0, -9.0]>
+
+  # Multiply by scalar value
+  vector_1 * 4                          #=> <Vector [8.0, 8.0, 4.0]>
+
+  # Divide by scalar value
+  vector * 4                            #=> <Vector [0.5, 0.5, 0.25]>
+
+  # Calculate dot product of 2 vectors
+  vector_1.dot(vector_2)                #=> 20.0
+
+  # Calculate cross product of 2 vectors
+  vector_1.cross(vector_2)              #=> <Vector [17.0, -18.0, 2.0]>
+
+  # Calculate angle between 2 vectors (in radians)
+  vector_1.angle(vector_2)              #=> 0.8929110789963546 
+
+```
+
+Compare vectors.
+
+```ruby
+  
+  # Are two vectors parallel or orthogonal?
+  vector_1 = Geometry::Vector.new(10,0,0)
+  vector_2 = Geometry::Vector.new(20,0,0)
+  vector_3 = Geometry::Vector.new(0,10,0)
+
+  vector_1.parallel?(vector_2)          #=> true
+  vector_1.parallel?(vector_3)          #=> false
+
+  vector_1.orthogonal?(vector_2)        #=> false
+  vector_1.orthogonal?(vector_3)        #=> true
+
+  # Are two vectors equal
+  vector_1 == vector_2                  #=> false
+```
+
+Contributing
+------------
+
+If you find a bug or think that you improve on the code, feel free to contribute.
+
+You can:
+
+* Send the author a message ("andrew.berkeley.is@googlemail.com":mailto:andrew.berkeley.is@googlemail.com)
+* Create an issue
+* Fork the project and submit a pull request.
+
+
+License
+-------
+
+© Copyright 2012 Andrew Berkeley.
+
+Licensed under the MIT license (See COPYING file for details)

data/Rakefile

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
+require 'rspec'
+require 'rspec/core/rake_task'
+
+task :default => [:spec]
+
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  # Put spec opts in a file named .rspec in root
+end
+
+require 'jeweler'
+
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "vector_geometry"
+  gem.homepage = "https://github.com/spatchcock/vector_geometry"
+  gem.license = "GNU Affero General Public License"
+  gem.summary = %Q{Cartesian and spherical geometry using vectors}
+  gem.description = %Q{Cartesian and spherical geometry using vectors}
+  gem.email = "andrew.berkeley.is@googlemail.com"
+  gem.authors = ["Andrew Berkeley"]
+  # dependencies defined in Gemfile
+end
+
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rdoc/task'
+RDoc::Task.new do |rd|
+  rd.title = "Vector Geometry"
+  rd.rdoc_dir = 'doc'
+  rd.main = "README"
+  rd.rdoc_files.include("README", "lib/**/*.rb")
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/geometry/geometry.rb

@@ -0,0 +1,47 @@
+module Geometry
+
+  def self.deg_to_rad(deg)
+    deg * Math::PI / 180.0
+  end
+
+  def self.rad_to_deg(rad)
+    (rad * 180.0) / Math::PI 
+  end
+
+  def self.haversine_distance(point_1,point_2,radius, options = {})
+    lat_1 = point_1[0]
+    lng_1 = point_1[1]
+    lat_2 = point_2[0]
+    lng_2 = point_2[1]
+
+    if options[:unit] = :deg
+      lat_1 = deg_to_rad(lat_1)
+      lng_1 = deg_to_rad(lng_1)
+      lat_2 = deg_to_rad(lat_2)
+      lng_2 = deg_to_rad(lng_2)
+    end
+
+    lat_diff = 0.5 * (lat_2 - lat_1);
+    lat_diff = Math.sin(lat_diff);
+    lat_diff = lat_diff * lat_diff;
+
+    lng_diff = 0.5 * (lng_2 - lng_1);
+    lng_diff = Math.sin(lng_diff);
+    lng_diff = lng_diff * lng_diff;
+
+    result = lat_diff;
+    result += Math.cos(lat_1) * Math.cos(lat_2) * lng_diff;
+    result = Math.sqrt(result);
+
+    return radius * 2 * Math.asin(result);
+    
+  end
+
+  def self.pythagorean_distance(point_1, point_2)
+    x = point_2[0] - point_1[0]
+    y = point_2[1] - point_1[1]
+
+    Math.sqrt(x * x + y * y).abs
+  end
+
+end

data/lib/geometry/spheroid/base.rb

@@ -0,0 +1,106 @@
+module Geometry
+
+  module Spheroid
+
+    # Ellipsoid - 3D analogue of an ellipse. Has 3 axis: a,b and c
+    # Spheroid  - Ellipsoid with two equal semi-diameters (a = b)
+    # Sphere    - Ellipsoid with three equal semi-diameters (a = b = c)
+    # Geoid     - 
+
+    # class Ellipsoid
+      
+    #   def initialize(a,b,c)
+    #     @a_radius = a
+    #     @b_radius = b
+    #     @c_radius = c
+    #   end
+
+    #   def volume
+    #     (4.0/3.0) * (Math::PI * a_radius * b_radius * c_radius)
+    #   end
+
+    # end
+
+    class Base
+
+      attr_accessor :polar_radius      # semi-minor axis 
+      attr_accessor :equatorial_radius # semi-major axis
+      attr_accessor :unit
+
+      # Unit is not functional but is simply memoized so that the basis for any calculations 
+      # is clear
+      def initialize(equatorial_radius, polar_radius, unit = :km)
+        @polar_radius      = polar_radius
+        @equatorial_radius = equatorial_radius
+        @unit              = unit
+      end
+
+      def mean_radius
+        # http://en.wikipedia.org/wiki/Earth_radius
+        @mean_radius ||= (@polar_radius + 2 * @equatorial_radius) / 3.0
+      end
+
+      def flattening
+        # http://en.wikipedia.org/wiki/Reference_ellipsoid
+        @flattening ||= (@equatorial_radius - @polar_radius) / @equatorial_radius
+      end
+
+      def inverse_flattening
+        @inverse_flattening ||= 1.0 / flattening
+      end
+
+      def flattening_complement_squared
+        # http://www.mathworks.co.uk/help/aeroblks/geodetictogeocentriclatitude.html
+        @flattening_complement_squared ||= (1.0 - flattening) * (1.0 - flattening)    
+      end
+   
+      def volume
+        @volume ||= (4.0 / 3.0) * (Math::PI * @polar_radius * @equatorial_radius ** 2)
+      end
+
+      # http://en.wikipedia.org/wiki/Earth_radius
+      def radius_at_geodetic_latitude(lat, options = {})
+        lat = Geometry.deg_to_rad(lat) unless options[:unit] == :radians
+
+        numerator   = (@equatorial_radius**2 * Math.cos(lat))**2 + (@polar_radius**2 * Math.sin(lat))**2
+        denominator = (@equatorial_radius    * Math.cos(lat))**2 + (@polar_radius    * Math.sin(lat))**2
+
+        Math.sqrt(numerator/denominator)
+      end
+
+      def geodetic_to_geocentric_latitude(lat, options = {})
+        lat = Geometry.deg_to_rad(lat) unless options[:unit] == :radians
+
+        Math.atan(Math.tan(lat) * flattening_complement_squared)  
+      end
+
+      # Invoke the haversine formula in the context of the spheroid represented by self
+      def haversine_distance(point_1, point_2, options = {})
+        Geometry.haversine_distance(point_1, point_2, mean_radius, options)
+      end
+    
+    end
+
+    Mercury = Geometry::Spheroid::Base.new(2439.7, 2439.7)
+
+    Venus   = Geometry::Spheroid::Base.new(6051.8, 6051.8)
+    
+    Earth   = Geometry::Spheroid::Base.new(6378.1370, 6356.7523)
+    
+    Moon    = Geometry::Spheroid::Base.new(1738.1, 1736.0)
+    
+    Mars    = Geometry::Spheroid::Base.new(3396.2, 3376.2)
+    
+    Jupiter = Geometry::Spheroid::Base.new(71492, 66854)
+    
+    Saturn  = Geometry::Spheroid::Base.new(60268, 54364)
+    
+    Uranus  = Geometry::Spheroid::Base.new(25559, 24973)
+    
+    Neptune = Geometry::Spheroid::Base.new(24764, 24341)
+    
+    Pluto   = Geometry::Spheroid::Base.new(1195, 1195)
+
+  end
+
+end

data/lib/geometry/spheroid/sphere.rb

@@ -0,0 +1,29 @@
+module Geometry
+
+  module Spheroid
+
+    class Sphere < Spheroid::Base
+
+      def initialize(radius, unit = :km)
+        super(radius,radius,unit)
+      end
+
+      def radius
+        @equatorial_radius
+      end
+
+      def diameter
+        @diameter ||= radius * 2.0
+      end
+
+      def circumference
+        @circumference ||= 2.0 * Math::PI * radius
+      end
+
+      def surface_area
+        @surface_area ||= 4.0 * (Math::PI * radius ** 2)
+      end
+
+    end
+  end
+end

data/lib/geometry/vector/earth_vector.rb

@@ -0,0 +1,7 @@
+module Geometry
+
+  class EarthVector < GeoVector
+    @@spheroid = Geometry::Spheroid::Earth
+  end
+
+end

data/lib/geometry/vector/geo_vector.rb

@@ -0,0 +1,234 @@
+module Geometry
+
+  class GeoVector < Vector
+
+    @@spheroid = nil
+
+    def self.from_great_circle_intersection(vector_1,vector_2,vector_3,vector_4)
+      normal_to_great_circle_1 = vector_1.cross_normal(vector_2)
+      normal_to_great_circle_2 = vector_3.cross_normal(vector_4)
+
+      unit_vector = normal_to_great_circle_1.cross_normal(normal_to_great_circle_2)
+
+      if @@spheroid
+        unit_vector.scale(@@spheroid.mean_radius)
+      else
+        unit_vector
+      end
+    end
+
+    # Return a 3-dimensional cartesian vector representing the given latitude and longitude.
+    def self.from_geographic(lat, lng, options = {})
+
+      spheroid = @@spheroid || options[:spheroid]
+      
+      unless options[:unit] == :radians
+        lat = Geometry.deg_to_rad(lat)
+        lng = Geometry.deg_to_rad(lng)
+      end
+
+      # Convert the geodetic latitude to geocentric if required
+      geocentric_latitude = options[:geocentric] ? lat : spheroid.geodetic_to_geocentric_latitude(lat, :unit => :radians)
+      
+      # Find the projection of the point on the equatorial plane.
+      equatorial_plane_projection = Math.cos(geocentric_latitude)
+
+      x = Math.cos(lng) * equatorial_plane_projection
+      y = Math.sin(lng) * equatorial_plane_projection
+      z = Math.sin(geocentric_latitude)
+
+      unit_vector = self.new(x,y,z)
+
+      if options[:unit_vector]
+        unit_vector
+      else
+        raise ArgumentError, "No spheroid defined" unless spheroid
+
+        geodetic_radius = spheroid.radius_at_geodetic_latitude(lat, :unit => :radians)
+        unit_vector.scale(geodetic_radius)
+      end
+    end
+
+    attr_accessor :geodetic_radius
+    attr_accessor :latitude
+    attr_accessor :longitude
+
+    def latitude(options = {})
+      @latitude ||= begin
+        lat = Math.atan2(@z,@x)
+
+        lat = Math::PI - lat if lat > Math::PI/2.0
+        lat = lat.abs        if lat == -0.0
+
+        lat
+      end
+
+      options[:unit] == :radians ? @latitude : Geometry.rad_to_deg(@latitude)
+    end
+
+    def longitude(options = {})
+      @longitude ||= Math.atan2(@y,@x)
+
+      options[:unit] == :deg ? Geometry.rad_to_deg(@longitude) : @longitude
+    end
+
+    def geodetic_radius(spheroid = @@spheroid)
+      @geodetic_radius ||= spheroid.radius_at_geodetic_latitude(latitude)
+    end
+
+    def antipode
+      scale(-1.0)
+    end
+
+    def mean_geodetic_radius(other)
+      (self.geodetic_radius + other.geodetic_radius) / 2.0
+    end
+
+    def great_circle_distance(other, options = {})
+      
+      angular_distance = angle(other) 
+
+      if @@spheroid && !options[:unit_vector]
+        if options[:use_mean_geodetic_radius]
+          return angular_distance * mean_geodetic_radius(other) 
+        else
+          return angular_distance * @@spheroid.mean_radius
+        end
+      else
+        angular_distance
+      end
+    end
+
+    # Calculate the distance of self from a great circle defined by two points.
+    def great_circle_distance_from_great_circle(point_a,point_b)
+
+      # The shortest distance from a great circle is the perpendicular distance. 
+
+      # Find the vector which is normal to the plane described by the (curved) line together
+      # with the origin.
+
+      normal_to_line = point_a.cross_normal(point_b).scale(@@spheroid.mean_radius)
+
+      # The line between self and the normal vector is perpendicular to the line.
+      #
+      # Next, find the intersection between the two lines which represents the shortest distance
+      # from self to the line.
+
+      intersection = GeoVector.from_great_circle_intersection(point_a, point_b, self, normal_to_line)
+
+      # There are actually two valid intersections (which are antipodes of one another) and we have
+      # found one. 
+      #
+      # Return the smallest distance from self to either intersection
+
+      [self.great_circle_distance(intersection), self.great_circle_distance(intersection.antipode)].min      
+    end
+
+    # Calculate the distance of self from a finite line segment defined by two points
+    def great_circle_distance_from_arc(point_a,point_b, options = {})
+
+      # Distance from a line segment is similar to the distance from the infinte line (above)
+      # with a modification.
+      #
+      # The distance from an infinitely long line calculates the shortest distance to an infintitely
+      # long line. This is the perpendicular distance. In the case of the line segment, this perpendicular
+      # may or may not fall on the line segment part of the more general infinte line.
+      # 
+      # If it does, we can keep the perpendicular distance. If not, the shortest distance will be
+      # to either of the two line segments end. Determine which.
+
+      normal_to_line = point_a.cross_normal(point_b).scale(@@spheroid.mean_radius)
+      intersection   = GeoVector.from_great_circle_intersection(point_a, point_b, self, normal_to_line)
+
+      # The point which intersects the two great circles is actually one of two such unique points. We
+      # know both fall on the great circle described by the points but we need to establish whether either
+      # fall on our line segment, i.e. between them. If so, we can take the perpendicular distance from 
+      # the intersection point.
+
+      line_length = point_a.great_circle_distance(point_b, options)
+
+      if line_length >= intersection.great_circle_distance(point_a, options) && 
+         line_length >= intersection.great_circle_distance(point_b, options)
+
+        # The intersection falls on the line segment.
+        # Calculate the perpendicular distance.
+        
+        return self.great_circle_distance(intersection, options)
+
+      elsif line_length >= intersection.antipode.great_circle_distance(point_a, options) && 
+            line_length >= intersection.antipode.great_circle_distance(point_b, options)
+
+        # The *other* intersection falls on the line segment.
+        # Calculate the perpendicular distance.
+
+        return self.great_circle_distance(intersection.antipode, options)
+
+      else
+
+        # Neither intersection falls on the line segment.
+        # Calculate the distance to the closer of the line segment ends.
+
+        return [ self.great_circle_distance(point_a, options), self.great_circle_distance(point_b, options) ].min
+      end
+    end
+
+    # Supports a polyline based on either cartesian or angular coordinates. Specify which using the :basis
+    # option
+    #
+    #  :cartesian => cartesian coordinates (x,y)
+    #
+    # otherwise lat/lng pairs are assumed
+    #
+    def great_circle_distance_from_polyline(polyline, options = {})
+
+      constructor = Proc.new do |vertex|
+        if options[:basis] == :cartesian
+          self.class.new(vertex[0], vertex[1], vertex[2])
+        else
+          self.class.from_geographic(vertex[0], vertex[1], options)          
+        end
+      end
+      
+      # memoize the last processed point as both array and vector objects
+      last_array  = polyline.first
+      last_vector = constructor.call(last_array)
+
+      minimum_distance = 999999999999
+
+      for vertex in polyline[1..-1]  
+
+        next if vertex == last_array  
+
+        start_vector = last_vector
+        end_vector   = constructor.call(vertex)
+
+        this_segment_distance = great_circle_distance_from_arc(start_vector, end_vector, options)
+
+        if(this_segment_distance < minimum_distance)
+          minimum_distance = this_segment_distance
+        end
+
+        last_array  = vertex
+        last_vector = end_vector
+      end
+
+      return minimum_distance
+    end
+
+    # Convert self to a geographic lat/lng pair. 
+    def to_geographic(options = {})
+      [latitude(options), longitude(options)]
+    end
+
+    protected
+      
+    # Return true of point is closer to both points than the points are to each other
+    def within_both_radii?(point_a,point_b)
+      line_length = point_a.great_circle_distance(point_b)
+      self.great_circle_distance(point_a) < line_length && self.great_circle_distance(point_b) < line_length
+    end
+
+  end
+
+end
+