Distance (distance v1.0.1)

Basic distance calculations for cartesian coordinates for calculting distances on a single plane. If you are looking to calculating distance on the surface of Earth, check out the Distance.GreatCircle module.

Examples

iex> Distance.distance({2.5, 2.5}, {4, 0.8})
2.2671568097509267
iex> Distance.segment_distance({2.5, 2.5}, {4, 0.8}, {-2, 3})
1.0797077632696
iex> Distance.distance([{2.5, 2.5}, {4, 0.8}, {-2, 3}, {1, -1}])
13.657774933219109

Link to this section Summary

Functions

Returns the direction from p0 to p1. The direction is measured as radians off of the positive x-axis in the direction of the positive y-axis.

Returns the angular difference between two directions in the range

Returns the geometric distance of the linestring defined by the List of points. Accepts 2- or 3-dimensional points.

Returns the geometric distance between two points. Accepts 2- or 3-dimensional points.

Returns the square of the distance between two points. This is used by the Distance.distance function above, but having access to the value before the expensice sqaure root operation is useful for time-sensitive applications that only need values for comparison.

Returns the geometric distance from a point p and the infinite line extending through points p1 and p2.

Similar to Distance.distance_squared, this provides much faster comparable version of Distance.line_distance.

Returns the cotemrinal angle closest to 0 for the given angle

Returns the minimal positive coterminal angle for the given angle.

Returns a point distance units away in the direction direction.

Returns the geometric distance from a point p and the line segment between two points p1 and p2. Note that this is a line segment, not an infinite line, so points not between p1 and p2 will return the distance to the nearest of the two endpoints.

Similar to Distance.distance_squared, this provides much faster comparable version of Distance.segment_distance.

Provides the minimum distance between any two points along the given line segments. In the case where the segements are not disjoint, this will always return 0.0.

Similar to Distance.distance_squared, this provides much faster comparable version of Distance.segment_segment_distance.

Link to this section Types

Specs

point() :: {number(), number()}

Link to this section Functions

Link to this function

angle_to(arg1, arg2)

Specs

angle_to(point(), point()) :: float()

Returns the direction from p0 to p1. The direction is measured as radians off of the positive x-axis in the direction of the positive y-axis.

The returned value will always be in the range of (-π, π]. The direction along the negative x-axis will always return positive π.

Examples

iex> Distance.angle_to({2, -1}, {2, 5}) 
:math.pi() / 2
Link to this function

angular_difference(a1, a2)

Specs

angular_difference(number(), number()) :: float()

Returns the angular difference between two directions in the range

Specs

distance([point()]) :: float()

Returns the geometric distance of the linestring defined by the List of points. Accepts 2- or 3-dimensional points.

Examples

iex> Distance.distance([{2.5, 2.5}, {4, 0.8}, {2.5, 3.1}, {2.5, 3.1}])
5.013062853300123
iex> Distance.distance([{1, -2, 1}, {-2, 2, -1}, {-2, 1, 0}, {2, -3, 1}])
12.543941016045627
Link to this function

distance(p1, p2)

Specs

distance(point(), point()) :: float()

Returns the geometric distance between two points. Accepts 2- or 3-dimensional points.

Examples

iex> Distance.distance({1, -2}, {-2, 2})
5.0
iex> Distance.distance({1, -2, 2}, {-2, 2, 1})
5.0990195135927845
Link to this function

distance_squared(arg1, arg2)

Specs

distance_squared(point(), point()) :: float()

Returns the square of the distance between two points. This is used by the Distance.distance function above, but having access to the value before the expensice sqaure root operation is useful for time-sensitive applications that only need values for comparison.

Examples

iex> Distance.distance_squared({1, -2}, {-2, 2})
25
iex> Distance.distance_squared({1, -2, 2}, {-2, 2, 1})
26
Link to this function

line_distance(p, p1, p2)

Specs

line_distance(point(), point(), point()) :: float()

Returns the geometric distance from a point p and the infinite line extending through points p1 and p2.

Examples

