3d quaternions

1.0.0

A utility library implementing quaternion and dual-quaternion functionality.

About 3d-quaternions

This is a library for quaternions. It contains most of the quaternion operations one would usually expect out of such a library and offers them both in non-modifying and modifying versions where applicable. It also tries to be efficient where plausible. Each quaternion is made up of floats, which by default are single-floats, as they do not require value boxing on most modern systems and compilers.

How To

Load it through ASDF or Quicklisp

(ql:quickload :3d-quaternions)
(use-package :org.shirakumo.flare.quaternion)

Create a quaternion:

(quat)

Quaternions always use floats. Where sensible, operations should accept real numbers for convenience. All quaternion operations are prefixed with a q to allow importing the package without conflicts.

(q+ (quat 1 2 3 4) 4 5 6)
(qfrom-angle +vz+ PI)

3d-quaternions implements pretty much all quaternion operations you might need, including comparators, dot product, matrix conversion, and so forth. There's also modifying variants of most operators, which have the same name, except they are prefixed by an n.

(let ((q (quat)))
  (nq* (nq+ q (quat 1 2 3 4)) 3)
  q)

quats are dumpable, meaning you can insert them as literals into your code and they will be properly saved to and restored from a FASL.

If you require higher precision than single-floats ensure, you can add :3d-vectors-double-floats to *features* and recompile the library (asdf:compile-system :3d-quaternions :force T). Similarly, if you want to switch back to single-floats, you can remove the feature and recompile. Both at the same time is not supported as it would increase complexity in the library massively and make certain operations much slower.

Also See

3d-vectors for Vector operations in conjunction with this library.
3d-matrices for Matrix operations in conjunction with this library.

System Information

Version: 1.0.0

Dependencies:

Author: Nicolas Hafner

License: zlib

Homepage: https://Shinmera.github.io/3d-quaternions/

Sources: https://github.com/Shinmera/3d-quaternions.git

Definition Index

ORG.SHIRAKUMO.FLARE.QUATERNION

No documentation provided.

EXTERNAL STRUCTURE

DQUAT

Encompasses a dual-quaternion.

Dual-quaternions are composed of two quaternions, the 'real'
representing a rotation, and the 'dual' representing a translation.

See DQUAT (type)
See DQCOPY
See DQUAT-P
See QREAL
See QDUAL
See Q=
See Q/=
See QEQUAL
See Q+
See NQ+
See Q-
See NQ-
See Q*
See NQ*
See Q/
See NQ/
See Q.
See QUNIT
See NQUNIT
See QCONJUGATE
See Q*V

EXTERNAL STRUCTURE

QUAT

Encompasses a quaternion.

A quaternion describes a rotational axis and an angle.
This is a sub-structure of a VEC3, and as such can be used with any
functions from 3D-VECTORS that support VEC3s.

See 3D-VECTORS:VEC3
See QUAT (function)
See QCOPY
See QUAT-P
See QX
See QY
See QZ
See QW
See QSETF
See QFROM-ANGLE
See QTOWARDS
See QAXIS
See QANGLE
See Q=
See Q/=
See QEQUAL
See Q+
See NQ+
See Q-
See NQ-
See Q*
See NQ*
See Q/
See NQ/
See Q.
See QLENGTH2
See QLENGTH
See QUNIT
See NQUNIT
See QCONJUGATE
See QINV
See Q*V
See QMIX
See QNLERP
See QSLERP
See QEXPT
See NQEXPT
See QLOOKAT
See QMAT3
See QMAT4
See QFROM-MAT

EXTERNAL FUNCTION

DQCOPY

INSTANCE

Returns a fresh copy of the dual-quaternion.

See DQUAT

EXTERNAL FUNCTION

DQUAT

&OPTIONAL
REAL
DUAL

Constructs a dual-quaternion

If no arguments are passed, an "empty" dual-quaternion is returned.

See DQUAT (type)

EXTERNAL FUNCTION

DQUAT-P

OBJECT

Returns true if the given object is a dual-quaternion.

See DQUAT

EXTERNAL FUNCTION

NQ*

VAL
&REST
VALS

Returns the first quaternion after being modified by multiplication of the passed quaternions.

You may also pass a real number to multiply with each component.
Note that for quaternions this is *not* element-wise multiplication.
If passed a dual-quaternion, the real side is multiplied normally,
while the dual side is multiplied with the real side to ensure the
quaternions stay true.

