Skip to content
Geo calculations in ruby and javascript
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Geo calculations

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

Status update (June 10, 2011)

- Major refactoring splitting into more logical file/modular structure
- Use autoload
- Extract GeoUnits
- Extract Dms with converter
- GeoPoint can now have set :coords_mode which affects how Ruby Core objects such as String and Array are parsed into :lng and :lat.

- The GeoPoint class should be extracted into separate gem, then this geo_calc gem should only have the more generic geo functionality as modules to be included
where needed in other gems!


require 'geo_calc'


Insert in your Gemfile:

gem 'geo_calc'

From command line, run bundler

$ bundle


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

Please take a look at geo vectors which builds on geo calc and provides various vector operations on geo points.
I also have plans to include geo calc in mongoid geo, the geo extension library for Mongoid 2.

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 = 51.5136, -0.0983
  p2 = "14 11 01 N", "-0.0983"
  p3 = 51.5136, "24 10 02 E"

  # a String
  p1 = "51.5136, -0.0983"
  p1 = "51.5136, 24 10 02 E"
  p3 = "51.4778, -0.0015"  
  p1 = "51 12 03 N, 24 10 02 E"

  # an Array
  p2 = [51.5136, -0.0983]
  p2 = [51.5136, "24 10 02 E"]
  p2 = [51.5136, {:lon => 27.3}]

  # a Hash
  p4 = {:lat => 27.3, :lng => "24 10 02 E"}
  p4 = {: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  


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_destination_point(brng, dist)  

Utility methods

These are some of the utility methods you can use on a GeoPoint object

  p1 = 5.1, -7          # 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…


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 © 2011 Kristian Mandrup. See LICENSE.txt for
further details.

Something went wrong with that request. Please try again.