geo_vectors 0.5.0

data/lib/geo_vectors/vector_parser.rb

@@ -0,0 +1,54 @@
+class GeoVector
+  module Parser
+    module ClassMethods
+      def create_vector *args
+        first_arg = args[0]             
+        first_arg.any_kind_of?(GeoVector, GeoVectors) ? first_arg : parse_vector(*args)
+      end
+
+      def parse_vector *args
+        res = [:point, :bearing, :direction, :multiple].map {|type| send parser(type), *args }.compact.first
+        raise ArgumentError, "No GeoVector could be created from arguments: #{args}" if !res
+        res
+      end
+
+      def parser type
+        "parse_#{type}_vector"
+      end
+
+      def parse_multiple_vector *args 
+        begin
+          GeoVectors.new *args
+        rescue
+          nil
+        end
+      end
+
+      def parse_point_vector *args 
+        begin
+          PointVector.new *args
+        rescue
+          nil
+        end
+      end
+
+      def parse_bearing_vector *args 
+        begin
+          BearingVector.new *args
+        rescue
+          nil
+        end
+      end
+      
+      def parse_direction_vector *args 
+        begin
+          DirectionVector.new *args
+        rescue
+          nil
+        end
+      end      
+    end
+    
+    extend ClassMethods
+  end
+end

data/spec/geo_vectors/API proposal guide.txt

@@ -0,0 +1,142 @@
+h2. Intro
+
+A GeoVector can be any of:
+
+1) *bearing vector* - bearing (direction in degrees) and a distance
+2) *direction vector* - direction (:N, :NW, :NE, :S, :SE, :SW, :E, :W) and a distance
+3) *point vector* - number of degrees due east/west (+ or -) and a distance due north/south (+ or -)
+
+Note that a direction vector is always converted to a bearing vector when added to a point
+
+A GeoVector can be applied to a GeoPoint (see geo_calc) or to another GeoVector.
+When multiple vectors are added together, the sum becomes a GeoVectors object.
+If a GeoVectors object is applied, the vectors are simply applied in turn.
+
+h2. Quick start (Usage guide)
+
+The following gives a quick overview for how to use the GeoVector API.
+
+_Note: This is suggested functionality._
+
+I plan to use my recently published _geo_calc_ gem as the base for the functionality described here.
+I need a major cleanup up of the current code...
+
+h3. Addition
+
+Vectors can be added to form a new Vector, using the simple formula vec = v1 + v2 = (v1.x + v2.y, v1.x + v2.y)
+
+h3. Vector on Vector addition
+
+If both vectors are point vectors, the result is simply a new point vector
+
+<pre>
+  v1 = [1, 3].vector
+  v2 = [-2, 2].vector
+  vec = v1 + v2
+  vec.unit.should == :degrees
+  vec.lat.should == -1
+  vec.lng.should == 5
+
+  # alternative addition operators
+  vec = v1 << v2  
+</pre>  
+
+h3. Vector subtraction
+
+<pre>
+  v1 = [1, 3].vector
+  v2 = [2, 1].vector
+  vec = v1 - v2 # here v2 inversed (scaled by -1) and then added 
+  vec.lat.should == -1
+  vec.lng.should == 2
+</pre>
+
+h3. Vector scaling
+
+<pre>
+  v1 = [1, 3].vector
+  vec = v1 * 2
+  vec.lat.should == 2
+  vec.lng.should == 6
+</pre>
+
+Scale a bearing vector
+
+<pre>
+  v1 = [32, 3.km].vector
+  vec = v1 * 2
+  vec.bearing.should == 32
+  vec.distance.should == 6.km
+</pre>
+
+
+Using division operator / for inverse scaling
+
+<pre>
+  v1 = [4, 2].vector
+  vec = v1 / 2
+  vec.lat.should == 2
+  vec.lng.should == 1
+</pre>
+
+h3. GeoVectors 
+
+Adding a point Vector to a bearing Vector
+
+If the vectors are of different type, a GeoVectors object is created 
+containing both vectors. A GeoVectors is a composite vector.
+
+<pre>
+  p1 = [1, -1]
+
+  v1 = [1, 3].vector # point Vector
+
+  # 32 deg bearing, 2.km
+  v2 = [32, 2.km].vector # bearing Vector
+  v2.bearing.should == 32
+  v2.distance.should == 2.km
+
+  vec = v1 + v2 # create a GeoVectors object
+  vec.should be_a(GeoVectors)
+  vec.vectors.size.should == 2 # should contain 2 vectors
+
+  # Adding more vectors to the GeoVectors object
+  vec.vectors << v3
+  vec << v4
+  
+  p2 = p1 + vec # Add GeoVectors to the point
+</pre>
+
+h3. Vector on Point addition
+
+Add a point Vector to a GeoPoint
+
+<pre>
+  p1 = [1, 3].geo_point
+  vec = [-2, 2].vector
+  p2 = p1 + vec
+  p2.lat.should == -1
+  p2.lng.should == 5  
+</pre>
+
+Add an inverse point Vector (subtract) to a GeoPoint
+
+<pre>
+  p1 = [1, 3].geo_point
+  vec = [2, 1].vector
+  p2 = p1 - vec
+  p2.lat.should == -1
+  p2.lng.should == 2
+</pre>
+
+Add a bearing Vector to a GeoPoint
+
+<pre>
+  p1 = [1, 3].geo_point
+
+  # 32 deg bearing, 2.km
+  vec = [32, 2.km].vector 
+
+  # use #destination_point from 'geo_calc' project
+  p2 = p1 + vec
+</pre>