See QUAT
See NQ*

EXTERNAL FUNCTION

NQ+

VAL
&REST
VALS

Returns the first quaternion after being modified by element-wise addition of all passed quaternions.

You may also pass a real number to add to each component.
If passed a dual-quaternion, both the real and dual are added.

See QUAT
See Q+

EXTERNAL FUNCTION

NQ-

VAL
&REST
VALS

Returns the first quaternion after being modified by element-wise subtraction of all passed quaternions.

You may also pass a real number to subtract from each component.
If passed a dual-quaternion, both the real and dual are subtracted.

See QUAT
See Q-

EXTERNAL FUNCTION
NQ/
- VAL
- &REST
- VALS
Source

EXTERNAL FUNCTION

NQEXPT

QUAT
EXP

Compute the exponentiation of a quaternion.

Returns the modified quaternion.

See QUAT

EXTERNAL FUNCTION

NQUNIT

A

Returns the quaternion after normalising it.

If passed a dual-quaternion, the real and dual part are normalised by
the length of the real part.

See QUAT
See QUNIT

EXTERNAL FUNCTION

Q*

VAL
&REST
VALS

Returns the multiplication of the passed quaternions.

You may also pass a real number to multiply with each component.
Note that for quaternions this is *not* element-wise multiplication.
If passed a dual-quaternion, the real side is multiplied normally,
while the dual side is multiplied with the real side to ensure the
quaternions stay true.

See QUAT
See NQ*

EXTERNAL FUNCTION

Q*V

Q
V

Returns the vector after multiplying it by the quaternion.

This essentially rotates the vector by the rotation expressed by the
quaternion.

If passed a dual-quaternion, the vector is first rotated, then
translated by the encoded transforms.

See QUAT
See 3D-VECTORS:VEC3

EXTERNAL FUNCTION

Q+

VAL
&REST
VALS

Returns the element-wise addition of the passed quaternions.

You may also pass a real number to add to each component.
If passed a dual-quaternion, both the real and dual are added.

See QUAT
See NQ+

EXTERNAL FUNCTION

Q-

VAL
&REST
VALS

Returns the element-wise subtraction of the passed quaternions.

You may also pass a real number to subtract from each component.
If passed a dual-quaternion, both the real and dual are subtracted.

See QUAT
See NQ+

EXTERNAL FUNCTION

Q.

A
B

Returns the dot product of the two quaternions.

If passed a dual-quaternion, only the real quaternion is dotted.

See QUAT

EXTERNAL FUNCTION
Q/
- VAL
- &REST
- VALS
Source

EXTERNAL FUNCTION

Q/=

VAL
&REST
VALS

Returns true if any of the quaternions passed are not the same.

This does not test for element-wise float exact equality,
and instead compares accounting for a minimal epsilon of difference.
If passed a dual-quaternion, both the real and dual are tested.

See QUAT

EXTERNAL FUNCTION

Q=

VAL
&REST
VALS

Returns true if the quaternions passed are the same.

This does not test for element-wise float exact equality,
and instead compares accounting for a minimal epsilon of difference.
If passed a dual-quaternion, both the real and dual are tested.

See QUAT

EXTERNAL FUNCTION

QANGLE

QUAT

Returns the angle around the rotation axis that the quaternion rotates by.

See QUAT

EXTERNAL FUNCTION

QAXIS

QUAT

Returns the normalised axis around which the quaternion rotates.

This is the same as just calling VUNIT.

See QUAT
See 3D-VECTORS:VUNIT

EXTERNAL FUNCTION

QCONJUGATE

A

Returns the conjugate of the quaternion.

If passed a dual-quaternion, both the real and dual part are
conjugated independently.

See QUAT

EXTERNAL FUNCTION

QCOPY

INSTANCE

Creates an exact copy of the quaternion.

See QUAT

EXTERNAL FUNCTION

QDUAL

INSTANCE

Accesses the quaternion encompassing the translation of the dual-quaternion.

See QUAT
See DQUAT

EXTERNAL FUNCTION
(SETF QDUAL)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

QEQUAL

A
B

Returns true if the quaternions passed describe the same direction.

This disregards the orientation of the rotation encoded, and treats
them the same regardless of whether they rotate around the 'long way'
or the 'short way'.
If passed a dual-quaternion, the real is tested by qequal, and the
dual is tested by q=.

See QUAT
See Q=

EXTERNAL FUNCTION

QEXPT

QUAT
EXP

