Crate vqm 

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, 3x3, 4x4, and 9x9 versions. The 9x9 matrix implementation has been added to support Kalman filters and is incomplete.

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
7. 4x4 matrices: Matrix4x4f32, Matrix4x4f64
8. 9x9 matrices: Matrix9x9f32, Matrix9x9f64 - partial implementation with special functions for Kalman filters.

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.

Structs

KalmanStateVector9

Flattened representation of a 9-element state vector for Kalman filter matrix math.

Matrix2x2

Matrix2x2<T>: 2x2 Matrix of type T.
Aliases Matrix2x2f32 and Matrix2x2f64 are provided.
Matrix2x2f32 uses SIMD accelerations implemented in Matrix2x2Math.
Internal implementation is using a flattened 1-dimensional array: an array of 4 elements stored in row-major order. That is the element m[row][col] is at array position [row * 2 + col], so element m01 is at a[1].

Matrix3x3

Matrix3x3<T>: 3x3 Matrix of type T.
Aliases Matrix3x3f32 and Matrix3x3f64 are provided.
Internal implementation is a flattened 3x3 matrix: an array of 9 elements stored in row-major order. That is the element m[row][col] is at array position [row * 3 + col], so element m12 is at a[5].

Matrix4x4

Matrix4x4<T>: 4x4 Matrix of type T.
Aliases Matrix4x4f32 and Matrix4x4f64 are provided.
Internal implementation is a flattened 4x4 matrix: an array of 9 elements stored in row-major order. That is the element m[row][col] is at array position [row * 3 + col], so element m12 is at a[5].

Matrix9x9

Matrix9x9<T>: 9x9 Matrix of type T.
Provided to support Kalman filter matrix math and so not all functions are provided.
In particular matrix by matrix multiply, determinant, adjugate, and inverse are not provided.
Functions to extract and utilize 3x3 sub-matrices are provided.
Aliases Matrix9x9f32 and Matrix9x9f64 are provided.
Internal implementation is a flattened 9x9 matrix: an array of 9 elements stored in row-major order. That is the element m[row][col] is at array position [row * 3 + col], so element m12 is at a[5].

Quaternion

Quaternion<T>: quaternion type T.
Aliases Quaternion32 and Quaternionf64 are provided.
Quaternionf32 uses SIMD accelerations implemented in QuaternionMath.

RollPitch

Roll and Pitch bundled for convenience.

RollPitchYaw

Roll, Pitch, and Yaw bundled for convenience.

Vector2d

Vector2d<T>: 2D vector of type T.
Aliases Vector2df32 and Vector2df64 are provided.
Vector2df32 uses SIMD accelerations implemented in Vector2dMath.

Vector3d

Vector3d<T>: 3D vector of type T.
Aliases Vector3df32 and Vector2df64 are provided.
Vector3df32 uses SIMD accelerations implemented in Vector3dMath.

Vector4d

Vector4d<T>: 3D vector of type T.
Aliases Vector4df32 and Vector4df64 are provided.
Vector4df32 uses SIMD accelerations implemented in Vector4dMath.

Traits

MathConstants

Math constants for use in generic code, eg T:PI, T:SQRT_2 etc.

Matrix2x2Math

Math functions for Matrix2x2, using SIMD accelerations for f32.

Matrix3x3Math

Math functions for Matrix3x3, using SIMD accelerations for f32.

Matrix4x4Math

Math functions for Matrix4x4, using SIMD accelerations for f32.

Matrix9x9Math

Math functions for Matrix9x9.

QuaternionMath

Math functions for Quaternion, using SIMD accelerations for f32.

SqrtMethods

no_std implementations of sqrt and sqrt_reciprocal in method call syntax
ie x.sqrt(), x.sqrt_reciprocal().

TrigonometricMethods

no_std implementations of trigonometric functions in method call syntax
eg x.sin(), x.cos() etc.

Vector2dMath

Math functions for Vector2d, using SIMD accelerations for f32.

Vector3dMath

Math functions for Vector3d, using SIMD accelerations for f32.

Vector4dMath

Math functions for Vector4d, using SIMD accelerations for f32.

Type Aliases

KalmanStateVector9f32

Kalman state vector of f32 values

KalmanStateVector9f64

Kalman tate vector of f64 values

Matrix2x2f32

2x2 matrix of f32 values

Matrix2x2f64

2x2 matrix of f64 values

Matrix3x3f32

3x3 matrix of f32 values

Matrix3x3f64

3x3 matrix of f64 values

Matrix4x4f32

4x4 matrix of f32 values

Matrix4x4f64

4x4 matrix of f64 values

Matrix9x9f32

9x9 matrix of f32 values

Matrix9x9f64

9x9 matrix of f64 values

Quaternionf32

Quaternion of f32 values

Quaternionf64

Quaternion of f64 values

RollPitchYawf32

RollPitchYaw struct { roll: f32, pitch: f32, yaw: f32 }

RollPitchYawf64

RollPitchYaw struct { roll: f64, pitch: f64, yaw: f64 }

RollPitchf32

RollPitch struct { roll: f32, pitch: f32 }

RollPitchf64

RollPitch struct { roll: f64, pitch: f64 }

Vector2df32

2-dimensional {x, y} vector of f32 values

Vector2df64

2-dimensional {x, y} vector of f64 values

Vector3df32

3-dimensional {x, y, z} vector of f32 values

Vector3df64

3-dimensional {x, y, z} vector of f64 values

Vector3di16

3-dimensional {x, y, z} vector of i16 values

Vector3di32

3-dimensional {x, y, z} vector of i32 values

Vector4df32

4-dimensional {x, y, z, t} vector of f32 values

Vector4df64

4-dimensional {x, y, z, t} vector of f64 values