num-quaternion

Quaternions for Rust.

num-quaternion is a Rust library designed for robust, efficient and easy to use quaternion arithmetic and operations. Quaternions are used extensively in computer graphics, robotics, and physics for representing rotations and orientations.

Features

• Basic Quaternion Operations: Addition, subtraction, multiplication, division, and conjugation.
• Unit Quaternions: Special support for unit quaternions with optimized operations.
• Conversion Functions: Convert to/from Euler angles, rotation vectors, and more.
• Interpolation: Spherical linear interpolation (SLERP) for smooth rotations.
• Interoperability: Works with the serde and the rand crates.
• Comprehensive Documentation: Detailed documentation with examples to help you get started quickly.

Installation

Add num-quaternion to your Cargo.toml:

[dependencies]
num-quaternion = "1.0.2"

For #![no_std] environments, disable the default std feature and enable libm to benefit from the advanced mathematical functions of num-quaternion:

[dependencies]
num-quaternion = { version = "1.0.2", default-features = false, features = ["libm"] }

Then, include it in your crate:

use num_quaternion::{Quaternion, UnitQuaternion, Q32, Q64, UQ32, UQ64};

To serialize or deserialize Quaternions with serde, or to randomly sample UnitQuaternions using the rand crate, enable the respective serde or rand feature.

Usage

Creating Quaternions

// Create a quaternion with explicit components
let q1 = Q32::new(1.0, 2.0, 3.0, 4.0);  // = 1 + 2i + 3j + 4k

// Create a quaternion using shorthand notation
let q2 = 1.0 + Q32::I;  // = 1 + i

Basic Operations

let q3 = q1 + q2;        // Quaternion addition
let q4 = q1 * q2;        // Quaternion multiplication
let q_conj = q1.conj();  // Quaternion conjugation

Unit Quaternions

let uq1 = q1.normalize().expect("Normalization failed"); // Normalize quaternion
let uq2 = UQ32::I;  // Unit quaternion representing the imaginary unit

Conversion Functions

// From Euler angles
let (roll, pitch, yaw) = (1.5, 1.0, 3.0);
let uq = UnitQuaternion::from_euler_angles(roll, pitch, yaw);

// To Euler angles
let euler_angles = uq.to_euler_angles();

// From rotation vector
let rotation_vector = [1.0, 0.0, 0.0]; // x axis rotation, 1 radian
let uq = UnitQuaternion::from_rotation_vector(&rotation_vector);

// To rotation vector
let rotation_vector = uq.to_rotation_vector();

Spherical Linear Interpolation (SLERP)

let uq1 = UQ32::ONE;  // Create a unit quaternion
let uq2 = UQ32::I;    // Create another unit quaternion
let interpolated = uq1.slerp(&uq2, 0.3);  // Perform SLERP with t=0.3

Documentation

Comprehensive documentation with examples can be found on docs.rs.

For detailed design principles and the error handling strategy see the Design Rationale.

Detailed release notes are provided in RELEASES.md.

Contributing

Contributions are welcome! Please fork the repository and submit pull requests. By contributing, you agree that your contributions will be dual-licensed under the Apache-2.0 and MIT licenses.

If you have any questions or need help, feel free to open an issue on GitHub.

Further instructions can be found in the CONTRIBUTING.md guidelines.

License

Licensed under either of

• Apache License, Version 2.0
• MIT license

at your option.

Acknowledgements

Special thanks to @cuviper for the num-complex crate which served as a model for this crate. num-quaternion is designed to integrate seamlessly with the rust-num family of crates.