Struct Quaternion

pub struct Quaternion { /* private fields */ }

A 4D quaternion that holds 3 complex numbers and 1 real number structured as such: (a + b i + c j + d k)

Implementations

impl Quaternion

Constructors

pub fn new(a: f32, b: f32, c: f32, d: f32) -> Self

Creates a new quaternion from the given values

• a: The real component of the quaternion
• b: The complex i component of the quaternion
• c: The complex j component of the quaternion
• d: The complex k component of the quaternion

Returns: Returns a new quaternion

Examples

let quat = Quaternion::new(1.0, 0.2, 0.4, 0.6);
assert_eq!(1.0, quat.a());
assert_eq!(0.2, quat.b());
assert_eq!(0.4, quat.c());
assert_eq!(0.6, quat.d());

pub fn identity() -> Self

Gets the identity quaternion that represents no rotation

Returns: Returns the identity quaternion that represents no rotation

Examples

let quat = Quaternion::identity();
assert_eq!(1.0, quat.a());
assert_eq!(0.0, quat.b());
assert_eq!(0.0, quat.c());
assert_eq!(0.0, quat.d());

pub fn from_axis_angle(axis: Vector3, angle: f32) -> Self

Creates a rotation quaternion over the given axis and angle in radians

• axis: The axis that the quaternion will rotate around
• angle: The angle in radians that the quaternion will rotate around

Returns: Returns a rotation quaternion

Examples

let axis = Vector3::new(0.0, 1.0, 0.0);
let quat = Quaternion::from_axis_angle(axis, Math::PI_OVER_2);
assert_range!(0.70710678, quat.a());
assert_range!(0.0, quat.b());
assert_range!(0.70710678, quat.c());
assert_range!(0.0, quat.d());
let axis = Vector3::new(1.0, 2.0, 3.0);
let quat = Quaternion::from_axis_angle(axis, Math::PI_OVER_2);
assert_range!(0.70710678, quat.a());
assert_range!(0.18898223, quat.b());
assert_range!(0.37796447, quat.c());
assert_range!(0.5669467, quat.d());

pub fn from_axis_angle_deg(axis: Vector3, angle: f32) -> Self

Creates a rotation quaternion over the given axis and angle in degrees

• axis: The axis that the quaternion will rotate around
• angle: The angle in degrees that the quaternion will rotate around

Returns: Returns a rotation quaternion

Examples

let axis = Vector3::new(0.0, 1.0, 0.0);
let quat = Quaternion::from_axis_angle_deg(axis, 90.0);
assert_range!(0.70710678, quat.a());
assert_range!(0.0, quat.b());
assert_range!(0.70710678, quat.c());
assert_range!(0.0, quat.d());
let axis = Vector3::new(1.0, 2.0, 3.0);
let quat = Quaternion::from_axis_angle_deg(axis, 90.0);
assert_range!(0.70710678, quat.a());
assert_range!(0.18898223, quat.b());
assert_range!(0.37796447, quat.c());
assert_range!(0.5669467, quat.d());

pub fn from_euler(euler_angles: Vector3) -> Self

Creates a new rotation quaternion from the given euler angles (in radians) on each axis

• euler_angles: The angles rotating around the relative axis used to create the quaternion

Returns: Returns the new rotation quaternion from the given euler angles (in radians)

Examples

let actual = Quaternion::from_euler(Vector3::new(-0.209439510239, 0.698131700798, 1.34390352404));
let expected = Quaternion::new(0.7091271, 0.1348748, 0.3273477, 0.6097468);
assert_eq!(expected, actual);
let actual = Quaternion::from_euler(Vector3::new(
	Math::PI_OVER_2, Math::PI_OVER_4, 0.0
));
let expected = Quaternion::new(0.65328145, 0.6532815, 0.27059805, -0.27059805);
assert_eq!(expected, actual);
let actual = Quaternion::from_euler(Vector3::new(
	0.0, Math::PI_OVER_2, 0.0
));
let expected = Quaternion::new(0.70710678, 0.0, 0.70710678, 0.0);
assert_eq!(expected, actual);

