quaternion-core 0.6.0

Provides quaternion operations and interconversion with several attitude representations.
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
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

# quaternion-core

[![Latest version](https://img.shields.io/crates/v/quaternion-core?color=orange&style=flat-square)](https://crates.io/crates/quaternion-core)
[![Documentation](https://img.shields.io/docsrs/quaternion-core/latest?color=brightgreen&style=flat-square&logo=docs.rs)](https://docs.rs/quaternion-core)
![Minimum rustc](https://img.shields.io/badge/rustc-1.60+-red.svg?style=flat-square&logo=rust)
![License](https://img.shields.io/crates/l/quaternion-core?color=blue&style=flat-square)

Quaternion library written in Rust.

This crate provides Quaternion operations and interconversion with several rotation 
representations as generic functions (supports `f32` & `f64`).

Additionally, it also works in a `no_std` environment!

## Usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
quaternion-core = "0.6"
```

For use in a `no_std` environment:

```toml
[dependencies.quaternion-core]
version = "0.6"
default-features = false
features = ["libm"]
```

## Conversion

![Interconversion with several rotation expressions.](https://raw.githubusercontent.com/HamaguRe/quaternion-core/016f95eef2bca3f43ae77306da64e85c64c30bb7/conversion.png)

This crate provides functions to convert between quaternions and several rotation
representations (as shown in the image above).

In particular, for Euler angles, it is possible to interconversion with 24 different 
euler angles (12 each of `Intrinsic` and `Extrinsic`) is possible!!

## Features

### libm

If you set `default-features=false` (do not import `std`), you must enable this feature.

In this case, mathematical functions (e.g. `sin`, `cos`, `sqrt` ...) are provided by 
[libm](https://crates.io/crates/libm) crate.

### fma

When this feature is enabled, the 
[mul_add](https://docs.rs/num-traits/0.2.15/num_traits/float/trait.Float.html#tymethod.mul_add) 
method will be used internally as much as possible.
That is, `(s * a) + b` will be expanded as `s.mul_add(a, b)` at compile time.

This crate uses the `mul_add` method mainly to improve calculation speed, but if the CPU does 
not support the `FMA` (Fused Multiply-Add) instruction or if the `libm` feature is 
enabled, then the calculation is performed by the software implementation.
In this case, it may be rather slower than if the `fma` feature is not enabled.

### norm-sqrt

When this feature is enabled, the default `norm(a)` implementation is compiled with 
`dot(a, a).sqrt()` instead.

By default, the `norm(a)` function is implemented in such a way that overflow and 
underflow are less likely to occur than with `dot(a, a).sqrt()`. However, if extremely 
large values are not input and underflow is not that much of a concern, 
`dot(a, a).sqrt()` is sufficient (and `dot(a, a).sqrt()` is faster than the default implementation in most cases).

### serde-serialize

When this feature is enabled, `RotationSequence` and `RotationType` will both
implement `serde::Serialize` and `serde::Deserialize`.

## Example

```rust
use quaternion_core as quat;

const PI: f64 = std::f64::consts::PI;
const EPSILON: f64 = 1e-12;

fn main() {
    // Generates a quaternion representing the
    // rotation of π/2[rad] around the y-axis.
    let q = quat::from_axis_angle([0.0, 1.0, 0.0], PI/2.0);

    // Rotate the point.
    let r = quat::point_rotation(q, [2.0, 2.0, 0.0]);

    // Check if the calculation is correct.
    let diff = quat::sub([0.0, 2.0, -2.0], r);
    for val in diff {
        assert!( val.abs() < EPSILON );
    }
}
```

## Development concept

In creating this crate, I tried to keep the implementation simple and practical.

All functions are implemented in such a way that the computational cost is as small as 
possible (but not too complex to implement), which is a great advantage for everyone.

Also, since I started creating this crate to experiment with attitude estimation, many parts 
were implemented with the intention of running on a microcontroller (e.g. the `norm-sqrt` feature).

## Releases

Release notes are available in [RELEASES.md](RELEASES.md).

## License

Licensed under either of
[Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)
or
[MIT License](https://opensource.org/licenses/MIT)
at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted 
for inclusion in the work by you, as defined in the Apache-2.0 license, shall 
be dual licensed as above, without any additional terms or conditions.