Magnum::Math::Distance namespace

Functions for calculating distances.

Contents

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

find_package(Magnum REQUIRED)

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

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

Functions

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::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 perp-dot product:

\[ d = \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 cross product:

\[ d = \frac{|(\boldsymbol p - \boldsymbol a) \times (\boldsymbol p - \boldsymbol b)|}{|\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.