## no-std num-quaternion

Quaternion numbers implementation for Rust

### 20 releases

 new 0.2.17 Jul 21, 2024 Jul 16, 2024 Jun 26, 2024 May 25, 2024

#86 in Math

MIT/Apache

165KB
3.5K SLoC

# 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.
• Comprehensive Documentation: Detailed documentation with examples to help you get started quickly.

## Installation

Add `num-quaternion` to your `Cargo.toml`:

``````[dependencies]
num-quaternion = "0.2.17"
``````

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 = "0.2.17", default-features = false, features = ["libm"] }
``````

Then, include it in your crate:

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

## 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.

## Releases

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.

## 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.

~140–435KB