Easy to use and efficient python quaternion library-quaternion

1. Introduction

https://github.com/moble/quaternion

This library is mainly to add a new type on the basis of Numpy quaternion. It not only realizes the numpy implementation of quaternion-related operations, but also extends many usages of numpy to related quaternions. And the core implementation of this library is implemented in C language, which ensures the higher speed of this library in operation.

In the recent study of quaternions, I compared multiple libraries, including Scipy's rotation-related library, and other libraries, and finally chose this library because of its support for numpy, but because its documentation only Quaternions are a very small part of the instructions, but in fact, the functions that this library can achieve are far greater than the documentation written by the author, so I wrote this Chinese document for my own record and study.

2. Installation

If it is in the conda environment, it is best to use

conda install -c conda-forge quaternion

If it appears, after downloading and installing No module name 'quaternion', you can properly reduce the numpy version, which is currently numpy-1.20.3adaptedquater

nion-2022.4.3Version

You can also use pip

python -m pip install --upgrade --force-reinstall numpy-quaternion

According to the instructions in Releases · mobile/quaternion (github.com), the dependencies still need to be installedconda install scipy numba

3. Basic Usage

import numpy as np
import quaternion

First construct a few quaternions

q1 = np.quaternion(1,2,3,4)
q2 = quaternion.from_float_array([1,2,3,4])

# 生成的都是单位四元数
q3 = quaternion.from_rotation_matrix([[1,2,3],[1,2,3],[1,2,3]])
q4 = quaternion.from_euler_angles([1,2,3])
print(q1,q2,q3,q4)

Quaternion cross product

$(w_1,x_1,y_1,z_1) \otimes (w_2,x_2,y_2,z_2) = \begin{matrix} (&w_1w_2-x_1x_2-y_1y_2-z_1z_2,\\&w_1x_2+x_1w_2+z_1y_2-y_1z_2,\\&w_1y_2+y_1w_2+x_1z_2-z_1x_2,\\&w_1z_2+z_1w_2+y_1x_2-x_1y_2&) \end{matrix}$

# dot方法这里也是叉乘 
print(np.dot(q1,q2))
print(q1 * q2)
print(np.multiply(q1,q2))

Quaternion modulus

$\lvert q \rvert = \sqrt{w^2+x^2+y^2+z^2}$

# 计算四元数的模
print(q1.abs())
print(q1.absolute())
print(np.sqrt(q1.norm()))
# 四元数的归一化
print(q1 / q1.abs())
print(q1.normalized())

Cayley norm for quaternions

$\lVert q \rVert = w^2+x^2+y^2+z^2$

Note that the Norm of the quaternion np.linalg.normis different from the method in numpy, which is in numpy Euclidean norm, and the norm in the quaternion isCayley norm

print(q1.norm())

Conjugation and inverse of quaternions

The conjugation of the quaternion is to make the vector part of the quaternion negative $q^* = (w,x ,y,z)^* = (w,-x,-y,-z)$

The inverse of a quaternion is just the conjugate of the quaternion divided by its Cayley norm $q^{-1} = \frac{q^*}{\lVert q \rVert}$

Generally, the unit quaternion is used, and its inverse and conjugate are equal at this time

# 四元数求共轭
print(q1.conjugate())
# 四元数求逆
print(q1.inverse())

# 单位四元数的共轭和逆是相等的
q_normolized = q1.normalized()
print(q_normolized.conjugate())
print(q_normolized.conjugate() / q_normolized.norm())

The amount of rotation between two quaternions

Indicates the amount of rotation from one orientation to another

$q = q_{begin}^* * q_{after}$ （ $q_{begin},q_{after}$ is the unit quaternion)

$q = q_{begin}^{-1} * q_{after}$ （ $q_{begin},q_{after}$ not a unit quaternion)

q = q3.conjugate() * q4
print(q)
# 要注意四元数叉乘顺序
print(q * q3)
print(q3 * q)
print(q4)


q3New = 2 * q3
print(q3New)
q = q3New.inverse() * q4
print(q.normalized())

Quaternion dot product

It is used to measure the similarity of two quaternions, which is similar to the point product of vectors. The larger the absolute value of the point product of two quaternions, the rotation it represents is about similar. The point product tends to -1 or 1, which means similarity , since $(1, 0, 0, 0)$ and $(- 1, 0, 0, 0)$ means that when the rotation angle is an integer multiple of 360 degrees, the orientation does not change

# 在quaternion库中没有对应的方法
def quatDot(q1,q2):
    return np.abs((q1.w * q2.w + q1.x * q2.x + q1.y * q2.y + q1.z * q2.z) / q1.absolute()*q2.absolute() )

4. Reference

Quaternion Basics - Paladin Wind - Blog Garden (cnblogs.com)

Basic operations of quaternions