Struct Quaternion

Source

pub struct Quaternion {
    pub w: f64,
    pub x: f64,
    pub y: f64,
    pub z: f64,
}

Expand description

A quaternion representing a rotation in 3D space.

With the optional serde feature, this type implements Serialize and Deserialize (the docs.rs listing cannot banner derive-generated impls).

Fields§

§w: f64

The scalar (real) part of the quaternion.

§x: f64

The x component of the vector part.

§y: f64

The y component of the vector part.

§z: f64

The z component of the vector part.

Implementations§

Source §

impl Quaternion

Source

pub const fn from_wxyz(w: f64, x: f64, y: f64, z: f64) -> Quaternion

Creates a quaternion from its w, x, y, and z components.

The scalar part w comes first — the name spells the order out, because the other common convention puts it last and a silently swapped w is a valid quaternion describing a different rotation. No normalization is performed; rotations are expected to be unit quaternions, so call Quaternion::normalize if the components do not already form one.

§Examples

use transforms::geometry::Quaternion;

let q = Quaternion::from_wxyz(1.0, 0.0, 0.0, 0.0);
assert_eq!(q, Quaternion::identity());

Source

pub const fn identity() -> Quaternion

Creates an identity quaternion representing no rotation.

Returns a quaternion with w=1 and x=y=z=0, which represents the identity rotation (i.e., no rotation at all).

§Examples

use transforms::geometry::Quaternion;

let q = Quaternion::identity();
assert_eq!(q.w, 1.0);
assert_eq!(q.x, 0.0);
assert_eq!(q.y, 0.0);
assert_eq!(q.z, 0.0);

Source

pub fn conjugate(self) -> Quaternion

Returns the conjugate of the quaternion.

§Examples

use transforms::geometry::Quaternion;

let q = Quaternion::from_wxyz(1.0, 2.0, 3.0, 4.0);
assert_eq!(q.conjugate(), Quaternion::from_wxyz(1.0, -2.0, -3.0, -4.0));

Source

pub fn normalize(self) -> Result<Quaternion, QuaternionError>

Normalizes the quaternion to unit length.

The intermediate norm — the square root of the sum of squares — sets both limits. A component beyond roughly 1.3e154, the square root of f64::MAX, squares to infinity (reported as NonFinite), and a norm below f64::EPSILON (about 2.2e-16) counts as zero (reported as ZeroLengthNormalization). That threshold is exclusive: a norm of exactly f64::EPSILON still normalizes.

§Errors

Returns QuaternionError::ZeroLengthNormalization if the norm is below f64::EPSILON, and QuaternionError::NonFinite if any component is NaN or the sum of squares overflows.

§Examples

use transforms::{errors::QuaternionError, geometry::Quaternion};

let q = Quaternion::from_wxyz(1.0, 2.0, 3.0, 4.0);
let normalized = q.normalize().unwrap();
assert!((normalized.norm() - 1.0).abs() < f64::EPSILON);

// The zero threshold is `f64::EPSILON` on the norm, not a
// rotation-scale epsilon: this one is far below rotation scale and
// still normalizes.
let at_threshold = Quaternion::from_wxyz(f64::EPSILON, 0.0, 0.0, 0.0);
assert_eq!(at_threshold.normalize().unwrap(), Quaternion::identity());

let below_threshold = Quaternion::from_wxyz(f64::EPSILON / 2.0, 0.0, 0.0, 0.0);
assert!(matches!(
    below_threshold.normalize(),
    Err(QuaternionError::ZeroLengthNormalization)
));

let zero_q = Quaternion::from_wxyz(0.0, 0.0, 0.0, 0.0);
assert!(matches!(
    zero_q.normalize(),
    Err(QuaternionError::ZeroLengthNormalization)
));

Source

pub fn norm(self) -> f64

Computes the norm (magnitude) of the quaternion.

§Examples

use transforms::geometry::Quaternion;

let q = Quaternion::from_wxyz(1.0, 1.0, 1.0, 1.0);
assert_eq!(q.norm(), 2.0);

Source

pub fn rotate_vector(self, v: Vector3) -> Vector3

Rotates a vector by the quaternion.

The vector is treated as a pure quaternion with a real part of zero.

§Examples

use transforms::geometry::{Quaternion, Vector3};

let q = Quaternion::from_wxyz(
    (core::f64::consts::PI / 4.0).cos(),
    0.0,
    0.0,
    (core::f64::consts::PI / 4.0).sin(),
);
let v = Vector3::new(1.0, 0.0, 0.0);
assert_relative_eq!(q.rotate_vector(v), Vector3::new(0.0, 1.0, 0.0));

Source

pub fn slerp(self, other: Quaternion, t: f64) -> Quaternion

Performs spherical linear interpolation (slerp) between two quaternions.

Interpolates between self and other by the factor t, which is clamped to [0.0, 1.0] — there is no extrapolation, matching the crate-wide policy. Infinite factors saturate to the corresponding endpoint; a NaN factor yields a NaN result.

The trigonometry runs through libm whether or not std is enabled, so the same operands yield bit-identical results in both feature modes.

§Examples

use transforms::geometry::Quaternion;

let q1 = Quaternion::identity();
let q2 = Quaternion::from_wxyz(0.0, 1.0, 0.0, 0.0);
let result = q1.slerp(q2, 0.5);
let expected = Quaternion::from_wxyz((0.5_f64).sqrt(), (0.5_f64).sqrt(), 0.0, 0.0);
assert_relative_eq!(result.w, expected.w, epsilon = f64::EPSILON);
assert_relative_eq!(result.x, expected.x, epsilon = f64::EPSILON);
assert_relative_eq!(result.y, expected.y, epsilon = f64::EPSILON);
assert_relative_eq!(result.z, expected.z, epsilon = f64::EPSILON);