#include <muu/quaternion.h>
template <typename Scalar>
muu::quaternion struct

A quaternion.

Template parameters
Scalar The quaternion's scalar component type. Must be a floating-point type.

Public types

using axis_angle_type = axis_angle<scalar_type>
The muu::axis_angle with the same scalar_type as this quaternion.
using constants = muu::constants<quaternion>
Compile-time constants for this quaternion.
using euler_type = euler_angles<scalar_type>
The muu::euler_angles with the same scalar_type as this quaternion.
using scalar_type = Scalar
The type of each scalar component stored in this quaternion.
using vector_type = vector<scalar_type, 3>
The three-dimensional muu::vector with the same scalar_type as this quaternion.

Public static functions

static auto slerp(const quaternion& start, const quaternion& finish, scalar_type alpha) -> quaternion constexpr noexcept
Performs a spherical-linear interpolation between two quaternion orientations.

Constructors, destructors, conversion operators

quaternion() defaulted noexcept
Default constructor. Values are not initialized.
quaternion(const quaternion&) defaulted constexpr noexcept
Copy constructor.
quaternion(scalar_type s, scalar_type vx, scalar_type vy, scalar_type vz) constexpr noexcept
Constructs a quaternion from raw scalar values.
quaternion(scalar_type s, const vector_type& v) constexpr noexcept
Constructs a quaternion from a scalar and a vector.
template <typename T>
quaternion(const quaternion<T>& quat) explicit constexpr noexcept
Converting constructor.
quaternion(const axis_angle_type& aa) explicit constexpr noexcept
Constructs a quaternion from an axis-angle rotation.
quaternion(const euler_type& euler) explicit constexpr noexcept
Constructs a quaternion from a set of euler angles.
quaternion(const matrix<scalar_type, 3, 3>& rot) explicit constexpr noexcept
Constructs a quaternion from a 3x3 3D rotation matrix.
quaternion(const matrix<scalar_type, 3, 4>& rot) explicit constexpr noexcept
Constructs a quaternion from the lower 3x3 part of a 3x4 3D transform matrix.
quaternion(const matrix<scalar_type, 4, 4>& rot) explicit constexpr noexcept
Constructs a quaternion from the lower 3x3 part of a 4x4 3D transform matrix.
template <typename T>
quaternion(const T& obj) constexpr noexcept
Constructs a quaternion from an implicitly bit-castable type.

Public functions

auto data() const -> constscalar_type* constexpr noexcept
Returns a pointer to the first scalar component in the quaternion.
auto data() -> scalar_type* constexpr noexcept
Returns a pointer to the first scalar component in the quaternion.
template <size_t Index>
auto get() const -> const auto& constexpr noexcept
Gets a reference to the value at a specific index.
template <size_t Index>
auto get() -> auto& constexpr noexcept
Gets a reference to the value at a specific index.
auto operator=(const quaternion&) -> quaternion& defaulted constexpr noexcept
Copy-assigment operator.
auto slerp(const quaternion& target, scalar_type alpha) -> quaternion& constexpr noexcept
Performs a spherical-linear interpolation on this quaternion (in-place).

Public variables

scalar_type s
The quaternion's scalar (real) part.
vector_type v
The quaternion's vector (imaginary) part.

Conjugate

static auto conjugate(const quaternion& q) -> quaternion constexpr noexcept
Returns the conjugate of a quaternion.
auto conjugate() const -> quaternion constexpr noexcept
Returns the conjugate of the quaternion.

Dot product

static auto dot(const quaternion& q1, const quaternion& q2) -> scalar_type constexpr noexcept
Returns the dot product of two quaternions.
auto dot(const quaternion& q) const -> scalar_type constexpr noexcept
Returns the dot product of this and another quaternion.

Equality (approximate)

template <typename T>
static auto approx_equal(const quaternion& q1, const quaternion<T>& q2, epsilon_type<scalar_type, T> epsilon = default_epsilon<scalar_type, T>) -> bool constexpr noexcept
Returns true if two quaternions are approximately equal.
static auto approx_zero(const quaternion& q, scalar_type epsilon = default_epsilon<scalar_type>) -> bool constexpr noexcept
Returns true if all the scalar components in a quaternion are approximately equal to zero.
template <typename T>
auto approx_equal(const quaternion<T>& q, epsilon_type<scalar_type, T> epsilon = default_epsilon<scalar_type, T>) const -> bool constexpr noexcept
Returns true if the quaternion is approximately equal to another.
auto approx_zero(scalar_type epsilon = default_epsilon<scalar_type>) const -> bool constexpr noexcept
Returns true if all the scalar components in the quaternion are approximately equal to zero.

Equality (exact)