data/spec/geo_vectors/bearing_vector/add_vector_spec.rb

@@ -0,0 +1,30 @@
+require 'spec_helper'
+
+describe BearingVector do
+  context 'Bearing Vector: 2 km at 32 degrees and a GeoPoint at (1,3)' do
+    let(:vector) { BearingVector.new 32, 2.km }
+    let(:point)  { GeoPoint.new 1, 3 }
+
+    describe '#+' do
+      it 'should add Bearing Vector to point' do      
+        p2 = point + vector
+        p2.should_not == point
+      end
+    end
+  
+    describe '#add (alias to +)' do
+      it 'should add Bearing Vector to point' do      
+        p2 = point.add(vector)
+        p2.should_not == point
+      end
+    end    
+
+    describe '#add! changes point' do
+      it 'should add Bearing Vector directly to point' do      
+        old_point = point.dup
+        point.add!(vector)
+        old_point.lat.should_not == point.lat
+      end
+    end    
+  end
+end

data/spec/geo_vectors/bearing_vector/random_spec.rb

@@ -0,0 +1,18 @@
+require 'spec_helper'
+
+describe GeoVector do
+  describe 'Random module' do
+    context 'Bearing vector 4.km at 52 deg' do
+      describe '#random_vector' do      
+        let (:vec) { vec = [4.km, 52].b_vector }
+        
+        it 'should return a random vector of up to 4.kms with any bearing' do
+          rvec = vec.random_vector
+          rvec.distance.in_kms.should be_between(0, 4)
+          puts "random bearing: #{rvec.bearing}"
+          rvec.bearing.should be_between(0, 360)
+        end
+      end
+    end
+  end
+end

data/spec/geo_vectors/bearing_vector_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+
+describe BearingVector do
+  describe '#initialize' do
+    it 'should create Bearing Vector from distance and degrees' do
+      v = BearingVector.new 2.km, 32
+      v.should be_a BearingVector
+      v.distance.should == 2.km
+      v.bearing.should == 32      
+    end      
+
+    it 'should create Bearing Vector from degrees and distance' do
+      v = BearingVector.new 32, 2.km
+      v.distance.should == 2.km
+      v.bearing.should == 32      
+    end      
+
+    it 'should create Bearing Vector from 2 numbers, assuming first arg is distance in :kms' do
+      v = BearingVector.new 2, 32
+      v.distance.should == 2.km
+      v.bearing.should == 32      
+    end      
+
+    it 'should NOT create Bearing Vector from 1 argument' do
+      lambda {BearingVector.new 2}.should raise_error
+    end      
+  end
+
+  describe '#to_s' do
+    it 'should print distance and bearing' do
+      BearingVector.new(2, 32).to_s.should match /distance: 2 kms, bearing: 32 degrees/      
+    end    
+  end      
+end

data/spec/geo_vectors/direction_vector/add_vector_spec.rb

@@ -0,0 +1,30 @@
+require 'spec_helper'
+
+describe DirectionVector do
+  context 'Direction Vector: 2 km North and a GeoPoint at (1,3)' do
+    let(:vector) { DirectionVector.new 2.km, :north }
+    let(:point)  { GeoPoint.new 1, 3 }
+
+    describe '#+' do
+      it 'should add Direction Vector to point' do      
+        p2 = point + vector
+        p2.should_not == point
+      end
+    end
+  
+    describe '#add (alias to +)' do
+      it 'should add Direction Vector to point' do      
+        p2 = point.add(vector)
+        p2.should_not == point
+      end
+    end    
+
+    describe '#add! changes point' do
+      it 'should add Direction Vector directly to point' do      
+        old_point = point.dup
+        point.add!(vector)
+        old_point.lat.should_not == point.lat
+      end
+    end    
+  end
+end

