31 releases
new 0.2.28 | Sep 7, 2024 |
---|---|
0.2.27 | Sep 6, 2024 |
0.2.26 | Aug 29, 2024 |
0.2.21 | Jul 31, 2024 |
0.1.2 | May 25, 2024 |
#79 in Math
710 downloads per month
225KB
4.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.28"
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.28", 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.
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
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.
Dependencies
~140–570KB
~11K SLoC