iex> Distance.line_distance({3, 2}, {-2, 1}, {5, 3})
0.4120816918460673 # distance between the point {3, 2} and the closest point along line segment ({-2, 1}, {5, 3})
iex> Distance.line_distance({1, -2}, {-2, 2}, {-10, 102})
2.671464946476815
iex> Distance.line_distance({1, -2}, {-2, 2}, {1, -2})
0.0
Link to this function

line_distance_squared(arg1, arg2, arg3)

Specs

line_distance_squared(point(), point(), point()) :: float()

Similar to Distance.distance_squared, this provides much faster comparable version of Distance.line_distance.

Examples

iex> Distance.line_distance_squared({3, 2}, {-2, 1}, {5, 3})
0.16981132075471717
iex> Distance.line_distance_squared({1, -2}, {-2, 2}, {-10, 102})
7.136724960254371
Link to this function

min_coterminal_angle(angle)

Specs

min_coterminal_angle(number()) :: float()

Returns the cotemrinal angle closest to 0 for the given angle

No matter the angle provided, the returned angle will be in the range (-π, π]

Examples

iex> Distance.min_coterminal_angle(:math.pi() / 2.0)
:math.pi() / 2
iex> Distance.min_coterminal_angle(-2.0 + :math.pi() * 6)
-2.0
iex> Distance.min_coterminal_angle(-:math.pi())
:math.pi()
Link to this function

min_positive_coterminal_angle(angle)

Specs

min_positive_coterminal_angle(number()) :: float()

Returns the minimal positive coterminal angle for the given angle.

No matter the angle provided, the returned angle will be in the range [0, 2π)

Examples

iex> Distance.min_positive_coterminal_angle(:math.pi() / 2.0)
:math.pi() / 2
iex> Distance.min_positive_coterminal_angle(-2.0 + :math.pi() * 6)
:math.pi() * 2.0 - 2.0
iex> Distance.min_positive_coterminal_angle(-:math.pi())
:math.pi()
Link to this function

project(arg, direction, distance)

Specs

project(point(), number(), number()) :: point()

Returns a point distance units away in the direction direction.

The direction is measured as radians off of the positive x-axis in the direction of the positive y-axis. Thus the new coordinates are:

x1 = x0 + distance * cos(direction)
y1 = y0 + distance * sin(direction)

Examples

iex> Distance.project({3, 5}, 3 * :math.pi() / 4, 2)
{1.585786437626905, 6.414213562373095} 
Link to this function

segment_distance(p, p1, p2)

Specs

segment_distance(point(), point(), point()) :: float()

Returns the geometric distance from a point p and the line segment between two points p1 and p2. Note that this is a line segment, not an infinite line, so points not between p1 and p2 will return the distance to the nearest of the two endpoints.

Examples

iex> Distance.segment_distance({3, 2}, {-2, 1}, {5, 3})
0.4120816918460673 # distance between the point {3, 2} and the closest point along line segment ({-2, 1}, {5, 3})
iex> Distance.segment_distance({1, -2}, {-2, 2}, {-10, 102})
5.0
iex> Distance.segment_distance({1, -2}, {-2, 2}, {1, -2})
0.0
Link to this function

segment_distance_squared(arg1, arg2, arg3)

Specs

segment_distance_squared(point(), point(), point()) :: float()

Similar to Distance.distance_squared, this provides much faster comparable version of Distance.segment_distance.

Examples

iex> Distance.segment_distance_squared({3, 2}, {-2, 1}, {5, 3})
0.16981132075471717
iex> Distance.segment_distance_squared({1, -2}, {-2, 2}, {-10, 102})
25
Link to this function

segment_segment_distance(a1, a2, b1, b2)

Specs

segment_segment_distance(point(), point(), point(), point()) :: float()

Provides the minimum distance between any two points along the given line segments. In the case where the segements are not disjoint, this will always return 0.0.

Example

iex> Distance.segment_segment_distance({0, 0}, {1, 1}, {1, 0}, {2, 0})
0.7071067811865476
iex> Distance.segment_segment_distance({0, 0}, {1, 1}, {1, 1}, {2, 2})
0.0
Link to this function

segment_segment_distance_squared(a1, a2, b1, b2)

Specs

segment_segment_distance_squared(point(), point(), point(), point()) :: float()

Similar to Distance.distance_squared, this provides much faster comparable version of Distance.segment_segment_distance.