Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/ferd36/quaternions

A blazingly fast C++ library to work with quaternions :zap:
https://github.com/ferd36/quaternions
Last synced: about 1 month ago
JSON representation
A blazingly fast C++ library to work with quaternions :zap:
Host: GitHub
URL: https://github.com/ferd36/quaternions
Owner: ferd36
License: mit
Created: 2015-12-14T16:59:58.000Z (almost 9 years ago)
Default Branch: master
Last Pushed: 2024-01-28T13:20:19.000Z (11 months ago)
Last Synced: 2024-08-02T05:11:55.997Z (4 months ago)
Language: C++
Homepage:
Size: 789 KB
Stars: 65
Watchers: 1
Forks: 15
Open Issues: 3
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

awesome-blazingly-fast - quaternions - A blazingly fast C++ library to work with quaternions :zap: (C++)
README

        # Quaternions  [![Build status](https://travis-ci.org/FrankAstier/quaternions.svg?branch=master)](https://travis-ci.org/FrankAstier/quaternions) [![Coverage Status](https://coveralls.io/repos/FrankAstier/quaternions/badge.svg?branch=master&service=github&bust=1)](https://coveralls.io/github/FrankAstier/quaternions?branch=master)

A C++11 library to work with quaternions, as a single header file.

## Introduction

- In mathematics, the quaternions are a number system that extends the complex numbers.

  They were first described by Irish mathematician William Rowan Hamilton in 1843 and applied to mechanics

  in three-dimensional space. A feature of quaternions is that multiplication of two quaternions is noncommutative.

  Hamilton defined a quaternion as the quotient of two directed lines in a three-dimensional space or equivalently

  as the quotient of two vectors. Quaternions find uses in both theoretical and applied mathematics, in particular

  for calculations involving three-dimensional rotations such as in three-dimensional computer graphics, computer

  vision and crystallographic texture analysis. In practical applications, they can be used alongside other methods,

  such as Euler angles and rotation matrices, or as an alternative to them, depending on the application.

## Design objectives

- This library was designed to be simple, fast and convenient.

- For simplicity, there is a single(parametric) class, quaternion::Quaternion, that lives in a single header file.

- Computing the power of a quaternion in particular has been optimized to be significantly faster than boost.

- The methods provided have been designed to make it as natural as possible to use quaternion::Quaternion.

## Usage

- include \

- using namespace quaternion;

- To build the unit tests: cmake . ; make OR make -f Makefile.mk

- To make the doc: doxygen Doxyfile.

- The file unit_tests.cpp shows usage examples for all the function in the quaternion namespace.

- The file unit_tests.cpp contains various benchmarks.

## Notes

- Boost provides quaternions at: http://www.boost.org/doc/libs/1_59_0/libs/math/doc/html/quaternions.html

  This implementation is as fast as or faster than Boost. In particular pow is much faster than Boost. The speedups

  in this implementation were obtained by factorizing the a few low powers, and re-using those factorizations for

  higher powers.

- I have tried to use intrinsics(SSE), but didn't find it to be faster than "naive" code.

- Expression templates: unless the expression templates do some serious work, gcc can optimize the code to get very

  good performance, essentially equal to expression templates. So expression templates seem to be an older technique

  that's no longer required by modern compilers(although clang seems to lag compared to gcc in terms of optimization).

- The std::complex class is reputed to be slow, mostly because it does a lot of work to comply with IEEE-754/IEC-559

  apparently. Maybe the worst of this is that this compliance is not optional, and some developers have complained

  that absolutely correct handling of the sign of infinities should not be forced on them.

## IEEE-754/IEC-559 compliance

- If the compiler supports IEC-559, which can be verified by calling std::numeric_limits::is_iec559,

  then quaternion::Quaternion will leverage this.

- However the Quaternion algorithms do not currently take extra steps to comply with IEC-559's prescribed way of handling

  NaNs, underflows, overflows...

## Tested with:

- clang

- gcc 4.8

## Requirements

- Boost is required for the unit tests, but not for the Quaternion class itself.

## Others/References

- https://en.wikipedia.org/wiki/Quaternion

