h1. Geo calculations

Geo Calculation library. Useful functions to add to your geo arsenal, fx when designing your own Geo library. 

h2. Status update (June 14, 2011)

Extracted GeoUnits and GeoPoint into separate gems: 

* "geo_units":https://github.com/kristianmandrup/geo_units 
* "geo_point":https://github.com/kristianmandrup/geo_point

h2. Install

@require 'geo_calc'@

h3. Gemfile

Insert in your Gemfile:

@gem 'geo_calc'@

From command line, run bundler

@$ bundle@

h2. Objective

The objective of this library is to act as a base for other geo libraries. 

The geo calculation API only requires that the point objects used, have a #lat and #lon method, which return the latitude and longitude respectively.
The lat/lng should each be a Numeric (ie. Float or Fixnum) within respective 'geo ranges': (-90 to 90, -180 to 180).

h3. Shortest distance

Calculate *distance in kms between points p1 and p2*

<pre>  
  dist = p1.distance_to(p2) # in km
</pre>

h3. Initial bearing (direction)

Calculate the initial bearing (direction in degrees which p1 points at p2)

<pre>
  brng = p1.bearing_to(p2) # in degrees clockwise from north
</pre>

h3. Final bearing (direction)

Calculate the final bearing (direction in degrees) between p1 -> p2)

<pre>
  final_brng = p1.final_bearing_to(p2) # final bearing in degrees from north  
</pre>

h3. Midpoint

Find the midpoint between points p1 and p2
  
<pre>
  mid = p1.midpoint_to point(p2) # midpoint between p1 and p2
</pre>

h3. Destination point

Find the destination point from walking a distance in a given bearing (direction in degrees from p1)
  
<pre>
  dest = p1.destination_point bearing, dist # Bearing in degrees, Distance in km  
</pre>

h3. Intersection point

Find the intersection point pcross between a path from p1 and a path from p2
  
<pre>
  pcross = GeoPoint.intersection p1, brng1, p2, brng2 # intersection between two paths
</pre>  

h2. Rhumb lines
  
<pre>
  p1.rhumb_distance_to(p2)
</pre>  
  
<pre>
  p1.bearing_to(p2)
</pre>  

<pre>
  p1.rhumb_destination_point(brng, dist)  
</pre>    

h2. Core Extensions

The library also extends core Ruby classes with geo related functions (see _core_ext_spec.rb_)

h3. Radians to degrees

<pre>
  (6.28).to_deg # almost 360 deg  
</pre>

h3. Degrees to radians

<pre>
  (360).to_deg # about 6.28, or 2 * PI
</pre>

h3. DMS to degrees 

Convert (degrees-minutes-seconds) to degrees (Float)

<pre>
  "24 10 02 E".parse_dms(:dm, 2) # dms format and precision 
</pre>

h3. Degrees to DMS

Convert degrees into to DMS format

<pre>
  53.2.to_dms # can also take dms format and precision args
</pre>

And many more...

h2. Javascript

The libary also comes wih a javascript file with the same functionality. 

See _js/geo_calc.js_ in the _/lib_ folder

h2. Contributing to geo_calc
 
* 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.

h2. Copyright

Copyright (c) 2011 Kristian Mandrup. See LICENSE.txt for
further details.