module Geocoder::Calculations

def bearing_between(point1, point2, options = {})


Based on: http://www.movable-type.co.uk/scripts/latlong.html

the same latitude)
is less confusing (returns due east or west when given two points with
(one along a great circle) but the linear method is the default as it
the spherical method is "correct" in that it returns the shortest path
* :method - :linear (default) or :spherical;

ways of specifying the points. Also accepts an options hash:
See Geocoder::Calculations.distance_between for

Returns a number of degrees from due north (clockwise).
Bearing between two points on Earth.
# 
def bearing_between(point1, point2, options = {})
  # set default options
  options[:method] = :linear unless options[:method] == :spherical
  # convert to coordinate arrays
  point1 = extract_coordinates(point1)
  point2 = extract_coordinates(point2)
  # convert degrees to radians
  point1 = to_radians(point1)
  point2 = to_radians(point2)
  # compute deltas
  dlat = point2[0] - point1[0]
  dlon = point2[1] - point1[1]
  case options[:method]
  when :linear
    y = dlon
    x = dlat
  when :spherical
    y = Math.sin(dlon) * Math.cos(point2[0])
    x = Math.cos(point1[0]) * Math.sin(point2[0]) -
        Math.sin(point1[0]) * Math.cos(point2[0]) * Math.cos(dlon)
  end
  bearing = Math.atan2(x,y)
  # Answer is in radians counterclockwise from due east.
  # Convert to degrees clockwise from due north:
  (90 - to_degrees(bearing) + 360) % 360
end

def bounding_box(point, radius, options = {})


* :units - :mi (default) or :km

ways of specifying the point. Also accepts an options hash:
See Geocoder::Calculations.distance_between for

(ActiveRecord queries use it thusly).
roughly limiting the possible solutions in a geo-spatial search
This is useful for finding corner points of a map viewport, or for

is twice the radius).
from the center point to any side of the box (the length of each side
with the given point at its center. The radius is the shortest distance
Returns coordinates of the lower-left and upper-right corners of a box
# 
def bounding_box(point, radius, options = {})
  lat,lon = extract_coordinates(point)
  radius  = radius.to_f
  units   = options[:units] || :mi
  [
    lat - (radius / latitude_degree_distance(units)),
    lon - (radius / longitude_degree_distance(lat, units)),
    lat + (radius / latitude_degree_distance(units)),
    lon + (radius / longitude_degree_distance(lat, units))
  ]
end

def compass_point(bearing, points = COMPASS_POINTS)


Translate a bearing (float) into a compass direction (string, eg "North").
# 
def compass_point(bearing, points = COMPASS_POINTS)
  seg_size = 360 / points.size
  points[((bearing + (seg_size / 2)) % 360) / seg_size]
end

def distance_between(point1, point2, options = {})


* :units - :mi (default) or :km

The options hash supports:

which returns a [lat,lon] array
* a geocoded object (one which implements a +to_coordinates+ method
* a geocodable address (string)
* an array of coordinates ([lat,lon])

Geocoder methods that accept points as arguments. They can be:
The points are given in the same way that points are given to all
Takes two points and an options hash.
Distance between two points on Earth (Haversine formula).
# 
def distance_between(point1, point2, options = {})
  # set default options
  options[:units] ||= :mi
  # convert to coordinate arrays
  point1 = extract_coordinates(point1)
  point2 = extract_coordinates(point2)
  # convert degrees to radians
  point1 = to_radians(point1)
  point2 = to_radians(point2)
  # compute deltas
  dlat = point2[0] - point1[0]
  dlon = point2[1] - point1[1]
  a = (Math.sin(dlat / 2))**2 + Math.cos(point1[0]) *
      (Math.sin(dlon / 2))**2 * Math.cos(point2[0])
  c = 2 * Math.atan2( Math.sqrt(a), Math.sqrt(1-a))
  c * earth_radius(options[:units])
end

def distance_to_radians(distance, units = :mi) 

def distance_to_radians(distance, units = :mi)
  distance.to_f / earth_radius(units)
end

def earth_radius(units = :mi)


Radius of the Earth in the given units (:mi or :km). Default is :mi.
# 
def earth_radius(units = :mi)
  units == :km ? EARTH_RADIUS : to_miles(EARTH_RADIUS)
end

def extract_coordinates(point)


running method and may return nil.
[lat,lon] array. Note that if a string is passed this may be a slow-
or an object that implements +to_coordinates+ and returns a
Takes an object which is a [lat,lon] array, a geocodable string,
# 
def extract_coordinates(point)
  case point
    when Array; point
    when String; Geocoder.coordinates(point)
    else point.to_coordinates
  end
end

def geographic_center(points)


the procedure documented at http://www.geomidpoint.com/calculation.html.
(can be mixed). Any objects missing coordinates are ignored. Follows
gravity) for an array of geocoded objects and/or [lat,lon] arrays
Compute the geographic center (aka geographic midpoint, center of
# 
def geographic_center(points)
  # convert objects to [lat,lon] arrays and convert degrees to radians
  coords = points.map{ |p| to_radians(extract_coordinates(p)) }
  # convert to Cartesian coordinates
  x = []; y = []; z = []
  coords.each do |p|
    x << Math.cos(p[0]) * Math.cos(p[1])
    y << Math.cos(p[0]) * Math.sin(p[1])
    z << Math.sin(p[0])
  end
  # compute average coordinate values
  xa, ya, za = [x,y,z].map do |c|
    c.inject(0){ |tot,i| tot += i } / c.size.to_f
  end
  # convert back to latitude/longitude
  lon = Math.atan2(ya, xa)
  hyp = Math.sqrt(xa**2 + ya**2)
  lat = Math.atan2(za, hyp)
  # return answer in degrees
  to_degrees [lat, lon]
end

def km_in_mi


Conversion factor: km to mi.
# 
def km_in_mi
  KM_IN_MI
end

def latitude_degree_distance(units = :mi)


Distance spanned by one degree of latitude in the given units.
# 
def latitude_degree_distance(units = :mi)
  2 * Math::PI * earth_radius(units) / 360
end

def longitude_degree_distance(latitude, units = :mi)


This ranges from around 69 miles at the equator to zero at the poles.
Distance spanned by one degree of longitude at the given latitude.
# 
def longitude_degree_distance(latitude, units = :mi)
  latitude_degree_distance(units) * Math.cos(to_radians(latitude))
end

def mi_in_km


Conversion factor: mi to km.
# 
def mi_in_km
  1.0 / KM_IN_MI
end

def radians_to_distance(radians, units = :mi) 

def radians_to_distance(radians, units = :mi)
  radians * earth_radius(units)
end

def to_degrees(*args)


converts each value and returns array.
If an array (or multiple arguments) is passed,
Convert radians to degrees.
# 
def to_degrees(*args)
  args = args.first if args.first.is_a?(Array)
  if args.size == 1
    (args.first * 180.0) / Math::PI
  else
    args.map{ |i| to_degrees(i) }
  end
end

def to_kilometers(mi)


Convert miles to kilometers.
# 
def to_kilometers(mi)
  mi * mi_in_km
end

def to_miles(km)


Convert kilometers to miles.
# 
def to_miles(km)
  km * km_in_mi
end

def to_radians(*args)


converts each value and returns array.
If an array (or multiple arguments) is passed,
Convert degrees to radians.
# 
def to_radians(*args)
  args = args.first if args.first.is_a?(Array)
  if args.size == 1
    args.first * (Math::PI / 180)
  else
    args.map{ |i| to_radians(i) }
  end
end