# 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`.

# point()

## Specs

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

# 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``````

# angular_difference(a1, a2)

## Specs

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

Returns the angular difference between two directions in the range

# distance(list)

## 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``````

# 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``````

# 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``````

# 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``````

# 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``````

# 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()``````

# 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()``````

# 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} ``````

# 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``````

# 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``````

# 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``````
`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`.