Magnum::Math::Distance namespace
#include <Magnum/Math/Distance.h>

Functions for calculating distances.

This library is built as part of Magnum by default. To use this library with CMake, find the Magnum package and link to the Magnum::Magnum target:

find_package(Magnum REQUIRED)

# ...
target_link_libraries(your-app PRIVATE Magnum::Magnum)

See Downloading and building and Usage with CMake for more information.

Functions

template<class T>
auto pointPointSquared(const Vector2<T>& a, const Vector2<T>& b) -> T new in Git master
Distance of two points in 2D, squared.
template<class T>
auto pointPoint(const Vector2<T>& a, const Vector2<T>& b) -> T new in Git master
Distance of two points in 2D.
template<class T>
auto pointPointSquared(const Vector3<T>& a, const Vector3<T>& b) -> T new in Git master
Distance of two points in 3D, squared.
template<class T>
auto pointPoint(const Vector3<T>& a, const Vector3<T>& b) -> T new in Git master
Distance of two points in 3D.
template<class T>
auto linePointSquared(const Vector2<T>& a, const Vector2<T>& b, const Vector2<T>& point) -> T
Distance of line and point in 2D, squared.
template<class T>
auto linePoint(const Vector2<T>& a, const Vector2<T>& b, const Vector2<T>& point) -> T
Distance of line and point in 2D.
template<class T>
auto linePointSquared(const Vector3<T>& a, const Vector3<T>& b, const Vector3<T>& point) -> T
Distance of line and point in 3D, squared.
template<class T>
auto linePoint(const Vector3<T>& a, const Vector3<T>& b, const Vector3<T>& point) -> T
Distance of line and point in 3D.
template<class T>
auto lineSegmentPointSquared(const Vector2<T>& a, const Vector2<T>& b, const Vector2<T>& point) -> T
Distance of point from line segment in 2D, squared.
template<class T>
auto lineSegmentPoint(const Vector2<T>& a, const Vector2<T>& b, const Vector2<T>& point) -> T
Dístance of point from line segment in 2D.
template<class T>
auto lineSegmentPointSquared(const Vector3<T>& a, const Vector3<T>& b, const Vector3<T>& point) -> T
Distance of point from line segment in 3D, squared.
template<class T>
auto lineSegmentPoint(const Vector3<T>& a, const Vector3<T>& b, const Vector3<T>& point) -> T
Dístance of point from line segment in 3D.
template<class T>
auto pointPlaneScaled(const Vector3<T>& point, const Vector4<T>& plane) -> T
Distance of point from plane, scaled by the length of the planes normal.
template<class T>
auto pointPlane(const Vector3<T>& point, const Vector4<T>& plane) -> T
Distance of point from plane.
template<class T>
auto pointPlaneNormalized(const Vector3<T>& point, const Vector4<T>& plane) -> T
Distance of point from plane with normalized normal.

Function documentation

template<class T>
T Magnum::Math::Distance::pointPointSquared(const Vector2<T>& a, const Vector2<T>& b) new in Git master

Distance of two points in 2D, squared.

Parameters
a First point
b Second point

Same as (b - a).dot(). More efficient than pointPoint(const Vector2<T>&, const Vector2<T>&) for comparing distance with other values, because it doesn't calculate the square root.

template<class T>
T Magnum::Math::Distance::pointPoint(const Vector2<T>& a, const Vector2<T>& b) new in Git master

Distance of two points in 2D.

Parameters
a First point
b Second point

Same as (b - a).length():

\[ d = |\boldsymbol{b} - \boldsymbol{a}| \]

template<class T>
T Magnum::Math::Distance::pointPointSquared(const Vector3<T>& a, const Vector3<T>& b) new in Git master

Distance of two points in 3D, squared.

Parameters
a First point
b Second point

Same as (b - a).dot(). More efficient than pointPoint(const Vector3<T>&, const Vector3<T>&) for comparing distance with other values, because it doesn't calculate the square root.

template<class T>
T Magnum::Math::Distance::pointPoint(const Vector3<T>& a, const Vector3<T>& b) new in Git master

Distance of two points in 3D.

Parameters
a First point
b Second point

Same as (b - a).length():

\[ d = |\boldsymbol{b} - \boldsymbol{a}| \]

template<class T>
T Magnum::Math::Distance::linePointSquared(const Vector2<T>& a, const Vector2<T>& b, const Vector2<T>& point)

Distance of line and point in 2D, squared.

Parameters
a First point of the line
b Second point of the line
point Point

More efficient than linePoint(const Vector2<T>&, const Vector2<T>&, const Vector2<T>&) for comparing distance with other values, because it doesn't calculate the square root.

template<class T>
T Magnum::Math::Distance::linePoint(const Vector2<T>& a, const Vector2<T>& b, const Vector2<T>& point)

Distance of line and point in 2D.

Parameters
a First point of the line
b Second point of the line
point Point

The distance $ d $ is calculated from point $ \boldsymbol{p} $ and line defined by $ \boldsymbol{a} $ and $ \boldsymbol{b} $ using a perp-dot product:

\[ d = \frac{|(\boldsymbol b - \boldsymbol a) \times (\boldsymbol a - \boldsymbol p)|}{|\boldsymbol b - \boldsymbol a|} = \frac{|(\boldsymbol b - \boldsymbol a)_\bot \cdot (\boldsymbol a - \boldsymbol p)|}{|\boldsymbol b - \boldsymbol a|} \]

