Geo calculations
Geo Calculation library. Useful functions to add to your geo arsenal, fx when designing your own Geo library.
Install
require 'geo_calc'
Gemfile
Insert in your Gemfile:
gem 'geo_calc'
From command line, run bundler
$ bundle
Quick start (Usage)
First define the points on the globe you want to work with. The GeoPoint initializer is very flexible with regards to the arguments it can handle.
# factory method on core ruby classes
"51 12 03 N, 24 10 02 E".geo_point
[51.5136, -0.0983].geo_point
{:latitude => 27.3, :longitude => "24 10 02 E"}.geo_point
# two arguments
p1 = GeoPoint.new 51.5136, -0.0983
p2 = GeoPoint.new "14 11 01 N", "-0.0983"
p3 = GeoPoint.new 51.5136, "24 10 02 E"
# a String
p1 = GeoPoint.new "51.5136, -0.0983"
p1 = GeoPoint.new "51.5136, 24 10 02 E"
p3 = GeoPoint.new "51.4778, -0.0015"
p1 = GeoPoint.new "51 12 03 N, 24 10 02 E"
# an Array
p2 = GeoPoint.new [51.5136, -0.0983]
p2 = GeoPoint.new [51.5136, "24 10 02 E"]
p2 = GeoPoint.new [51.5136, {:lon => 27.3}]
# a Hash
p4 = GeoPoint.new {:lat => 27.3, :lng => "24 10 02 E"}
p4 = GeoPoint.new {:latitude => 27.3, :longitude => "24 10 02 E"}
Shortes distance
Calculate distance in kms between points p1 and p2
dist = p1.distance_to(p2) # in km
Initial bearing (direction)
Calculate the initial bearing (direction in degrees which p1 points at p2)
brng = p1.bearing_to(p2) # in degrees clockwise from north
Final bearing (direction)
Calculate the final bearing (direction in degrees) between p1 → p2)
final_brng = p1.final_bearing_to(p2) # final bearing in degrees from north
Midpoint
Find the midpoint between points p1 and p2
mid = p1.midpoint_to point(p2) # midpoint between p1 and p2
Destination point
Find the destination point from walking a distance in a given bearing (direction in degrees from p1)
dest = p1.destination_point bearing, dist # Bearing in degrees, Distance in km
Intersection point
Find the intersection point pcross between a path from p1 and a path from p2
pcross = GeoPoint.intersection p1, brng1, p2, brng2 # intersection between two paths
Rhumb lines
p1.rhumb_distance_to(p2)
p1.bearing_to(p2)
p1.rhumb_destination_point(brng, dist)
Utility methods
These are some of the utility methods you can use on a GeoPoint object
p1 = GeoPoint.new 5.1, -7
p1.lat # latitude
p1.lon # longitude
p1.to_arr # array representation of [lat, lng]
p1.reverse_arr! # reverse to_arr to instead return [lng, lat]
p1.normal_arr! # return to normal to_arr functionality: [lat, lng]
p1.to_s # string representation
Core Extensions
The library also extends core Ruby classes with geo related functions (see core_ext_spec.rb)
Radians to degrees
(6.28).to_deg # almost 360 deg
Degrees to radians
(360).to_deg # about 6.28, or 2 * PI
DMS to degrees
Convert (degrees-minutes-seconds) to degrees (Float)
"24 10 02 E".parse_dms(:dm, 2) # dms format and precision
Degrees to DMS
Convert degrees into to DMS format
53.2.to_dms # can also take dms format and precision args
And many more…
Javascript
The libary also comes wih a javascript file with the same functionality.
See js/geo_calc.js in the /lib folder
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.
Copyright
Copyright © 2011 Kristian Mandrup. See LICENSE.txt for further details.