pub fn from_euler_deg(euler_angles: Vector3) -> Self

Creates a new rotation quaternion from the given euler angles (in degrees) on each axis

• euler_angles: The angles rotating around the relative axis used to create the quaternion

Returns: Returns the new rotation quaternion from the given euler angles (in degrees)

Examples

let actual = Quaternion::from_euler_deg(Vector3::new(
	-12.0, 40.0, 77.0
));
let expected = Quaternion::new(0.7091271, 0.1348748, 0.3273477, 0.6097468);
assert_eq!(expected, actual);
let actual = Quaternion::from_euler_deg(Vector3::new(
	90.0, 45.0, 0.0
));
let expected = Quaternion::new(0.65328145, 0.65328145, 0.27059805, -0.27059805);
assert_eq!(expected, actual);
let actual = Quaternion::from_euler_deg(Vector3::new(
	0.0, 90.0, 0.0
));
let expected = Quaternion::new(0.70710678, 0.0, 0.70710678, 0.0);
assert_eq!(expected, actual);
let actual = Quaternion::from_euler_deg(Vector3::new(
	-23.0, 45.0, 67.0
));
let expected = Quaternion::new(0.7128339, 0.05338183, 0.4143703, 0.5633075);
assert_eq!(expected, actual);

impl Quaternion

Properties

pub fn a(&self) -> f32

Gets the real component of the quaternion

Returns: Returns the real component of the quaternion

pub fn set_a(&mut self, value: f32)

Sets the real component of the quaternion

• value: The value to set the real component to

pub fn b(&self) -> f32

Gets the complex i component of the quaternion

Returns: Returns the complex i component of the quaternion

pub fn set_b(&mut self, value: f32)

Sets the complex i component of the quaternion

• value: The value to set the complex i component of the quaternion

pub fn c(&self) -> f32

Gets the complex j component of the quaternion

Returns: Returns the complex j component of the quaternion

pub fn set_c(&mut self, value: f32)

Sets the complex j component of the quaternion

• value: The value to set the complex j component of the quaternion

pub fn d(&self) -> f32

Gets the complex k component of the quaternion

Returns: Returns the complex k component of the quaternion

pub fn set_d(&mut self, value: f32)

Sets the complex k component of the quaternion

• value: The value to set the complex k component of the quaternion

pub fn euler(&self) -> Vector3

Gets the euler angles (in radians) of the quaternion

Returns: Returns the euler angles (in radians) in a 3D vector

Remarks

This isn’t very accurate, the x and y coordinates have an error-margin of 0.01 while the z coordinate has an error-margin of 0.06

Examples

let euler = Vector3::new(0.3, 0.2, 1.0);
let quat = Quaternion::from_euler(euler);
assert_range!(euler.x(), quat.euler().x(), 0.01);
assert_range!(euler.y(), quat.euler().y(), 0.01);
assert_range!(euler.z(), quat.euler().z(), 0.06);

pub fn set_euler(&mut self, value: Vector3)

Sets the euler angles (in radians) of the quaternion

• value: The euler angles (in radians) to update the quaternion with

Examples

let mut actual = Quaternion::identity();
actual.set_euler(Vector3::new(
	Math::PI_OVER_2, Math::PI_OVER_4, 0.0
));
let expected = Quaternion::new(0.65328145, 0.65328145, 0.27059805, -0.27059805);
assert_eq!(expected, actual);
actual.set_euler(Vector3::new(
	0.0, Math::PI_OVER_2, 0.0
));
let expected = Quaternion::new(0.70710678, 0.0, 0.70710678, 0.0);
assert_eq!(expected, actual);

pub fn euler_deg(&self) -> Vector3

Gets the euler angles (in degrees) of the quaternion

Returns: Returns the euler angles (in degrees) in a 3D vector

Remarks

