The qmath module

qmath

Similar to the built-in module cmath, this module has definitions of mathematical functions expanded to work with quaternions.

Quaternion Boolean functions

quaternions.qmath.isclose(a, b, *, rel_tol=1e-09, abs_tol=1e-09) → bool

Determine whether two Quaternions are close in value.

For the values to be considered close, the difference between them must be smaller than at least one of the tolerances.

-inf, inf and NaN behave similarly to the IEEE 754 Standard. That is, NaN is not close to anything, even itself. inf and -inf are only close to themselves.

Parameters:

a (Quaternion) – The first Quaternion.
b (Quaternion) – The second Quaternion.
rel_tol (float) – maximum difference for being considered “close”, relative to the magnitude of the input values
abs_tol (float) – maximum difference for being considered “close”, regardless of the magnitude of the input values

Returns:

True if a is close in value to b,: and False otherwise.

Return type:

bool

New in version 2.0.0.

quaternions.qmath.isfinite(q: Quaternion) → bool: Return True if all components of q are finite, and False otherwise.

New in version 2.0.0.

quaternions.qmath.isinf(q: Quaternion) → bool: Return True if any component of q is an infinity, and False otherwise.

New in version 2.0.0.

quaternions.qmath.isnan(q: Quaternion) → bool: Return True if any component of q is a NaN, and False otherwise.

New in version 2.0.0.

Quaternion mathematical functions

quaternions.qmath.exp(q: Quaternion) → Quaternion: Return the exponential of a quaternion.

quaternions.qmath.log(q: Quaternion, base: Quaternion = 2.718281828459045) → Quaternion

Return the logarithm of a quaternion to the given base.

If the base is not specified, returns the natural logarithm (base e) of the quaternion.

quaternions.qmath.log10(q: Quaternion) → Quaternion: Return the base-10 logarithm of the quaternion.

quaternions.qmath.sqrt(q: Quaternion) → Quaternion: Return the square root of the quaternion.

quaternions.qmath.cos(q: Quaternion) → Quaternion: Return the cosine of the quaternion.

New in version 2.0.0.

quaternions.qmath.cosh(q: Quaternion) → Quaternion: Return the hyperbolic cosine of q.

New in version 2.0.0.

quaternions.qmath.sin(q: Quaternion) → Quaternion: Return the sine of the quaternion.

New in version 2.0.0.

quaternions.qmath.sinh(q: Quaternion) → Quaternion: Return the hyperbolic sine of q.

New in version 2.0.0.

quaternions.qmath.tan(q: Quaternion) → Quaternion: Return the tangent of the quaternion.

New in version 2.0.0.

quaternions.qmath.tanh(q: Quaternion) → Quaternion: Return the hyperbolic tangent of q.

New in version 2.0.0.

Rotation functions

quaternions.qmath.rotate3d(point: Iterable[float], angle: float, axis: Iterable[float] = (0.0, 0.0, 1.0), rounding: int = -1, degrees: bool = True) → Tuple[float]

Rotate a point around an axis.

Take a point in 3d space represented as a tuple or list of three (3) values and rotate it by an angle around a given axis vector.

Parameters:

point – The point to rotate. The format for the coordinates is (x, y, z).
angle – The angle of rotation. By default, angle is set to be input in degrees. See the degrees parameter if you want to use radians instead.
axis – The axis to rotate the point around. By default, this is the z-axis (0, 0, 1).
rounding – The number of decimal points the result will be rounded to. Default value is -1, which does not round the end result.
degrees – When set to True, this function interprets the parameter angle as degrees. Set this parameter to False to use angles in radians. Default is True.

For the point and axis parameters, if only one value is given, the value will be assumed to be an x-coordinate with the y- and z-coordinates equal to zero (0). If two values are given, they will be assumed to be x- and y-coordinates with the z-coordinate equal to zero (0).

quaternions.qmath.rotate_Euler(point: Iterable[float], yaw: float, pitch: float, roll: float, x_axis: Iterable[float] = (1.0, 0.0, 0.0), z_axis: Iterable[float] = (0.0, 0.0, 1.0), degrees: bool = True) → Tuple[float]

Rotate a given point using Euler angles.

This function uses the rotation convention of z-y’-x”, rotating yaw, then pitch, then roll.

Parameters:

point – The point to rotate. The format for the coordinates is (x, y, z).
yaw – The angle of rotation around the z-axis.
pitch – The angle of rotation around the y’-axis. The y’-axis is the y-axis after the yaw rotation has been applied.
roll – The angle of rotation around the x”-axis. The x”-axis is the x-axis after both the yaw and pitch rotations.
x_axis – The initial x-axis of the coordinate system that point belongs to. Default value is (1, 0, 0).
z_axis – The initial z-axis of the coordinate system that point belongs to. Default value is (0, 0, 1).
degrees – When set to True, this function interprets the angle parameters as degrees. Set this parameter to False to use angles in radians. Default is True.

New in version 1.1.0.

Vector functions

quaternions.qmath.cross_product(vector1: Iterable[float], vector2: Iterable[float]) → Tuple[float]

Return the cross product of two vectors.

Because this uses quaternions to calculate, this only works for vectors up to three (3) dimensions.

New in version 1.1.0.

quaternions.qmath.dot_product(vector1: Iterable[float], vector2: Iterable[float]) → float

Return the dot product of two vectors.

Because this uses quaternions to calculate, this only works for vectors up to three (3) dimensions.

New in version 1.1.0.

Constants

quaternions.qmath.pi: The mathematical constant π, as a float.

quaternions.qmath.tau: The mathematical constant τ, as a float.

quaternions.qmath.e: The mathematical constant e, as a float.

quaternions.qmath.inf: Floating-point positive infinity. Equivalent to float('inf').

quaternions.qmath.infi: Quaternion with positive infinity i part and zero for all the other parts. Equivalent to Quaternion(0, float('inf'), 0, 0).

quaternions.qmath.infj: Quaternion with positive infinity j part and zero for all the other parts. Equivalent to Quaternion(0, 0, float('inf'), 0).

quaternions.qmath.infk: Quaternion with positive infinity k part and zero for all the other parts. Equivalent to Quaternion(0, 0, 0, float('inf')).

quaternions.qmath.nan: A floating-point “not a number” (NaN) value. Equivalent to float('nan').

quaternions.qmath.nani: Quaternion with NaN i part and zero for all the other parts. Equivalent to Quaternion(0, float('nan'), 0, 0).

quaternions.qmath.nanj: Quaternion with NaN j part and zero for all the other parts. Equivalent to Quaternion(0, 0, float('nan'), 0).

quaternions.qmath.nank: Quaternion with NaN k part and zero for all the other parts. Equivalent to Quaternion(0, 0, 0, float('nan')).