- http://www.boost.org/doc/libs/1_59_0/libs/math/doc/html/quaternions.html

- *vectorclass* from Agner Fog, can be found at: http://www.agner.org/optimize/, and provides quaternion classes.

- http://www.geometrictools.com/index.html

## Quaternion synopsis

### Quaternion\ members

#### Constructors

    Quaternion(T a=0, T b=0, T c=0, T d=0)

    template

    Quaternion(T1 a=0, T1 b=0, T1 c=0, T1 d=0)

    template

    Quaternion(const std::complex &x, const std::complex &y=std::complex(0, 0))

    template

    Quaternion(T1 *it)

    template

    Quaternion(It it)

    template

    Quaternion(const Quaternion &y)

    template

    Quaternion & operator=(const Quaternion &other)

#### Accessors

    T a() const

    T b() const

    T c() const

    T d() const

    std::complex c1() const

    std::complex c2() const

    T to_real() const

    std::complex to_complex() const

    std::array to_array() const

    T real() const

    Quaternion unreal() const

    T norm_squared() const

    T abs() const

    T unreal_norm_squared() const

#### Tests

    template

    bool is_unit(T1 eps=0) const

    template

    bool is_real(T1 eps=0) const

    template

    bool is_complex(T1 eps=0) const

    template

    bool is_unreal(T1 eps=0) const

#### Arithmetic

    Quaternion operator+() const

    Quaternion operator-() const

    Quaternion operator+=(T y)

    Quaternion operator-=(T y)

    Quaternion operator*=(T k)

    Quaternion operator/=(T k)

    template

    Quaternion operator+=(const std::complex &y)

    template

    Quaternion operator-=(const std::complex &y)

    template

    Quaternion operator*=(const std::complex &y)

    template

    Quaternion operator/=(const std::complex &y)

    template

    Quaternion operator+=(const Quaternion &y)

    template

    Quaternion operator-=(const Quaternion &y)

    template

    Quaternion operator*=(const Quaternion &y)

    template

    Quaternion operator/=(const Quaternion &y)

### Typedef

    typedef Quaternion Qf

    typedef Quaternion Qd

    typedef Quaternion Qld

    template

    using polar_representation = std::array

    template

    using matrix_representation = std::array, 2>, 2>

    template

    using rotation_matrix = std::array, 3>

### Enumerations

    enum  DisplayStyle { q_nice, q_compact }

### Predefined constants

    const Qf Qf_1(1)

    const Qf Qf_i(0, 1)

    const Qf Qf_j(0, 0, 1)

    const Qf Qf_k(0, 0, 0, 1)

    const Qd Qd_1(1)

    const Qd Qd_i(0, 1)

    const Qd Qd_j(0, 0, 1)

    const Qd Qd_k(0, 0, 0, 1)

    const Qld Qld_1(1)

    const Qld Qld_i(0, 1)

    const Qld Qld_j(0, 0, 1)

    const Qld Qld_k(0, 0, 0, 1)

### Functions

#### Constructors

    template

    Quaternion spherical(T rho, T theta, T phi1, T phi2)

    template

    Quaternion semipolar(T rho, T alpha, T theta1, T theta2)

    template

    Quaternion multipolar(T rho1, T theta1, T rho2, T theta2)

    template

    Quaternion cylindrospherical(T t, T radius, T longitude, T latitude)

    template

    Quaternion cylindrical(T r, T angle, T h1, T h2)

    template

    polar_representation to_polar_representation(const Quaternion &x)

    template

    matrix_representation to_matrix_representation(const Quaternion &x)

    template

    rotation_matrix to_rotation_matrix(const Quaternion &x)

    template

    Quaternion from_rotation_matrix(const rotation_matrix &rm)

#### Various

    template

    Quaternion conj(const Quaternion &x)

    template

    T norm_squared(const Quaternion &x)

    template

    T abs(const Quaternion &x)

    template

    T unreal_norm_squared(const Quaternion &x)

    template

    T norm_l0(const Quaternion &x)

    template

    T norm_l1(const Quaternion &x)

    template

    T norm_lk(const Quaternion &x, T1 k)

    template

    T norm_sup(const Quaternion &x)

    template

    Quaternion normalize(const Quaternion &x)