This isn’t very accurate, the x and y coordinates have an error-margin of 4.0 while the z coordinate has an error margin of 14.0

Examples

let euler = Vector3::new(-12.0, 40.0, 77.0);
let quat = Quaternion::from_euler_deg(euler);
assert_range!(euler.x(), quat.euler_deg().x(), 4.0);
assert_range!(euler.y(), quat.euler_deg().y(), 4.0);
assert_range!(euler.z(), quat.euler_deg().z(), 10.0);

pub fn set_euler_deg(&mut self, value: Vector3)

Sets the euler angles (in degrees) of the quaternion

• value: The euler angles (in degrees) to update the quaternion with

Examples

let mut actual = Quaternion::identity();
actual.set_euler_deg(Vector3::new(
	90.0, 45.0, 0.0
));
let expected = Quaternion::new(0.65328145, 0.65328145, 0.27059805, -0.27059805);
assert_eq!(expected, actual);
actual.set_euler_deg(Vector3::new(
	0.0, 90.0, 0.0
));
let expected = Quaternion::new(0.70710678, 0.0, 0.70710678, 0.0);
assert_eq!(expected, actual);

pub fn magnitude(&self) -> f32

Gets the magnitude of the quaternion

Returns: Returns the magnitude of the quaternion

Examples

let quat = Quaternion::identity();
assert_eq!(1.0, quat.magnitude());
let quat = Quaternion::new(0.0, 0.0, 0.0, 0.0);
assert_eq!(0.0, quat.magnitude());
let quat = Quaternion::new(1.0, 2.0, 3.0, 4.0);
assert_range!(5.477225575051661, quat.magnitude());

pub fn squared_magnitude(&self) -> f32

Gets the squared magnitude of the quaternion

Returns: Returns the squared magnitude of the quaternion

Examples

let quat = Quaternion::identity();
assert_eq!(1.0, quat.squared_magnitude());
let quat = Quaternion::new(0.0, 0.0, 0.0, 0.0);
assert_eq!(0.0, quat.squared_magnitude());
let quat = Quaternion::new(1.0, 2.0, 3.0, 4.0);
assert_eq!(30.0, quat.squared_magnitude());

impl Quaternion

Public Methods

pub fn conjugate(self) -> Self

Conjugates the quaternion, so it turns it from (a + b i + c j + d k) to (a - b i - c j - d k)

Returns: Returns the conjugated quaternion

Examples

let quat = Quaternion::new(1.0, -2.0, 3.0, -4.0);
let expected = Quaternion::new(1.0, 2.0, -3.0, 4.0);
assert_eq!(expected, quat.conjugate());

pub fn divide(self, rhs: Quaternion) -> Self

Divides the two quaternions together

• rhs: The other quaternion to divide with

Returns: Returns a divided quaternion

Examples

let a = Quaternion::new(1.0, 2.0, 3.0, 4.0);
let b = Quaternion::new(5.0, 6.0, 7.0, 8.0);
let expected = Quaternion::new(0.013409962, 0.0015325671, 0.0, 0.0030651342);
assert_eq!(expected, a / b);
let expected = Quaternion::new(0.013409962, -0.0015325671, 0.0, -0.0030651342);
assert_eq!(expected, b / a);
let expected = Quaternion::new(-0.031111112, 0.0044444446, 0.006666667, 0.008888889);
assert_eq!(expected, a / a.conjugate());

pub fn dot(self, rhs: Quaternion) -> f32

Dot products the two quaternions together

• rhs: The other quaternion to get the dot product with

Returns: Returns the dot product

Examples

let a = Quaternion::new(1.0, 2.0, 3.0, 4.0);
let b = Quaternion::new(5.0, 6.0, 7.0, 8.0);
assert_eq!(70.0, a.dot(b));

pub fn invert(self) -> Self

Inverts the quaternion

Returns: Returns the inverted quaternion

Examples

