Struct Quaternion

Source
pub struct Quaternion { /* private fields */ }
Expand description

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

Implementations§

Source§

impl Quaternion

Constructors

Source

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());
Source

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());
Source

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());
Source

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());
Source

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);
Source

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);
Source§

impl Quaternion

Properties

Source

pub fn a(&self) -> f32

Gets the real component of the quaternion

Returns: Returns the real component of the quaternion

Source

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

Sets the real component of the quaternion

  • value: The value to set the real component to
Source

pub fn b(&self) -> f32

Gets the complex i component of the quaternion

Returns: Returns the complex i component of the quaternion

Source

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
Source

pub fn c(&self) -> f32

Gets the complex j component of the quaternion

Returns: Returns the complex j component of the quaternion

Source

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
Source

pub fn d(&self) -> f32

Gets the complex k component of the quaternion

Returns: Returns the complex k component of the quaternion

Source

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
Source

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);
Source

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);
Source

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);
Source

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);
Source

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());
Source

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());
Source§

impl Quaternion

Public Methods

Source

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());
Source

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());
Source

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));
Source

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());
Source

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());
Source

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());
Source

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());
Source

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());
Source

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);
Source

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§

Source§

impl Add for Quaternion

Source§

type Output = Quaternion

The resulting type after applying the + operator.
Source§

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

Performs the + operation. Read more
Source§

impl AddAssign for Quaternion

Source§

fn add_assign(&mut self, rhs: Quaternion)

Performs the += operation. Read more
Source§

impl Clone for Quaternion

Source§

fn clone(&self) -> Quaternion

Returns a copy of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for Quaternion

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Div<Quaternion> for f32

Source§

type Output = Quaternion

The resulting type after applying the / operator.
Source§

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

Performs the / operation. Read more
Source§

impl Div<Quaternion> for i32

Source§

type Output = Quaternion

The resulting type after applying the / operator.
Source§

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

Performs the / operation. Read more
Source§

impl Div<f32> for Quaternion

Source§

type Output = Quaternion

The resulting type after applying the / operator.
Source§

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

Performs the / operation. Read more
Source§

impl Div<i32> for Quaternion

Source§

type Output = Quaternion

The resulting type after applying the / operator.
Source§

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

Performs the / operation. Read more
Source§

impl Div for Quaternion

Source§

type Output = Quaternion

The resulting type after applying the / operator.
Source§

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

Performs the / operation. Read more
Source§

impl DivAssign<f32> for Quaternion

Source§

fn div_assign(&mut self, rhs: f32)

Performs the /= operation. Read more
Source§

impl DivAssign<i32> for Quaternion

Source§

fn div_assign(&mut self, rhs: i32)

Performs the /= operation. Read more
Source§

impl Mul<Quaternion> for f32

Source§

type Output = Quaternion

The resulting type after applying the * operator.
Source§

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

Performs the * operation. Read more
Source§

impl Mul<Quaternion> for i32

Source§

type Output = Quaternion

The resulting type after applying the * operator.
Source§

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

Performs the * operation. Read more
Source§

impl Mul<Vector2> for Quaternion

Source§

type Output = Vector2

The resulting type after applying the * operator.
Source§

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

Performs the * operation. Read more
Source§

impl Mul<Vector3> for Quaternion

Source§

type Output = Vector3

The resulting type after applying the * operator.
Source§

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

Performs the * operation. Read more
Source§

impl Mul<f32> for Quaternion

Source§

type Output = Quaternion

The resulting type after applying the * operator.
Source§

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

Performs the * operation. Read more
Source§

impl Mul<i32> for Quaternion

Source§

type Output = Quaternion

The resulting type after applying the * operator.
Source§

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

Performs the * operation. Read more
Source§

impl Mul for Quaternion

Source§

type Output = Quaternion

The resulting type after applying the * operator.
Source§

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

Performs the * operation. Read more
Source§

impl MulAssign<f32> for Quaternion

Source§

fn mul_assign(&mut self, rhs: f32)

Performs the *= operation. Read more
Source§

impl MulAssign<i32> for Quaternion

Source§

fn mul_assign(&mut self, rhs: i32)

Performs the *= operation. Read more
Source§

impl Neg for Quaternion

Source§

type Output = Quaternion

The resulting type after applying the - operator.
Source§

fn neg(self) -> Self::Output

Performs the unary - operation. Read more
Source§

impl PartialEq for Quaternion

Source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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

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

impl Sub for Quaternion

Source§

type Output = Quaternion

The resulting type after applying the - operator.
Source§

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

Performs the - operation. Read more
Source§

impl SubAssign for Quaternion

Source§

fn sub_assign(&mut self, rhs: Quaternion)

Performs the -= operation. Read more
Source§

impl Copy for Quaternion

Source§

impl Eq for Quaternion

Source§

impl Send for Quaternion

Source§

impl Sync for Quaternion

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.