#### Tests

    template

    bool is_unit(const Quaternion &x, T1 eps=0)

    template

    bool is_real(const Quaternion &x, T1 eps=0)

    template

    bool is_complex(const Quaternion &x, T1 eps=0)

    template

    bool is_unreal(const Quaternion &x, T1 eps=0)

#### Equality

    template

    bool operator==(const Quaternion &x, T2 y)

    template

    bool operator==(T2 y, const Quaternion &x)

    template

    bool operator!=(const Quaternion &x, T2 y)

    template

    bool operator!=(T2 y, const Quaternion &x)

    template

    bool nearly_equal(const Quaternion &x, T2 y, T3 eps)

    template

    bool nearly_equal(T2 y, const Quaternion &x, T3 eps)

    template

    bool operator==(const Quaternion &x, const std::complex &y)

    template

    bool operator!=(const Quaternion &x, const std::complex &y)

    template

    bool operator==(const std::complex &y, const Quaternion &x)

    template

    bool operator!=(const std::complex &y, const Quaternion &x)

    template

    bool nearly_equal(const Quaternion &x, const std::complex &y, T3 eps)

    template

    bool nearly_equal(const std::complex &y, const Quaternion &x, T3 eps)

    template

    bool operator==(const Quaternion &x, const Quaternion &y)

    template

    bool operator!=(const Quaternion &x, const Quaternion &y)

    template

    bool nearly_equal(const Quaternion &x, const Quaternion &y, T3 eps)

#### Arithmetic

    template

    Quaternion operator+(const Quaternion &x, T1 y)

    template

    Quaternion operator+(T1 y, const Quaternion &x)

    template

    Quaternion operator+(const Quaternion &x, std::complex &y)

    template

    Quaternion operator+(std::complex &y, const Quaternion &x)

    template

    Quaternion operator+(const Quaternion &x, const Quaternion &y)

    template

    Quaternion operator-(const Quaternion &x, T1 y)

    template

    Quaternion operator-(T1 y, const Quaternion &x)

    template

    Quaternion operator-(const Quaternion &x, std::complex &y)

    template

    Quaternion operator-(std::complex &y, const Quaternion &x)

    template

    Quaternion operator-(const Quaternion &x, const Quaternion &y)

    template

    Quaternion operator*(const Quaternion &x, T1 y)

    template

    Quaternion operator*(T1 y, const Quaternion &x)

    template

    Quaternion operator*(const Quaternion &x, std::complex &y)

    template

    Quaternion operator*(std::complex &y, const Quaternion &x)

    template

    Quaternion operator*(const Quaternion &x, const Quaternion &y)

    template

    Quaternion inverse(const Quaternion &x)

    template

    Quaternion operator/(const Quaternion &x, T1 y)

    template

    Quaternion operator/(T1 y, const Quaternion &x)

    template

    Quaternion operator/(const Quaternion &x, std::complex &y)

    template

    Quaternion operator/(std::complex &y, const Quaternion &x)

    template

    Quaternion operator/(const Quaternion &x, const Quaternion &y)

#### Dot, cross product, commutator

    template

    T dot(const Quaternion &x, const Quaternion &y)

    template

    Quaternion cross(const Quaternion &x, const Quaternion &y)

    template

    Quaternion commutator(const Quaternion &x, const Quaternion &y)

#### Transcendentals

    template

    Quaternion exp(const Quaternion &x)

    template

    Quaternion log(const Quaternion &x)

    template

    Quaternion pow2(const Quaternion &x)

    template

    Quaternion pow3(const Quaternion &x)

    template

    Quaternion pow4(const Quaternion &x)

    template

    Quaternion pow(const Quaternion &x, int expt)

    template

    Quaternion pow(const Quaternion &x, T a)

    template

    Quaternion pow(const Quaternion &x, const Quaternion &a)

    template

    Quaternion cos(const Quaternion &x)

    template

    Quaternion sin(const Quaternion &x)

    template

    Quaternion tan(const Quaternion &x)

    template