#include <Magnum/Math/Quaternion.h>
template<class T>
Quaternion class
Quaternion.
Template parameters | |
---|---|
T | Underlying data type |
Represents 3D rotation. Usually denoted as the following in equations, with being the vector() part and being the scalar() part:
See 2D and 3D transformations for a brief introduction.
Public types
- using Type = T
- Underlying data type.
Public static functions
- static auto rotation(Rad<T> angle, const Vector3<T>& normalizedAxis) -> Quaternion<T>
- Rotation quaternion.
- static auto rotation(const Vector3<T>& normalizedFrom, const Vector3<T>& normalizedTo) -> Quaternion<T> new in Git master
- Quaternion rotating from a vector to another.
- static auto reflection(const Vector3<T>& normal) -> Quaternion<T> new in Git master
- Reflection quaternion.
- static auto fromMatrix(const Matrix3x3<T>& matrix) -> Quaternion<T>
- Create a quaternion from a rotation matrix.
Constructors, destructors, conversion operators
- Quaternion() constexpr noexcept
- Default constructor.
- Quaternion(IdentityInitT) explicit constexpr noexcept
- Construct an identity quaternion.
- Quaternion(ZeroInitT) explicit constexpr noexcept
- Construct a zero-initialized quaternion.
-
Quaternion(Magnum::
NoInitT) explicit noexcept - Construct without initializing the contents.
- Quaternion(const Vector3<T>& vector, T scalar) constexpr noexcept
- Construct from a vector and a scalar.
- Quaternion(const Vector3<T>& vector) explicit constexpr noexcept
- Construct from a vector.
-
template<class U>Quaternion(const Quaternion<U>& other) explicit constexpr noexcept
- Construct from a quaternion of different type.
-
template<class U, class = decltype(Implementation::QuaternionConverter<T, U>::from(std::Quaternion(const U& other) explicit constexpr
declval<U>()))> - Construct a quaternion from external representation.
-
template<class U, class = decltype(Implementation::QuaternionConverter<T, U>::to(std::operator U() const explicit constexpr
declval<Quaternion<T>>()))> - Convert the quaternion to external representation.
Public functions
- auto data() -> T*
- Raw data.
- auto data() const -> const T*
- auto operator==(const Quaternion<T>& other) const -> bool
- Equality comparison.
- auto operator!=(const Quaternion<T>& other) const -> bool
- Non-equality comparison.
- auto isNormalized() const -> bool
- Whether the quaternion is normalized.
- auto vector() -> Vector3<T>&
- Vector part ( )
- auto vector() const -> const Vector3<T> constexpr
- auto scalar() -> T&
- Scalar part ( )
- auto scalar() const -> T constexpr
- auto angle() const -> Rad<T>
- Rotation angle of a unit quaternion.
- auto axis() const -> Vector3<T>
- Rotation axis of a unit quaternion.
- auto toMatrix() const -> Matrix3x3<T>
- Convert to a rotation matrix.
- auto toEuler() const -> Vector3<Rad<T>> new in 2020.06
- Convert to an euler vector.
- auto operator+() const -> Quaternion<T> new in Git master
- Promotion.
- auto operator-() const -> Quaternion<T>
- Negated quaternion.
- auto operator+=(const Quaternion<T>& other) -> Quaternion<T>&
- Add and assign a quaternion.
- auto operator+(const Quaternion<T>& other) const -> Quaternion<T>
- Add a quaternion.
- auto operator-=(const Quaternion<T>& other) -> Quaternion<T>&
- Subtract and assign a quaternion.
- auto operator-(const Quaternion<T>& other) const -> Quaternion<T>
- Subtract a quaternion.
- auto operator*=(T scalar) -> Quaternion<T>&
- Multiply with a scalar and assign.
- auto operator*(T scalar) const -> Quaternion<T>
- Multiply with a scalar.
- auto operator/=(T scalar) -> Quaternion<T>&
- Divide with a scalar and assign.
- auto operator/(T scalar) const -> Quaternion<T>
- Divide with a scalar.
- auto operator*(const Quaternion<T>& other) const -> Quaternion<T>
- Multiply with a quaternion.
- auto dot() const -> T
- Dot product of the quaternion.
- auto length() const -> T
- Quaternion length.
- auto normalized() const -> Quaternion<T>
- Normalized quaternion (of unit length)
- auto conjugated() const -> Quaternion<T>
- Conjugated quaternion.
- auto inverted() const -> Quaternion<T>
- Inverted quaternion.
- auto invertedNormalized() const -> Quaternion<T>
- Inverted normalized quaternion.
- auto transformVector(const Vector3<T>& vector) const -> Vector3<T>
- Rotate a vector with a quaternion.
- auto transformVectorNormalized(const Vector3<T>& vector) const -> Vector3<T>
- Rotate a vector with a normalized quaternion.
- auto reflectVector(const Vector3<T>& vector) const -> Vector3<T> new in Git master
- Reflect a vector with a reflection quaternion.
Function documentation
template<class T>
static Quaternion<T> Magnum:: Math:: Quaternion<T>:: rotation(Rad<T> angle,
const Vector3<T>& normalizedAxis)
Rotation quaternion.
Parameters | |
---|---|
angle | Rotation angle (counterclockwise) |
normalizedAxis | Normalized rotation axis |
Expects that the rotation axis is normalized.
template<class T>
static Quaternion<T> Magnum:: Math:: Quaternion<T>:: rotation(const Vector3<T>& normalizedFrom,
const Vector3<T>& normalizedTo) new in Git master
Quaternion rotating from a vector to another.
Parameters | |
---|---|
normalizedFrom | Normalized vector from which to rotate |
normalizedTo | Normalized vector to which to rotate |
Returns a quaternion that transforms normalizedFrom
into normalizedTo
. Expects that both vectors are normalized. If the vectors are parallel, returns an identity quaternion, if they're antiparallel, picks an arbitrary rotation axis.
Based on The Shortest Arc Quaternion by Stan Melax, Game Programming Gems 1, page 214.
template<class T>
static Quaternion<T> Magnum:: Math:: Quaternion<T>:: reflection(const Vector3<T>& normal) new in Git master
Reflection quaternion.
Parameters | |
---|---|
normal | Normal of the plane through which to reflect |
Expects that the normal is normalized.
Note that reflection quaternions behave differently from usual rotations, in particular they can't be concatenated together with usual quaternion multiplication, toMatrix() will not create a reflection matrix out of them and transformVector() will not do a proper reflection either, you have to use reflectVector() instead. See its documentation for more information.
template<class T>
static Quaternion<T> Magnum:: Math:: Quaternion<T>:: fromMatrix(const Matrix3x3<T>& matrix)
Create a quaternion from a rotation matrix.
Expects that the matrix is a pure rotation, i.e. orthogonal and without any reflection. See Matrix4::
template<class T>
Magnum:: Math:: Quaternion<T>:: Quaternion() constexpr noexcept
Default constructor.
Equivalent to Quaternion(IdentityInitT).
template<class T>
Magnum:: Math:: Quaternion<T>:: Quaternion(IdentityInitT) explicit constexpr noexcept
Construct an identity quaternion.
Creates unit quaternion.
template<class T>
Magnum:: Math:: Quaternion<T>:: Quaternion(const Vector3<T>& vector,
T scalar) constexpr noexcept
Construct from a vector and a scalar.
template<class T>
Magnum:: Math:: Quaternion<T>:: Quaternion(const Vector3<T>& vector) explicit constexpr noexcept
Construct from a vector.
To be used in transformations later.
template<class T>
template<class U>
Magnum:: Math:: Quaternion<T>:: Quaternion(const Quaternion<U>& other) explicit constexpr noexcept
Construct from a quaternion of different type.
Performs only default casting on the values, no rounding or anything else.
template<class T>
T* Magnum:: Math:: Quaternion<T>:: data()
Raw data.
Contrary to what Doxygen shows, returns reference to an one-dimensional fixed-size array of four elements, i.e. T(&)[4]
, vector part first, scalar after.
template<class T>
const T* Magnum:: Math:: Quaternion<T>:: data() const
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<class T>
bool Magnum:: Math:: Quaternion<T>:: isNormalized() const
Whether the quaternion is normalized.
Quaternion is normalized if it has unit length:
template<class T>
T Magnum:: Math:: Quaternion<T>:: scalar() const constexpr
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<class T>
Vector3<T> Magnum:: Math:: Quaternion<T>:: axis() const
Rotation axis of a unit quaternion.
Expects that the quaternion is normalized.
If the angle() is zero, the returned axis is a NaN vector, indicating that the axis is arbitrary. In other words, rotating by a zero angle around any axis will always give back a quaternion. To always get a unit vector back, you do the following, replace it with an X axis for a zero angle:
Quaternion a = …; Rad angle = a.angle(); Vector3 axis = angle == 0.0_radf ? Vector3::xAxis() : a.axis();
template<class T>
Vector3<Rad<T>> Magnum:: Math:: Quaternion<T>:: toEuler() const new in 2020.06
Convert to an euler vector.
Expects that the quaternion is normalized. Returns the angles in an XYZ order, you can combine them back to a quaternion like this:
Rad x, y, z; Quaternion a = Quaternion::rotation(z, Vector3::zAxis())* Quaternion::rotation(y, Vector3::yAxis())* Quaternion::rotation(x, Vector3::xAxis());
template<class T>
Quaternion<T> Magnum:: Math:: Quaternion<T>:: operator+() const new in Git master
Promotion.
Returns the value as-is.
template<class T>
Quaternion<T> Magnum:: Math:: Quaternion<T>:: operator-() const
Negated quaternion.
template<class T>
Quaternion<T>& Magnum:: Math:: Quaternion<T>:: operator+=(const Quaternion<T>& other)
Add and assign a quaternion.
The computation is done in-place.
template<class T>
Quaternion<T> Magnum:: Math:: Quaternion<T>:: operator+(const Quaternion<T>& other) const
Add a quaternion.
template<class T>
Quaternion<T>& Magnum:: Math:: Quaternion<T>:: operator-=(const Quaternion<T>& other)
Subtract and assign a quaternion.
The computation is done in-place.
template<class T>
Quaternion<T> Magnum:: Math:: Quaternion<T>:: operator-(const Quaternion<T>& other) const
Subtract a quaternion.
template<class T>
Quaternion<T>& Magnum:: Math:: Quaternion<T>:: operator*=(T scalar)
Multiply with a scalar and assign.
The computation is done in-place.
template<class T>
Quaternion<T> Magnum:: Math:: Quaternion<T>:: operator*(T scalar) const
Multiply with a scalar.
template<class T>
Quaternion<T>& Magnum:: Math:: Quaternion<T>:: operator/=(T scalar)
Divide with a scalar and assign.
The computation is done in-place.
template<class T>
Quaternion<T> Magnum:: Math:: Quaternion<T>:: operator/(T scalar) const
Divide with a scalar.
template<class T>
Quaternion<T> Magnum:: Math:: Quaternion<T>:: operator*(const Quaternion<T>& other) const
Multiply with a quaternion.
template<class T>
T Magnum:: Math:: Quaternion<T>:: length() const
Quaternion length.
See also dot() const which is faster for comparing length with other values.
template<class T>
Quaternion<T> Magnum:: Math:: Quaternion<T>:: normalized() const
Normalized quaternion (of unit length)
template<class T>
Quaternion<T> Magnum:: Math:: Quaternion<T>:: conjugated() const
Conjugated quaternion.
template<class T>
Quaternion<T> Magnum:: Math:: Quaternion<T>:: inverted() const
Inverted quaternion.
See invertedNormalized() which is faster for normalized quaternions.
template<class T>
Quaternion<T> Magnum:: Math:: Quaternion<T>:: invertedNormalized() const
Inverted normalized quaternion.
Equivalent to conjugated(). Expects that the quaternion is normalized.
template<class T>
Vector3<T> Magnum:: Math:: Quaternion<T>:: transformVector(const Vector3<T>& vector) const
Rotate a vector with a quaternion.
See transformVectorNormalized(), which is faster for normalized quaternions.
Note that this function will not give the correct result for quaternions created with reflection(), for those use reflectVector() instead.
template<class T>
Vector3<T> Magnum:: Math:: Quaternion<T>:: transformVectorNormalized(const Vector3<T>& vector) const
Rotate a vector with a normalized quaternion.
Faster alternative to transformVector(), expects that the quaternion is normalized. Done using the following equation:
Which is equivalent to the common equation (source: https:/
template<class T>
Vector3<T> Magnum:: Math:: Quaternion<T>:: reflectVector(const Vector3<T>& vector) const new in Git master
Reflect a vector with a reflection quaternion.
Compared to the usual vector transformation performed with rotation quaternions and transformVector(), the reflection is done like this:
You can use reflection() to create a quaternion reflecting along given normal. Note that it's **not possible to combine reflections and rotations with the usual quaternion multiplication. Assuming a (normalized) rotation quaternion , a combined rotation and reflection of vector would look like this instead:
See also quaternion reflection at Euclidean Space.
template<class T>
template<class T>
T dot(const Quaternion<T>& a,
const Quaternion<T>& b)
Dot product between two quaternions.
template<class T>
template<class T>
Rad<T> halfAngle(const Quaternion<T>& normalizedA,
const Quaternion<T>& normalizedB)
Half-angle between normalized quaternions.
Expects that both quaternions are normalized.
To avoid numerical issues when two complex numbers are very close to each other, the dot product is clamped to the range before being passed to .
template<class T>
template<class T>
Quaternion<T> lerp(const Quaternion<T>& normalizedA,
const Quaternion<T>& normalizedB,
T t)
Linear interpolation of two quaternions.
Parameters | |
---|---|
normalizedA | First quaternion |
normalizedB | Second quaternion |
t | Interpolation phase (from range ) |
Expects that both quaternions are normalized.
Note that this function does not check for shortest path interpolation, see lerpShortestPath(const Quaternion<T>&, const Quaternion<T>&, T) for an alternative.
template<class T>
template<class T>
Quaternion<T> lerpShortestPath(const Quaternion<T>& normalizedA,
const Quaternion<T>& normalizedB,
T t)
Linear shortest-path interpolation of two quaternions.
Parameters | |
---|---|
normalizedA | First quaternion |
normalizedB | Second quaternion |
t | Interpolation phase (from range ) |
Unlike lerp(const Quaternion<T>&, const Quaternion<T>&, T), this interpolates on the shortest path at some performance expense. Expects that both quaternions are normalized.
template<class T>
template<class T>
Quaternion<T> slerp(const Quaternion<T>& normalizedA,
const Quaternion<T>& normalizedB,
T t)
Spherical linear interpolation of two quaternions.
Parameters | |
---|---|
normalizedA | First quaternion |
normalizedB | Second quaternion |
t | Interpolation phase (from range ) |
Expects that both quaternions are normalized. If the quaternions are nearly the same or one is a negation of the other, it falls back to a linear interpolation (shortest-path to avoid a degenerate case of returning a zero quaternion for ), but without post-normalization as the interpolation result can still be considered sufficiently normalized:
Otherwise, the interpolation is performed as:
Note that this function does not check for shortest path interpolation, see slerpShortestPath(const Quaternion<T>&, const Quaternion<T>&, T) for an alternative.
template<class T>
template<class T>
Quaternion<T> slerpShortestPath(const Quaternion<T>& normalizedA,
const Quaternion<T>& normalizedB,
T t)
Spherical linear shortest-path interpolation of two quaternions.
Parameters | |
---|---|
normalizedA | First quaternion |
normalizedB | Second quaternion |
t | Interpolation phase (from range ) |
Unlike slerp(const Quaternion<T>&, const Quaternion<T>&, T) this function interpolates on the shortest path. Expects that both quaternions are normalized. If the quaternions are nearly the same or one is a negation of the other, it falls back to a linear interpolation (shortest-path to avoid a degenerate case of returning a zero quaternion for ) but without post-normalization as the interpolation result can still be considered sufficiently normalized:
Otherwise, the interpolation is performed as:
template<class T>
template<class T>
Quaternion<T> operator*(T scalar,
const Quaternion<T>& quaternion)
Multiply a scalar with a quaternion.
Same as Quaternion::
template<class T>
template<class T>
Quaternion<T> operator/(T scalar,
const Quaternion<T>& quaternion)
Divide a quaternion with a scalar and invert.
template<class T>
template<class T>
Debug& operator<<(Debug& debug,
const Quaternion<T>& value)
Debug output operator.