Source: http://mathworld.wolfram.com/Point-LineDistance2-Dimensional.html

template<class T>
T Magnum::Math::Distance::linePointSquared(const Vector3<T>& a, const Vector3<T>& b, const Vector3<T>& point)

Distance of line and point in 3D, squared.

More efficient than linePoint(const Vector3<T>&, const Vector3<T>&, const Vector3<T>&) for comparing distance with other values, because it doesn't calculate the square root.

template<class T>
T Magnum::Math::Distance::linePoint(const Vector3<T>& a, const Vector3<T>& b, const Vector3<T>& point)

Distance of line and point in 3D.

Parameters
a First point of the line
b Second point of the line
point Point

The distance $ d $ is calculated from point $ \boldsymbol{p} $ and line defined by $ \boldsymbol{a} $ and $ \boldsymbol{b} $ using a cross product:

\[ d = \frac{|(\boldsymbol b - \boldsymbol a) \times (\boldsymbol a - \boldsymbol p)|}{|\boldsymbol b - \boldsymbol a|} \]

Source: http://mathworld.wolfram.com/Point-LineDistance3-Dimensional.html

template<class T>
T Magnum::Math::Distance::lineSegmentPointSquared(const Vector2<T>& a, const Vector2<T>& b, const Vector2<T>& point)

Distance of point from line segment in 2D, squared.

More efficient than lineSegmentPoint() for comparing distance with other values, because it doesn't calculate the square root.

template<class T>
T Magnum::Math::Distance::lineSegmentPoint(const Vector2<T>& a, const Vector2<T>& b, const Vector2<T>& point)

Dístance of point from line segment in 2D.

Parameters
a Starting point of the line
b Ending point of the line
point Point

Returns distance of point from line segment or from its starting/ending point, depending on where the point lies.

Determining whether the point lies next to line segment or outside is done using Pythagorean theorem. If the following equation applies, the point $ \boldsymbol{p} $ lies outside line segment closer to $ \boldsymbol{a} $ :

\[ |\boldsymbol p - \boldsymbol b|^2 > |\boldsymbol b - \boldsymbol a|^2 + |\boldsymbol p - \boldsymbol a|^2 \]

On the other hand, if the following equation applies, the point lies outside line segment closer to $ \boldsymbol{b} $ :

\[ |\boldsymbol p - \boldsymbol a|^2 > |\boldsymbol b - \boldsymbol a|^2 + |\boldsymbol p - \boldsymbol b|^2 \]

The last alternative is when the following equation applies. The point then lies between $ \boldsymbol{a} $ and $ \boldsymbol{b} $ and the distance is calculated the same way as in linePoint().

\[ |\boldsymbol b - \boldsymbol a|^2 > |\boldsymbol p - \boldsymbol a|^2 + |\boldsymbol p - \boldsymbol b|^2 \]

template<class T>
T Magnum::Math::Distance::lineSegmentPointSquared(const Vector3<T>& a, const Vector3<T>& b, const Vector3<T>& point)

Distance of point from line segment in 3D, squared.

More efficient than lineSegmentPoint(const Vector3<T>&, const Vector3<T>&, const Vector3<T>&) for comparing distance with other values, because it doesn't calculate the square root.

template<class T>
T Magnum::Math::Distance::lineSegmentPoint(const Vector3<T>& a, const Vector3<T>& b, const Vector3<T>& point)

Dístance of point from line segment in 3D.

Parameters
a Starting point of the line
b Ending point of the line
point Point

Similar to 2D implementation lineSegmentPoint(const Vector2<T>&, const Vector2<T>&, const Vector2<T>&).

template<class T>
T Magnum::Math::Distance::pointPlaneScaled(const Vector3<T>& point, const Vector4<T>& plane)

Distance of point from plane, scaled by the length of the planes normal.

The distance $ d $ is calculated from point $ \boldsymbol{p} $ and plane with normal $ \boldsymbol{n} $ and $ w $ using:

\[ d = \boldsymbol{p} \cdot \boldsymbol{n} + w \]

The distance is negative if the point lies behind the plane.

More efficient than pointPlane() when merely the sign of the distance is of interest, for example when testing on which half space of the plane the point lies.

template<class T>
T Magnum::Math::Distance::pointPlane(const Vector3<T>& point, const Vector4<T>& plane)

Distance of point from plane.

The distance $ d $ is calculated from point $ \boldsymbol{p} $ and plane with normal $ \boldsymbol{n} $ and $ w $ using:

\[ d = \frac{\boldsymbol{p} \cdot \boldsymbol{n} + w}{\left| \boldsymbol{n} \right|} \]

The distance is negative if the point lies behind the plane.

In cases where the planes normal is a unit vector, pointPlaneNormalized() is more efficient. If merely the sign of the distance is of interest, pointPlaneScaled() is more efficient.

template<class T>
T Magnum::Math::Distance::pointPlaneNormalized(const Vector3<T>& point, const Vector4<T>& plane)

Distance of point from plane with normalized normal.

The distance $ d $ is calculated from point $ \boldsymbol{p} $ and plane with normal $ \boldsymbol{n} $ and $ w $ using:

\[ d = \boldsymbol{p} \cdot \boldsymbol{n} + w \]

The distance is negative if the point lies behind the plane. Expects that plane normal is normalized.

More efficient than pointPlane() in cases where the plane's normal is normalized. Equivalent to pointPlaneScaled() but with assertion added on top.