data/spec/geo_vectors/direction_vector/random_spec.rb

@@ -0,0 +1,16 @@
+require 'spec_helper'
+
+describe GeoVector do
+  describe 'Random module' do
+    context 'Direction vector 4.km North' do
+      describe '#random_vector' do      
+        let (:vec) { vec = [4.km, :north].d_vector }
+        
+        it 'should return a random vector of up to 4.kms in any direction' do
+          rvec = vec.random_vector
+          rvec.distance.in_kms.should be_between(0, 4)
+        end
+      end
+    end
+  end
+end

data/spec/geo_vectors/direction_vector_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+
+describe DirectionVector do
+  describe '#initialize' do
+    it 'should create Direction Vector from distance and direction' do
+      v = DirectionVector.new 2.km, :north
+      v.distance.should == 2.km
+      v.direction.should == :N
+    end      
+
+    it 'should create Direction Vector from degrees and distance' do
+      v = DirectionVector.new :north, 2.km
+      v.distance.should == 2.km
+      v.direction.should == :N
+    end      
+
+    it 'should create Direction Vector from number and direction, assuming number is distance in :kms' do
+      v = DirectionVector.new 2, :north
+      v.distance.should == 2.km
+      v.direction.should == :N
+    end      
+
+    it 'should NOT create Direction Vector from 1 argument' do
+      lambda {DirectionVector.new 1}.should raise_error
+    end      
+  end
+end

data/spec/geo_vectors/geo_vectors_spec.rb

@@ -0,0 +1,108 @@
+require 'spec_helper'
+
+describe GeoVectors do
+  context 'an GeoVectors containing a PointVector v1, and a BearingVector v2' do
+    let (:v1) { [1, 2].vector }
+    let (:v2) { [30, 4.km].b_vector }
+    let (:vecs) { GeoVectors.new v1, v2 }
+    let (:point) { [3, 4].geo_point }
+
+    describe '#vectors' do
+      it 'should return the instances of GeoVector added' do
+        vecs.vectors.first.should == v1
+        vecs.vectors.last.should == v2
+      end
+    end
+
+    describe '#to_s' do
+      it 'should return vector seperated with ;' do
+        vecs.to_s.should match /;/
+      end
+    end
+
+    describe '#each' do
+      it 'should return each vector' do
+        vecs.each do |v| 
+          v.should be_a GeoVector
+        end
+      end
+    end
+
+    describe '#map' do
+      it 'should return each vector' do
+        x = vecs.vectors.map do |v| 
+          v.to_s
+        end.join('#')        
+        x.should match /#/
+      end
+    end
+
+
+    describe '#directions' do
+      it 'should return directions of all vectors' do
+        dirs = vecs.directions
+        dirs.should include(30)
+        dirs.size.should == 2
+      end
+    end
+
+    describe '#distances' do
+      it 'should return distances of all vectors' do
+        dists = vecs.distances
+        dists.should include(4.km)
+        dists.size.should == 2
+      end
+    end
+
+    describe '#scale' do
+      it 'should return distances of all vectors' do
+        big_vecs = vecs.scale 2
+        big_vecs.vectors.first.lat.should == 2
+      end
+    end
+
+    describe '#scale' do
+      it 'should return distances of all vectors' do
+        vecs2 = vecs.dup
+        vecs2.reduce 2
+        vecs2.vectors.first.lat.should == 0.5
+      end
+    end
+
+
+    describe 'Addition' do    
+      describe '#add' do
+        it 'should add vector to a point' do
+          p2 = point.add vecs
+          p2.lat.should > point.lat
+        end
+      end
+
+      describe '#+' do
+        it 'should add vector to a point' do
+          old_lat = point.lat
+          p2 = point + vecs
+          p2.lat.should > point.lat
+        end
+      end
+    end
+  
+    describe 'Subtraction' do
+      describe '#sub' do
+        it 'should subtract vector from point' do
+          p2 = point.sub(vecs)
+          p2.lat.should < point.lat
+        end
+      end
+  
+      describe '#-' do
+        it 'should subtract vector from point' do
+          old_lat = point.lat
+          p2 = point - vecs
+          p2.lat.should < point.lat
+        end
+      end
+    end
+  end
+end
+