Struct QuaternionSpace 

pub struct QuaternionSpace { /* private fields */ }

A spatial context representing 3D orientation using unit quaternions.

QuaternionSpace models the rotational state of an object in 3D space using a quaternion [w, x, y, z], which encodes a rotation around an axis without the risk of gimbal lock. This is especially useful in applications that require smooth, continuous rotation or orientation tracking.

The quaternion should be normalized (unit length) to represent a valid rotation.

Fields

• id: A unique identifier for the orientation context (e.g., sensor ID)
• quat: A 4-element array representing the quaternion in [w, x, y, z] order:
  • w: scalar component (cos(θ/2))
  • x, y, z: vector part representing the axis of rotation (unit vector scaled by sin(θ/2))

Coordinate Index Mapping

When used with the Coordinate trait, the following index mapping applies:

• 0 => w
• 1 => x
• 2 => y
• 3 => z

Background

Quaternions are an extension of complex numbers used to represent rotations in three-dimensional space. Unlike Euler angles or axis-angle representations, quaternions avoid singularities (gimbal lock), allow smooth interpolation (slerp), and are computationally stable for tracking cumulative orientation over time.

Quaternions are commonly used in:

• Aerospace and inertial navigation (IMUs, magnetometers, gyroscopes)
• Robotics and drone control
• Virtual and augmented reality (VR/AR head tracking)
• 3D game engines and computer graphics

Example

use deep_causality::*;

// Represents a 90-degree rotation around the Z-axis
let q = QuaternionSpace::new(1, std::f64::consts::FRAC_1_SQRT_2, 0.0, 0.0, std::f64::consts::FRAC_1_SQRT_2);

println!("{}", q);
assert_eq!(q.dimension(), 4);
assert!((q.distance(&q) - 0.0).abs() < 1e-9);

Notes

• All components are assumed to be in floating-point units (unitless)
• Input quaternions should be normalized before use (||q|| = 1.0)
• For multi-sensor fusion, make sure quaternions follow the same handedness convention (e.g., right-handed)

Implementations

impl QuaternionSpace

pub fn w(&self) -> f64

pub fn x(&self) -> f64

pub fn y(&self) -> f64

pub fn z(&self) -> f64

impl QuaternionSpace

pub fn new(id: u64, w: f64, x: f64, y: f64, z: f64) -> Self

Trait Implementations

impl Adjustable<f64> for QuaternionSpace

fn update<const W: usize, const H: usize, const D: usize, const C: usize>( &mut self, array_grid: &ArrayGrid<f64, W, H, D, C>, ) -> Result<(), UpdateError>

The default implementation does nothing to keep update optional. Override this method to implement a node update when needed. For a sample implementation, see src/types/context_types/node_types_adjustable

fn adjust<const W: usize, const H: usize, const D: usize, const C: usize>( &mut self, array_grid: &ArrayGrid<f64, W, H, D, C>, ) -> Result<(), AdjustmentError>

The default implementation does nothing to keep adjustment optional. Override this method to implement a node adjustment when needed. Depending on the type of node adjustment, select a 1, 2,3, or 4 dimensional array grid that contains the transformation data to apply to the node. For a sample implementation, see src/types/context_types/node_types_adjustable

impl Clone for QuaternionSpace

fn clone(&self) -> QuaternionSpace

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Coordinate<f64> for QuaternionSpace

fn dimension(&self) -> usize

Returns the number of dimensions in the coordinate system (always 4).

fn coordinate(&self, index: usize) -> Result<&f64, IndexError>

Returns a reference to the coordinate value at the specified index.

Index Mapping

• 0 => w
• 1 => x
• 2 => y
• 3 => z

Errors

Returns IndexError if the index is out of bounds.

impl Debug for QuaternionSpace

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

Formats the value using the given formatter.

impl Display for QuaternionSpace

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

Formats the value using the given formatter.

impl Identifiable for QuaternionSpace

fn id(&self) -> u64

impl Metric<f64> for QuaternionSpace

fn distance(&self, other: &Self) -> f64

Computes the Euclidean distance between two quaternions in 4D space.

The quaternion is treated as a 4D vector in ℝ⁴ with components [w, x, y, z]. The standard Euclidean norm is applied:

d(q₁, q₂) = √[(w₁ - w₂)² + (x₁ - x₂)² + (y₁ - y₂)² + (z₁ - z₂)²]

This implementation is appropriate when:

• Quaternions are treated as general 4D points (not necessarily normalized).
• You need straight-line (chordal) distance in Euclidean space.

Note

If the quaternions represent unit quaternions (i.e., orientations), and you wish to compute the angular distance between them, consider overriding this method with:

let dot = q1.w * q2.w + q1.x * q2.x + q1.y * q2.y + q1.z * q2.z;
let theta = 2.0 * dot.abs().acos(); // Angular distance in radians

This version reflects the minimal rotation angle between two orientations on the unit hypersphere.

impl PartialEq for QuaternionSpace

fn eq(&self, other: &QuaternionSpace) -> 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 Spatial<f64> for QuaternionSpace

impl StructuralPartialEq for QuaternionSpace