fastmath.quaternion — generateme/fastmath 3.0.0-alpha4

Operations for quaternions.

Quaternions extend complex numbers and are widely used in fields like 3D graphics and physics for representing rotations.

In fastmath, quaternions are represented as 4-dimensional vectors ([[Vec4]]) where the components correspond to the scalar part and the three imaginary parts ($i$, $j$, $k$): $q = a + bi + cj + dk$ is (Vec4. a b c d).

The namespace provides functions for creating quaternions, accessing scalar and vector parts, predicates (e.g., real?, zero?, inf?, nan?), and fundamental properties (magnitude, argument, normalization).

A comprehensive set of operations is included:

• Arithmetic: Addition, subtraction, multiplication, division, negation, square, reciprocal, scaling, conjugation.
• Transcendental Functions: Extensions of standard complex functions like exponential, logarithm, power, trigonometric, hyperbolic functions, and their inverses.
• Rotations: Functions for creating rotation quaternions, rotating 3D vectors (rotate), spherical linear interpolation (SLERP), and conversions between quaternions, Euler angles (ZYX body 3-2-1 and z-y'-x''), and rotation matrices.

The implementation correctly handles floating-point special values, including ##Inf and ##NaN.

-I clj

0-1i+0j+0k

-J clj

0+0i-1j+0k

-K clj

0+0i+0j-1k

acos clj

(acos q)

acos(q)

acosh clj

(acosh q)

acosh(q)

acot clj

(acot q)

acot(q)

acoth clj

(acoth q)

acoth(q)

acsc clj

(acsc q)

acsc(q)

acsch clj

(acsch q)

acsch(q)

add clj

(add q1 q2)

Sum of two quaternions

adds clj

(adds q1 s)

Adds scalar to a quaternion

arg clj

(arg quaternion)

Argument of quaternion, atan2(|vector(q)|, re(q))

asec clj

(asec q)

asec(q)

asech clj

(asech q)

asech(q)

asin clj

(asin q)

asin(q)

asinh clj

(asinh q)

asinh(q)

atan clj

(atan q)

atan(q)

atanh clj

(atanh q)

atanh(q)

complex->quaternion clj

(complex->quaternion z)

Create quaternion from complex number

conjugate clj

(conjugate quaternion)

Conjugate of the quaternion

cos clj

(cos q)

cos(q)

cosh clj

(cosh q)

cosh(q)

cot clj

(cot q)

cot(q)

coth clj

(coth q)

coth(q)

csc clj

(csc q)

csc(q)

csch clj

(csch q)

csch(q)

delta-eq clj

(delta-eq q1 q2)

(delta-eq q1 q2 accuracy)

Compare quaternions with given accuracy (10e-6 by default)

div clj

(div q1 q2)

Division two quaternions

ensure-quaternion clj

(ensure-quaternion q)

Convert possible number, complex number to a quaternion

exp clj

(exp q)

exp(q)

from-angles clj

(from-angles [x y z])

(from-angles x y z)

Converts Tait–Bryan angles (z-y′-x'' intrinsic rotation sequence) to a quaternion.

The angles [x y z] correspond to rotations around the local (body) x-axis, followed by the intermediate local y'-axis, and finally the local z''-axis.

Parameters:

• x: Rotation around the x-axis (radians).
• y: Rotation around the y'-axis (radians).
• z: Rotation around the z''-axis (radians).

Can accept individual double values or a Vec3 containing [x y z].

Returns A quaternion Vec4 representing the rotation.

from-euler clj

(from-euler [roll pitch yaw])

(from-euler roll pitch yaw)

Converts Euler angles (ZYX body 3-2-1 convention) to a quaternion.

The rotation sequence is intrinsic Z-Y'-X'' (yaw, pitch, roll), applied to the body frame. The order of input parameters or vector components is [roll pitch yaw].

Parameters:

• roll: Rotation around the x-axis (radians), expected range [-pi, pi].
• pitch: Rotation around the y'-axis (radians), expected range [-pi/2, pi/2].
• yaw: Rotation around the z''-axis (radians), expected range [-pi, pi].

Can accept individual double values or a Vec3 containing [roll pitch yaw].

Returns A quaternion Vec4 representing the rotation.

from-rotation-matrix clj

(from-rotation-matrix m)

Converts a 3x3 rotation matrix to a quaternion.

Takes a [[Mat3x3]] rotation matrix as input. Returns a [[Vec4]] representing the quaternion that represents the same rotation.

The resulting quaternion is a unit quaternion if the input matrix is a valid rotation matrix. The method handles numerical stability and normalization.

I clj

0+1i+0j+0k

im-i clj

(im-i quaternion)

Return i imaginary part

im-j clj

(im-j quaternion)

Return j imaginary part

im-k clj

(im-k quaternion)

Return k imaginary part

imaginary? clj

(imaginary? quaternion)

Is q is a pure imaginary number?

inf? clj

(inf? quaternion)

Is infinitive?

invalid? clj

(invalid? z)

Is NaN or Inf?

J clj

0+0i+1j+0k

K clj

0+0i+0j+1k

log clj

(log q)

log(q)

logb clj

(logb quaternion b)

log with base b

mult clj

(mult q1 q2)

Multiplication of two quaternions.

nan? clj

(nan? quaternion)

Is NaN?

neg clj

(neg quaternion)

Negation of the quaternion.

norm clj

(norm quaternion)

Norm of the quaternion, length of the vector

normalize clj

(normalize quaternion)

Normalize quaternion, unit of quaternion.

ONE clj

1+0i+0j+0k

pow clj

(pow q p)

Quaternion power

qsgn clj

(qsgn q)

(qsgn re im-i im-j im-k)

Computes the signum of a quaternion.

Returns 0.0 for the zero quaternion ($0+0i+0j+0k$). For any other quaternion, returns the sign of its scalar part.

quaternion clj

(quaternion a)

(quaternion scalar [i j k])

(quaternion a b c d)

Create quaternion from individual values or scalar and vector parts, reprezented as Vec4.

re clj

(re quaternion)

Returns scalar part of quaternion

real? clj

(real? quaternion)

Is q is a real number?

reciprocal clj

(reciprocal quaternion)

Reciprocal of the quaternion

rotate clj

(rotate in rotq)

(rotate in angle u)

Rotate 3d in vector around axis u, the same as fastmath.vector/axis-rotate.

rotation-quaternion clj

(rotation-quaternion angle u)

Creates a unit quaternion representing a rotation.

The rotation is defined by an angle (in radians) and a 3D vector u specifying the axis of rotation. The axis vector u is normalized internally to ensure a unit quaternion result.

Parameters:

• angle: The rotation angle in radians (double).
• u: The axis of rotation (Vec3). It will be normalized before use.

Returns A unit quaternion (Vec4) representing the rotation.

scalar clj

(scalar quaternion)

Returns scalar part of quaternion, double

scale clj

(scale quaternion scale)

Scale the quaternion

sec clj

(sec q)

sec(q)

sech clj

(sech q)

sech(q)

sin clj

(sin q)

sin(q)

sinh clj

(sinh q)

sinh(q)

slerp clj

(slerp q1 q2 t)

Performs Spherical Linear Interpolation (SLERP) between two quaternions.

SLERP interpolates along the shortest arc on the unit sphere, providing smooth interpolation between rotations represented by unit quaternions.

Parameters:

• q1: The starting quaternion (Vec4).
• q2: The ending quaternion (Vec4).
• t: The interpolation parameter (double). Should be in the range [0.0, 1.0].
  • If t=0.0, returns q1.
  • If t=1.0, returns q2.
  • For 0.0 < t < 1.0, returns an interpolated quaternion. The parameter t is internally constrained to [0.0, 1.0].

Note: This function is typically used with unit quaternions for rotation interpolation.

sq clj

(sq quaternion)

Square of the quaternion.

sqrt clj

(sqrt q)

sqrt(q)

sub clj

(sub q1 q2)

Difference of two quaternions

tan clj

(tan q)

tan(q)

tanh clj

(tanh q)

tanh(q)

to-angles clj

(to-angles q)

Converts a quaternion q to Tait–Bryan angles using the z-y′-x'' intrinsic rotation sequence. The input quaternion is normalized before calculation. Returns a Vec3 representing the angles [x y z]. These angles correspond to rotations around the local (body) x-axis, followed by the intermediate local y'-axis, and finally the local z''-axis. Output angles are typically in the range [-pi, pi] for x and z, and [-pi/2, pi/2] for y.

to-euler clj

(to-euler q)

Converts a quaternion q to ZYX (body 3-2-1) Euler angles. The input quaternion is normalized before calculation. Returns a Vec3 representing the angles [roll pitch yaw]. Roll is the angle around the x-axis, pitch around the y'-axis, and yaw around the z''-axis. Output angles are typically in [-pi, pi] for roll/yaw and [-pi/2, pi/2] for pitch.

to-rotation-matrix clj

(to-rotation-matrix q)

Converts a quaternion to a 3x3 rotation matrix.

The input quaternion is normalized internally to ensure a valid rotation matrix. Unit quaternions are used to represent rotations.

Parameters:

• q: The quaternion (Vec4) to convert.

Returns A 3x3 rotation matrix (Mat3x3).

valid? clj

(valid? z)

Is valid complex (not NaN or Inf)?

vector clj

(vector quaternion)

Returns vector part of quaternion, Vec3 type

ZERO clj

0+0i+0j+0k

zero? clj

(zero? quaternion)

Is zero?