let actual = Quaternion::new(1.0, -2.0, 3.0, -4.0);
let expected = Quaternion::new(0.033333333, 0.06666667, -0.1, 0.13333334);
assert_eq!(expected, actual.invert());
assert_eq!(Quaternion::identity(), actual * actual.invert());
assert_eq!(Quaternion::identity(), Quaternion::identity().invert());

pub fn multiply(self, rhs: Quaternion) -> Self

Multiplies the two quaternions together

• rhs: The other quaternion to multiply with

Returns: Returns a multiplied quaternion

Remarks

Multiplying quaternions are not commutative, meaning that a * b =/= b * a

Examples

let a = Quaternion::new(1.0, 2.0, 3.0, 4.0);
let b = Quaternion::new(5.0, 6.0, 7.0, 8.0);
let expected = Quaternion::new(-60.0, 12.0, 30.0, 24.0);
assert_eq!(expected, a * b);
let expected = Quaternion::new(-60.0, 20.0, 14.0, 32.0);
assert_eq!(expected, b * a);
assert_eq!(30.0 * Quaternion::identity(), a * a.conjugate());

pub fn multiply_vector2(self, rhs: Vector2) -> Vector2

Multiplies the quaternion with the vector to rotate the vector

• rhs: The vector to multiply with

Returns: Returns the rotated vector

Examples

let vector = Vector2::new(100.0, 200.0);
let rotation = Quaternion::from_euler_deg(Vector3::new(-12.0, 40.0, 77.0));
let expected = Vector2::new(-151.0844, 139.3148);
assert_range!(expected.x(), (rotation * vector).x());
assert_range!(expected.y(), (rotation * vector).y());

pub fn multiply_vector3(self, rhs: Vector3) -> Vector3

Multiplies the quaternion with the vector to rotate the vector

• rhs: The vector to multiply with

Returns: Returns the rotated vector

Examples

let vector = Vector3::new(100.0, 200.0, 300.0);
let rotation = Quaternion::from_euler_deg(Vector3::new(-12.0, 40.0, 77.0));
let expected = Vector3::new(37.538, 201.6883, 312.9101);
assert_range!(expected.x(), (rotation * vector).x());
assert_range!(expected.y(), (rotation * vector).y());
assert_range!(expected.z(), (rotation * vector).z());

pub fn normalize(self) -> Self

Normalizes the quaternion

Returns: Returns the normalized quaternion

Examples

let actual = Quaternion::new(1.0, 2.0, 3.0, 4.0);
let expected = Quaternion::new(0.18257418, 0.36514837, 0.5477225, 0.73029673);
assert_eq!(expected, actual.normalize());

pub fn slerp(self, rhs: Quaternion, t: f32) -> Self

Spherically interpolates between the two quaternions

• rhs: The other quaternion to interpolate towards
• t: The clamped ratio (t) to interpolate with

Returns: Returns the spherically interpolated quaternion

Examples

let a = Quaternion::new(0.8660254, 0.0, 0.5, 0.0);
let b = Quaternion::new(0.4158418, 0.1114245, -0.2336062, 0.8718304);
let expected = Quaternion::new(0.81289685, 0.07065991, 0.1689338, 0.55287176);
assert_range!(expected.a(), a.slerp(b, 0.5).a(), 0.001);
assert_range!(expected.b(), a.slerp(b, 0.5).b(), 0.001);
assert_range!(expected.c(), a.slerp(b, 0.5).c(), 0.001);
assert_range!(expected.d(), a.slerp(b, 0.5).d(), 0.001);

pub fn slerp_unclamped(self, rhs: Quaternion, t: f32) -> Self

Spherically interpolates between the two quaternions (not clamped)

• rhs: The other quaternion to interpolate towards
• t: The unclamped ratio (t) to interpolate with

Returns: Returns the spherically interpolated quaternion

Examples

