Geo Vectors

Vector classes and operations for performing various Geo calculations.

require 'geo_vectors_

Insert into Gemfile of the app:

gem 'geo_vectors'

Then run bundler from command line to bundle the gem with the app:

$ bundle

See the Changelog for recent changes and updates!

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 -)

A GeoVector can be applied to a GeoPoint (see geo_calc) or to another GeoVector.

When multiple vectors are added (or grouped) together, the sum becomes a GeoVectors object except when PointVectors are added the result is a new PointVector.
When a GeoVectors object is applied (added or subtracted) to a GeoPoint instance, all the vectors are applied in succession to the geo point.
See the specs for more details on the API for a GeoVectors object.

The following gives a quick overview on how to use the GeoVectors API.

Note that using [1, 2].vector and similar macros (core Ruby extensions), requires that you include the optional macros:

require 'geo_vectors/macros'

Vector on Vector addition

If both vectors are point vectors, the result is simply a new point vector.
Point vectors can be added to form a new Point vector, using the simple formula

vec = v1 + v2 = (v1.x + v2.y, v1.x + v2.y)

  require 'geo_vectors'
  require 'geo_vectors/macros'  
  
  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  

Vector subtraction

  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

Vector scaling

  v1 = [1, 3].vector
  vec = v1 * 2
  vec.lat.should == 2
  vec.lng.should == 6

Other scale methods: #scale, #scale!

Inverse scaling (reduction)

  v1 = [4, 2].vector
  vec = v1 / 2
  vec.lat.should == 2
  vec.lng.should == 1

You can also call #reduce to get the same effect

Vector scaling

  v1 = [3.km, 32].vector
  vec = v1 * 2
  vec.bearing.should == 32
  vec.distance.should == 6.km

Generate random vector

  v1 = [3.km, 32].vector
  random_vec = v1.random_vector
  random_vec.distance.number.should be_between(0, 3)

This can be used to generate a random point within a circle (i.e radius of a point).

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.

  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

Add a Vector to a GeoPoint

  p1 = [1, 3].geo_point
  vec = [-2, 2].vector
  p2 = p1 + vec
  p2.lat.should == -1
  p2.lng.should == 5  

Other subtract methods: #add, #add!

  p1 = [1, 3].geo_point
  p1.add!(-2, 2)
  p1.lat.should == -1
  p1.lng.should == 5  

Subtract a Vector from a GeoPoint

  p1 = [1, 3].geo_point
  vec = [2, 1].vector
  p2 = p1 - vec
  p2.lat.should == -1
  p2.lng.should == 2

Subtract a bearing Vector from a GeoPoint

  p1 = [1, 3].geo_point

  # 32 deg bearing, 2.km
  vec = [32, 2.km].vector 
  p2 = p1 - vec

Other subtract methods: #sub, #sub!

  p1 = [1, 3].geo_point
  p1.sub!(2.km, 32)
  p1.lat.should == -1
  p1.lng.should == 5  

• Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet
• Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it
• Fork the project
• Start a feature/bugfix branch
• Commit and push until you are happy with your contribution
• Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright © 2011 Kristian Mandrup. See LICENSE.txt for
further details.