Distance

Provides a set of distance functions for use in GIS or graphic applications.

Installation

defp deps do
  [{:distance, "~> 1.0"}]
end

Functions

Point-Point Distance

Calculate geometric distance between two or more points (two- or three-dimensional):

Distance.distance({2, -1}, {-1, 3}) # => 5
Distance.distance({2, -1, 4}, {-1, 3, 2}) # => 5.385...

Distance.distance([{2.5, 2.5}, {4, 0.8}, {2.5, 3.1}, {2.5, 3.1}]) # => 5.013...

Calculate the square of the geometric distance between two points (useful as a faster way to compare distances between points without the need for an expensive square root operation):

Distance.distance_squared({2, -1}, {-1, 3}) # => 25
Distance.distance_squared({2, -1, 4}, {-1, 3, 2}) # => 29

Point-Segment Distance

Calculate geometric distance between a point and the closest point on a line segment. For instance the distance between the point (3, 3) and the line segment between (-2, 1) and (5, 3).

Distance.segment_distance({3, 2}, {-2, 1}, {5, 3}) # => 0.412...

Similar to the distance function, there is a squared version for faster calculations when needed:

Distance.segment_distance_squared({3, 2}, {-2, 1}, {5, 3}) # => 0.170...

Angular Functions

Get bearing from one point to another and project from one point a given distance along a direction. Additionally, there are useful methods for simplifying angles to coterminal angles and measuring differences between directions.

Angles are measured as radians off of the positive x-axis in the direction of the positive y-axis.

Great Circle Distance

Calculate great circle distances (shortest travel distance on the surface of a spherical Earth) given a two longitude-latitude pairs. This is an implementation of the Haversine formula and approximates using a spherical (non-ellipsoid) Earth with a mean radius of 6,371,008.8 meters derived from the WGS84 datum.

The function accepts two tuples in the form of {longitude, latitude} and returns the distance in meters. It will also accept a List of tuples.

Distance.GreatCircle.distance({-96.796667, 32.775833}, {126.967583, 37.566776}) # => 10974882.74...

Distance.GreatCircle.distance([
  {-96.796667, 32.775833},
  {126.967583, 37.566776},
  {151.215158, -33.857406},
  {55.274180, 25.197229},
  {6.942661, 50.334057},
  {-97.635926, 30.134442}
]) # => 44728827.849...

Vincenty's Inverse Formula Distance

Calculate distance per Vincenty's inverse formula (shortest travel distance on the surface of an oblate spheroid Earth) given two longitude-latitude pairs.

This method is iterative and more costly than other methods, such as the great circle method, but also potentially more accurate. It is important to note that nearly antipodal points can cause convergence issues with this method.

The function accepts two tuples in the form of {longitude, latitude} and returns the distance in meters. It will also accept a List of tuples.

Distance.Vincenty.distance({-96.796667, 32.775833}, {126.967583, 37.566776}) # => 10997423.55...

Distance.Vincenty.distance([
  {-96.796667, 32.775833},
  {126.967583, 37.566776},
  {151.215158, -33.857406},
  {55.274180, 25.197229},
  {6.942661, 50.334057},
  {-97.635926, 30.134442}
]) # => 44737835.514...

Contributing

In order to run all of the checks locally, use the validate mix task:

mix validate
mix test