Geo Vectors

Vector classes and operations for performing various Geo calculations.

Install

require 'geo_vectors_

Gemfile

Insert into Gemfile of the app:

gem 'geo_vectors'

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

$ bundle

Status and updates

See the Changelog for recent changes and updates!

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

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

Multiple vectors

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.

Quick start (Usage guide)

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 math

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

Bearing vectors

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

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.


  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

GeoPoint addition

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

GeoPoint subtraction

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

Contributing to Geo Vectors

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.