Compute the exponentiation of a quaternion.

Returns a fresh quaternion.

See QUAT

EXTERNAL FUNCTION

QFROM-ANGLE

AXIS
ANGLE

Construct a quaternion from an axis and a rotation.

Returns the freshly constructed quaternion.

See QUAT

EXTERNAL FUNCTION

QFROM-MAT

MAT

Returns a quaternion that encompasses the same rotation described by the matrix.

Both a MAT3 and MAT4 can be used.

See QUAT
See QMAT3
See QMAT4
See 3D-MATRICES:MAT3
See 3D-MATRICES:MAT4

EXTERNAL FUNCTION

QFROM-POSITION

QUAT
VEC

Turn a rotation quaternion and a position vector into a dual-quaternion.

See QUAT
See 3D-VECTORS:VEC3
See DQUAT

EXTERNAL FUNCTION

QINV

A

Returns the inverses of the quaternion.

See QUAT

EXTERNAL FUNCTION

QLENGTH

A

Returns the length of the quaternion.

If passed a dual-quaternion, only the real quaternion is measured.

See QUAT
See QLENGTH2

EXTERNAL FUNCTION

QLENGTH2

A

Returns the squared length of the quaternion.

If passed a dual-quaternion, only the real quaternion is measured.

See QUAT
See QLENGTH

EXTERNAL FUNCTION

QLOOKAT

DIR
UP

Returns a quaternion that encompassses the rotation necessary to look in the described direction.

See QUAT

EXTERNAL FUNCTION

QMAT3

QUAT

Returns a MAT3 that encompasses the rotation described by the quaternion.

See QUAT
See QMAT4
See QFROM-MAT
See 3D-MATRICES:MAT3

EXTERNAL FUNCTION

QMAT4

QUAT

Returns a MAT4 that encompasses the rotation described by the quaternion.

See QUAT
See QMAT3
See QFROM-MAT
See 3D-MATRICES:MAT4

EXTERNAL FUNCTION

QMIX

FROM
TO
X

Returns a new quaternion mixed with the two.

This is essentially Q = A*(1-X) + B*X

See QUAT

EXTERNAL FUNCTION

QNLERP

FROM
TO
X

Returns the linearly interpolated quaternion between the two.

This is essentially Q = A + (B-A)*X

See QUAT

EXTERNAL FUNCTION

QPOSITION

DQUAT

Return the position vector encoded by the dual-quaternion.

See 3D-VECTORS:VEC3
See DQUAT

EXTERNAL FUNCTION

QREAL

INSTANCE

Accesses the quaternion encompassing the rotation of the dual-quaternion.

See QUAT
See DQUAT

EXTERNAL FUNCTION
(SETF QREAL)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

QSLERP

FROM
TO
X

Returns the spherically interpolated quaternion between the two.

This attempts to compute the interpolation by rotating along the unit
sphere.

See QUAT

EXTERNAL FUNCTION

QTOWARDS

FROM
TO

Construct a quaternion that describes the rotation from one vector to another.

Returns the freshly constructed quaternion.

See QUAT

EXTERNAL FUNCTION

QUAT

&OPTIONAL
X
Y
Z
W

Constructs a quaternion.

If no arguments are passed, a unit quaternion of 0 0 0 1 is returned.

See QUAT (type)

EXTERNAL FUNCTION

QUAT-P

OBJECT

Returns true if the passed object is a quaternion.

See QUAT

EXTERNAL FUNCTION

QUNIT

A

Returns a normalised copy of the quaternion.

If passed a dual-quaternion, the real and dual part are normalised by
the length of the real part.

See QUAT
See NQUNIT

EXTERNAL FUNCTION

QW

VEC

Accesses the fourth component of the quaternion.

See QUAT (type)

EXTERNAL FUNCTION

QX

VEC

Accesses the first component of the quaternion.

See QUAT (type)

EXTERNAL FUNCTION

QY

VEC

Accesses the second component of the quaternion.

See QUAT (type)

EXTERNAL FUNCTION

QZ

VEC

Accesses the third component of the quaternion.

See QUAT (type)

EXTERNAL MACRO

DQSETF

QUAT
REAL
DUAL

Update the fields of a dual-quaternion.

Returns the modified dual-quaternion.

See DQUAT

EXTERNAL MACRO

QSETF

QUAT
X
Y
Z
W

Update the fields of a quaternion.

Returns the modified quaternion.

See QUAT