Struct Quaternion 

#[repr(C)]
pub struct Quaternion {
    pub x: f32,
    pub y: f32,
    pub z: f32,
    pub w: f32,
}

Represents a quaternion for efficient 3D rotations.

Quaternions are a four-dimensional complex number system that can represent rotations in 3D space. They are generally more efficient and numerically stable than rotation matrices, avoiding issues like gimbal lock.

A quaternion is stored as (x, y, z, w), where [x, y, z] is the “vector” part and w is the “scalar” part. For representing rotations, it should be a “unit quaternion” where x² + y² + z² + w² = 1.

Examples

use khora_core::math::{Quaternion, Vec3};
use std::f32::consts::FRAC_PI_2;

// A quarter-turn about the Y axis maps +Z onto +X.
let yaw = Quaternion::from_axis_angle(Vec3::Y, FRAC_PI_2);
let rotated = yaw * Vec3::Z;
assert!((rotated - Vec3::X).length() < 1e-5);

// Composing rotations is quaternion multiplication; the identity is a no-op.
let combined = yaw * Quaternion::IDENTITY;
assert!((combined * Vec3::Z - Vec3::X).length() < 1e-5);

// `slerp` blends along the shortest arc; halfway is a 45° turn.
let half = Quaternion::slerp(Quaternion::IDENTITY, yaw, 0.5);
let expected = Quaternion::from_axis_angle(Vec3::Y, FRAC_PI_2 / 2.0);
assert!((half * Vec3::Z - expected * Vec3::Z).length() < 1e-5);

Fields

x: f32

The x component of the vector part.

y: f32

The y component of the vector part.

z: f32

The z component of the vector part.

w: f32

The scalar (real) part.

Implementations

impl Quaternion

pub const IDENTITY: Quaternion

The identity quaternion, representing no rotation.

pub fn new(x: f32, y: f32, z: f32, w: f32) -> Quaternion

Creates a new quaternion from its raw components.

Note: This does not guarantee a unit quaternion. For creating rotations, prefer using from_axis_angle or other rotation-specific constructors.

pub fn from_axis_angle(axis: Vec3, angle_radians: f32) -> Quaternion

Creates a quaternion representing a rotation around a given axis by a given angle.

Arguments

• axis: The axis of rotation. It is recommended to pass a normalized vector.
• angle_radians: The angle of rotation in radians.

pub fn from_rotation_matrix(m: &Mat4) -> Quaternion

Creates a quaternion from a 4x4 rotation matrix.

This method only considers the upper 3x3 part of the matrix for the conversion.

pub fn magnitude_squared(&self) -> f32

Calculates the squared length (magnitude) of the quaternion.

pub fn magnitude(&self) -> f32

Calculates the length (magnitude) of the quaternion.

pub fn normalize(&self) -> Quaternion

Returns a normalized version of the quaternion with a length of 1. If the quaternion has a near-zero magnitude, it returns the identity quaternion.

pub fn conjugate(&self) -> Quaternion

Computes the conjugate of the quaternion, which negates the vector part.

pub fn inverse(&self) -> Quaternion

Computes the inverse of the quaternion. For a unit quaternion, the inverse is equal to its conjugate.

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

Computes the dot product of two quaternions.

pub fn rotate_vec3(&self, v: Vec3) -> Vec3

Rotates a 3D vector by this quaternion.

pub fn slerp(start: Quaternion, end: Quaternion, t: f32) -> Quaternion

Performs a Spherical Linear Interpolation (Slerp) between two quaternions.

Slerp provides a smooth, constant-speed interpolation between two rotations, following the shortest path on the surface of a 4D sphere.

• t - The interpolation factor, clamped to the [0.0, 1.0] range.

pub fn to_euler_xyz(&self) -> (f32, f32, f32)

Converts this quaternion to Euler angles in XYZ (pitch, yaw, roll) order.

Returns (x, y, z) angles in radians.

• x = pitch (rotation around X axis)
• y = yaw (rotation around Y axis)
• z = roll (rotation around Z axis)

pub fn from_euler_xyz(x: f32, y: f32, z: f32) -> Quaternion

Creates a quaternion from Euler angles in XYZ order.

Arguments

• x — pitch in radians (rotation around X axis)
• y — yaw in radians (rotation around Y axis)
• z — roll in radians (rotation around Z axis)

Trait Implementations

impl Add for Quaternion

fn add(self, rhs: Quaternion) -> <Quaternion as Add>::Output

Adds two quaternions component-wise. Note: This is not a standard rotation operation.

type Output = Quaternion

The resulting type after applying the + operator.

impl<'__de, __Context> BorrowDecode<'__de, __Context> for Quaternion

fn borrow_decode<__D>(decoder: &mut __D) -> Result<Quaternion, DecodeError>

where __D: BorrowDecoder<'__de, Context = __Context>,

Attempt to decode this type with the given BorrowDecode.

impl Clone for Quaternion

fn clone(&self) -> Quaternion

Returns a duplicate 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<(), Error>

Formats the value using the given formatter.

impl<__Context> Decode<__Context> for Quaternion

fn decode<__D>(decoder: &mut __D) -> Result<Quaternion, DecodeError>

where __D: Decoder<Context = __Context>,

Attempt to decode this type with the given Decode.

impl Default for Quaternion

fn default() -> Quaternion

Returns the identity quaternion, representing no rotation.

impl<'de> Deserialize<'de> for Quaternion

fn deserialize<__D>( __deserializer: __D, ) -> Result<Quaternion, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Encode for Quaternion

fn encode<__E>(&self, encoder: &mut __E) -> Result<(), EncodeError>

where __E: Encoder,

Encode a given type.

impl Mul<Vec3> for Quaternion

fn mul(self, rhs: Vec3) -> <Quaternion as Mul<Vec3>>::Output

Rotates a Vec3 by this quaternion.

type Output = Vec3

The resulting type after applying the * operator.

impl Mul<f32> for Quaternion

fn mul(self, scalar: f32) -> <Quaternion as Mul<f32>>::Output

Scales all components of the quaternion by a scalar.

type Output = Quaternion

The resulting type after applying the * operator.

impl Mul for Quaternion

fn mul(self, rhs: Quaternion) -> <Quaternion as Mul>::Output

Combines two rotations using the Hamilton product. Note that quaternion multiplication is not commutative.

type Output = Quaternion

The resulting type after applying the * operator.

impl MulAssign for Quaternion

fn mul_assign(&mut self, rhs: Quaternion)

Combines this rotation with another.

impl Neg for Quaternion

fn neg(self) -> <Quaternion as Neg>::Output

Negates all components of the quaternion.

type Output = Quaternion

The resulting type after applying the - operator.

impl PartialEq for Quaternion

fn eq(&self, other: &Quaternion) -> 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 Serialize for Quaternion

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Sub for Quaternion

fn sub(self, rhs: Quaternion) -> <Quaternion as Sub>::Output

Subtracts two quaternions component-wise.

type Output = Quaternion

The resulting type after applying the - operator.

impl Copy for Quaternion

impl StructuralPartialEq for Quaternion