static auto infinity_or_nan(const quaternion& q) -> bool constexpr noexcept
Returns true if any of the scalar components of a quaternion are infinity or NaN.
static auto zero(const quaternion& q) -> bool constexpr noexcept
Returns true if all the scalar components of a quaternion are exactly zero.
auto infinity_or_nan() const -> bool constexpr noexcept
Returns true if any of the scalar components of the quaternion are infinity or NaN.
auto zero() const -> bool constexpr noexcept
Returns true if all the scalar components of the quaternion are exactly zero.
template <typename T>
auto operator!=(const quaternion& lhs, const quaternion<T>& rhs) -> bool constexpr noexcept
Returns true if two quaternions are not exactly equal.
template <typename T>
auto operator==(const quaternion& lhs, const quaternion<T>& rhs) -> bool constexpr noexcept
Returns true if two quaternions are exactly equal.

Multiplication

auto operator*=(const quaternion& rhs) -> quaternion& constexpr noexcept
Multiplies this quaternion with another.
auto operator*=(scalar_type rhs) -> quaternion& constexpr noexcept
Scales the shortest-path rotation equivalent of this quaternion by a scalar (in-place).
auto operator*(const quaternion& lhs, const quaternion& rhs) -> quaternion constexpr noexcept
Multiplies two quaternions.
auto operator*(const quaternion& lhs, const vector_type& rhs) -> vector_type constexpr noexcept
Rotates a three-dimensional vector by the rotation encoded in a quaternion.
auto operator*(const vector_type& lhs, const quaternion& rhs) -> vector_type constexpr noexcept
Rotates a three-dimensional vector by the rotation encoded in a quaternion.
auto operator*(const quaternion& lhs, scalar_type rhs) -> quaternion constexpr noexcept
Scales the shortest-path rotation equivalent of a quaternion by a scalar.
auto operator*(scalar_type lhs, const quaternion& rhs) -> quaternion constexpr noexcept
Scales the shortest-path rotation equivalent of a quaternion by a scalar.

Normalization

static auto normalize(const quaternion& q) -> quaternion constexpr noexcept
Normalizes a quaternion.
static auto normalized(const quaternion& q) -> bool constexpr noexcept
Returns true if a quaternion is normalized (i.e. has a length of 1).
auto normalize() -> quaternion& constexpr noexcept
Normalizes the quaternion (in-place).
auto normalized() const -> bool constexpr noexcept
Returns true if the quaternion is normalized (i.e. has a length of 1).

Rotations

static auto from_axis_angle(const vector_type& axis, scalar_type angle) -> quaternion constexpr noexcept
Creates a quaternion from an axis-angle rotation.
static auto from_axis_angle(const axis_angle_type& aa) -> quaternion constexpr noexcept
Creates a quaternion from an axis-angle rotation.
static auto from_euler(scalar_type yaw, scalar_type pitch, scalar_type roll) -> quaternion constexpr noexcept
Creates a quaternion from a set of euler angles.
static auto from_euler(const euler_type& euler) -> quaternion constexpr noexcept
Creates a quaternion from an axis-angle rotation.
static auto from_rotation(const vector_type& from, const vector_type& to) -> quaternion constexpr noexcept
Creates a quaternion encoding a rotation from one direction vector to another.
static auto from_rotation(const matrix<Scalar, 3, 3>& rot) -> quaternion constexpr noexcept
Creates a quaternion from a 3x3 3D rotation matrix.
static auto from_rotation(const matrix<Scalar, 3, 4>& rot) -> quaternion constexpr noexcept
Creates a quaternion from the lower 3x3 part of a 3x4 3D transform matrix.
static auto from_rotation(const matrix<Scalar, 4, 4>& rot) -> quaternion constexpr noexcept
Creates a quaternion from the lower 3x3 part of a 4x4 3D transform matrix.
static auto to_axis_angle(const quaternion& quat, bool shortest_path = true) -> axis_angle_type constexpr noexcept
Extracts an axis-angle rotation from a quaternion.
static auto to_euler(const quaternion& q) -> euler_type constexpr noexcept
Extracts a set of euler angles from a quaternion.
auto to_axis_angle(bool shortest_path = true) const -> axis_angle_type constexpr noexcept
Extracts an axis-angle rotation from this quaternion.
auto to_euler() const -> euler_type constexpr noexcept
Extracts a set of euler angles from this quaternion.

Friends

template <typename Char, typename Traits>
auto operator<<(std::basic_ostream<Char, Traits>& os, const quaternion& q) -> std::basic_ostream<Char, Traits>&
Writes a quaternion out to a text stream.

Function documentation

template <typename Scalar>
static quaternion muu::quaternion::slerp(const quaternion& start, const quaternion& finish, scalar_type alpha) constexpr noexcept

Performs a spherical-linear interpolation between two quaternion orientations.

Parameters
start The start orientation.
finish The finish orientation.
alpha The blend factor.
Returns A quaternion orientation derived from a spherical-linear interpolation between start and finish.

template <typename Scalar>
muu::quaternion::quaternion(scalar_type s, scalar_type vx, scalar_type vy, scalar_type vz) constexpr noexcept

Constructs a quaternion from raw scalar values.

Parameters
s Initial value for the scalar (real) part.
vx Initial value for the vector (imaginary) part's X component.
vy Initial value for the vector (imaginary) part's Y component.
vz Initial value for the vector (imaginary) part's Z component.

