vqm Rust Crate

A vector, quaternion, and matrix (VQM) library targeted at embedded systems and robotics. (In particular stabilized vehicles including self-balancing robots and aircraft).

This crate is no_std, that it does not link to the standard library and so does not depend on an operating system and uses no allocation. This means it is suitable for embedded system.

Overview

Vectors have 2D, 3D, and 4D versions.

Matrices have 2x2 and 3x3 versions.

Each type has versions for f32 and f64. So we have:

1. 2D vectors: Vector2df32, Vector2df64
2. 3D vectors: Vector3df32, Vector3df64
3. 4D vectors: Vector4df32, Vector4df64
4. quaternions: Quaternionf32, Quaternionf64
5. 2x2 matrices: Matrix2x2f32, Matrix2x2f64
6. 3x3 matrices: Matrix3x3f32,Matrix3x3f64

The 3D vector additionally has i16 and i32 versions: Vector3di16 and Vector3di32.

(Under the hood, types are implemented using generics, so Vector3df32 is actually Vector3d<f32>, but that is transparent to the user.)

Mathematical methods and constants

This crate also provides implementations of the trigonometric methods normally provided by the standard library, namely: sin, cos, sin_cos, tan, asin, acos, atan2. The are provided in method_call syntax, ie x.sin().

The methods sqrt and sqrt_reciprocal are also provided.

The MathConstants trait provides a the standard mathematical constants in a form that can be used in generic code ie T:PI.

SIMD support

SIMD support can be enabled with the simd feature.

It is currently experimental and many of the implementations are naive "placeholder" implementations to be optimized at a later date. These placeholder implementations may be slower than the non-SIMD code, so if you used SIMD make sure you benchmark to show that you are indeed getting a performance improvement.

This uses portable simd, which requires the nightly compiler, since it is still unstable in rust.

This can be invoked using rustup, eg:

rustup run nightly cargo build --features simd --target thumbv8m.main-none-eabi

Struct alignment

By default Vector3df32 is aligned to a 16-byte boundary, and Matrix3x3f32 is aligned to a 32-byte boundary. This can be turned off using the no_align feature flag:

cargo build -features no_align

If no_align is used then SIMD support is not available.

Architecture

See ARCHITECTURE.md for details on vqm's internals.

Original implementation

I originally implemented this crate as a C++ library: Library-VectorQuaternionMatrix.

The capabilities of this crate now exceed those of the original library.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.