let a = Quaternion::new(0.8660254, 0.0, 0.5, 0.0);
let b = Quaternion::new(0.4158418, 0.1114245, -0.2336062, 0.8718304);
let expected = Quaternion::new(0.81289685, 0.07065991, 0.1689338, 0.55287176);
assert_range!(expected.a(), a.slerp_unclamped(b, 0.5).a(), 0.001);
assert_range!(expected.b(), a.slerp_unclamped(b, 0.5).b(), 0.001);
assert_range!(expected.c(), a.slerp_unclamped(b, 0.5).c(), 0.001);
assert_range!(expected.d(), a.slerp_unclamped(b, 0.5).d(), 0.001);

Trait Implementations

impl Add for Quaternion

type Output = Quaternion

The resulting type after applying the + operator.

fn add(self, rhs: Quaternion) -> Self::Output

Performs the + operation.

impl AddAssign for Quaternion

fn add_assign(&mut self, rhs: Quaternion)

Performs the += operation.

impl Clone for Quaternion

fn clone(&self) -> Quaternion

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Quaternion

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Div<Quaternion> for f32

type Output = Quaternion

The resulting type after applying the / operator.

fn div(self, rhs: Quaternion) -> Self::Output

Performs the / operation.

impl Div<Quaternion> for i32

type Output = Quaternion

The resulting type after applying the / operator.

fn div(self, rhs: Quaternion) -> Self::Output

Performs the / operation.

impl Div<f32> for Quaternion

type Output = Quaternion

The resulting type after applying the / operator.

fn div(self, rhs: f32) -> Self::Output

Performs the / operation.

impl Div<i32> for Quaternion

type Output = Quaternion

The resulting type after applying the / operator.

fn div(self, rhs: i32) -> Self::Output

Performs the / operation.

impl Div for Quaternion

type Output = Quaternion

The resulting type after applying the / operator.

fn div(self, rhs: Quaternion) -> Self::Output

Performs the / operation.

impl DivAssign<f32> for Quaternion

fn div_assign(&mut self, rhs: f32)

Performs the /= operation.

impl DivAssign<i32> for Quaternion

fn div_assign(&mut self, rhs: i32)

Performs the /= operation.

impl Mul<Quaternion> for f32

type Output = Quaternion

The resulting type after applying the * operator.

fn mul(self, rhs: Quaternion) -> Self::Output

Performs the * operation.

impl Mul<Quaternion> for i32

type Output = Quaternion

The resulting type after applying the * operator.

fn mul(self, rhs: Quaternion) -> Self::Output

Performs the * operation.

impl Mul<Vector2> for Quaternion

type Output = Vector2

The resulting type after applying the * operator.

fn mul(self, rhs: Vector2) -> Self::Output

Performs the * operation.

impl Mul<Vector3> for Quaternion

type Output = Vector3

The resulting type after applying the * operator.

fn mul(self, rhs: Vector3) -> Self::Output

Performs the * operation.

impl Mul<f32> for Quaternion

type Output = Quaternion

The resulting type after applying the * operator.

fn mul(self, rhs: f32) -> Self::Output

Performs the * operation.

impl Mul<i32> for Quaternion

type Output = Quaternion

The resulting type after applying the * operator.

fn mul(self, rhs: i32) -> Self::Output

Performs the * operation.

impl Mul for Quaternion

type Output = Quaternion

The resulting type after applying the * operator.

fn mul(self, rhs: Quaternion) -> Self::Output

Performs the * operation.

impl MulAssign<f32> for Quaternion

fn mul_assign(&mut self, rhs: f32)

Performs the *= operation.

impl MulAssign<i32> for Quaternion

fn mul_assign(&mut self, rhs: i32)

Performs the *= operation.

impl Neg for Quaternion

type Output = Quaternion

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl PartialEq for Quaternion

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Sub for Quaternion

type Output = Quaternion

The resulting type after applying the - operator.

fn sub(self, rhs: Quaternion) -> Self::Output

Performs the - operation.

impl SubAssign for Quaternion

fn sub_assign(&mut self, rhs: Quaternion)

Performs the -= operation.

impl Copy for Quaternion

impl Eq for Quaternion

impl Send for Quaternion

impl Sync for Quaternion