vqm 0.1.1

A vector, quaternion, and matrix library targeted at embedded systems and robotics.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

# `vqm` Rust Crate<br>![license](https://img.shields.io/badge/license-MIT-green) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![open source](https://badgen.net/badge/open/source/blue?icon=github)

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](https://en.wikipedia.org/wiki/Quaternion): `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](https://doc.rust-lang.org/core/simd/index.html), which requires the nightly compiler, since it is still
unstable in rust.

This can be invoked using `rustup`, eg:

```sh
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:

```sh
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.

[ARCHITECTURE.md]: ARCHITECTURE.md

## Original implementation

I originally implemented this crate as a C++ library:
[Library-VectorQuaternionMatrix](https://github.com/martinbudden/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](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option.