# AngleBetweenVectors.jl

#### When computing the arc separating two cartesian vectors, this is robustly stable; others are not.

#### Copyright © 2018 by Jeffrey Sarnoff. This work is released under The MIT License.

AngleBetweenVectors exports `angle`

.
`angle(point1, point2)`

determines the angle of their separation. The smaller of the two solutions is used. `π`

obtains If the points are opposed, [(1,0), (-1,0)]; so `0 <= angle(p1, p2) <= pi`

.

This function expects two points from a 2D, 3D .. ManyD space, in Cartesian coordinates. Tuples and Vectors are handled immediately (prefer Tuples for speed). To use another point representations, just define a `Tuple`

constructor for it. NamedTuples and SVectors have this already.

Most software uses `acos(dot(p1, p2) / sqrt(norm(p1) norm(p2))`

instead. While they coincide often; it is exceedingly easy to find cases where `angle`

is more accurate and then, usually they differ by a few ulps. Not always.

### provides

`angle( point₁, point₂ )`

- points are given as Cartesian coordinates
- points may be of any finite dimension >= 2
- points may be any type with a Tuple constructor defined

#### point representations that just work

- points as Tuples
- points as NamedTuples
- points as Vectors
- points as SVectors (StaticArrays)

#### working with other point representations

Just define a `Tuple`

constructor for the representation. That's all.

```
# working with this?
struct Point3D{T}
x::T
y::T
z::T
end
# define this:
Base.Tuple(a::Point3D{T}) where {T} = (a.x, a.y, a.z)
# this just works:
angle(point1::Point3D{T}, point2::Point3D{T}) where {T}
```

### why use it

This implementation is more robustly accurate than the usual method.

You can work with points in 2D, 3D, .. 1000D .. ?.

### notes

The shorter of two angle solutions is returned as an unoriented magnitude (0 <= radians < π).

Vectors are given by their Cartesian coordinates in 2D, 3D or .. N-dimensions.

This follows a note by Professor Kahan in Computing Cross-Products and Rotations (pg 15): "More uniformly accurate .. valid for Euclidean spaces of any dimension, it never errs by more than a modest multiple of ε."