template <typename Scalar>
muu::quaternion::quaternion(scalar_type s, const vector_type& v) constexpr noexcept

Constructs a quaternion from a scalar and a vector.

Parameters
s Initial value for the scalar (real) part.
v Initial value for the vector (imaginary) part.

template <typename Scalar>
template <typename T>
muu::quaternion::quaternion(const T& obj) constexpr noexcept

Constructs a quaternion from an implicitly bit-castable type.

Template parameters
T A bit-castable type.

template <typename Scalar>
template <size_t Index>
const auto& muu::quaternion::get() const constexpr noexcept

Gets a reference to the value at a specific index.

Template parameters
Index The index of the value to retrieve, where s == 0, v == 1.
Returns A reference to the selected value.

template <typename Scalar>
template <size_t Index>
auto& muu::quaternion::get() constexpr noexcept

Gets a reference to the value at a specific index.

Template parameters
Index The index of the value to retrieve, where s == 0, v == 1.
Returns A reference to the selected value.

template <typename Scalar>
quaternion& muu::quaternion::slerp(const quaternion& target, scalar_type alpha) constexpr noexcept

Performs a spherical-linear interpolation on this quaternion (in-place).

Parameters
target The 'target' orientation.
alpha The blend factor.
Returns A reference to the quaternion.

template <typename Scalar>
static bool muu::quaternion::zero(const quaternion& q) constexpr noexcept

Returns true if all the scalar components of a quaternion are exactly zero.

template <typename Scalar>
bool muu::quaternion::zero() const constexpr noexcept

Returns true if all the scalar components of the quaternion are exactly zero.

template <typename Scalar>
template <typename T>
bool muu::quaternion::operator!=(const quaternion& lhs, const quaternion<T>& rhs) constexpr noexcept

Returns true if two quaternions are not exactly equal.

template <typename Scalar>
template <typename T>
bool muu::quaternion::operator==(const quaternion& lhs, const quaternion<T>& rhs) constexpr noexcept

Returns true if two quaternions are exactly equal.

template <typename Scalar>
static quaternion muu::quaternion::normalize(const quaternion& q) constexpr noexcept

Normalizes a quaternion.

Parameters
q The quaternion to normalize.
Returns A normalized copy of the input quaternion.

template <typename Scalar>
quaternion& muu::quaternion::normalize() constexpr noexcept

Normalizes the quaternion (in-place).

Returns A reference to the quaternion.

template <typename Scalar>
static quaternion muu::quaternion::from_axis_angle(const vector_type& axis, scalar_type angle) constexpr noexcept

Creates a quaternion from an axis-angle rotation.

Parameters
axis Axis to rotate around. Must be normalized.
angle Angle to rotate by (in radians).
Returns A quaternion encoding the given axis-angle rotation.

template <typename Scalar>
static quaternion muu::quaternion::from_euler(scalar_type yaw, scalar_type pitch, scalar_type roll) constexpr noexcept

Creates a quaternion from a set of euler angles.

Parameters
yaw The rotation around the local up axis (in radians).
pitch The rotation around the local right axis (in radians).
roll The rotation around the local forward axis (in radians).
Returns A quaternion encoding the given axis-angle rotation.

template <typename Scalar>
static quaternion muu::quaternion::from_rotation(const vector_type& from, const vector_type& to) constexpr noexcept

Creates a quaternion encoding a rotation from one direction vector to another.

Parameters
from The source direction.
to The destination direction.
Returns A quaternion encoding a rotation between the two direction vectors.

template <typename Scalar>
static axis_angle_type muu::quaternion::to_axis_angle(const quaternion& quat, bool shortest_path = true) constexpr noexcept

Extracts an axis-angle rotation from a quaternion.

Parameters
quat The quaternion to convert. Must be normalized.
shortest_path Should the returned values be derived from the shortest path? true is more intuitive but means that the returned values may not convert back to the original quaternion if used with from_axis_angle().
Returns An axis-angle rotation representing the rotation stored in the given quaternion.

template <typename Scalar>
static euler_type muu::quaternion::to_euler(const quaternion& q) constexpr noexcept

Extracts a set of euler angles from a quaternion.

Parameters
q The quaternion to convert.
Returns A set of euler angles representing the rotation stored in the given quaternion.

template <typename Scalar>
axis_angle_type muu::quaternion::to_axis_angle(bool shortest_path = true) const constexpr noexcept

Extracts an axis-angle rotation from this quaternion.

Parameters
shortest_path Should the returned values be derived from the shortest path? true is more intuitive but means that the returned values may not convert back to the original quaternion if used with from_axis_angle().
Returns An axis-angle rotation representing the rotation stored in the quaternion.

template <typename Scalar>
template <typename S>
quaternion<S> normalize(const quaternion<S>& q) constexpr noexcept

Normalizes a quaternion.

Parameters
q The quaternion to normalize.
Returns A normalized copy of the input quaternion.