3d quaternions
1.0.0A utility library implementing quaternion and dualquaternion functionality.
About 3dquaternions
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 nonmodifying and modifying versions where applicable. It also tries to be efficient where plausible. Each quaternion is made up of float
s, which by default are singlefloat
s, as they do not require value boxing on most modern systems and compilers.
How To
Load it through ASDF or Quicklisp
(ql:quickload :3dquaternions)
(usepackage :org.shirakumo.flare.quaternion)
Create a quaternion:
(quat)
Quaternions always use float
s. 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)
(qfromangle +vz+ PI)
3dquaternions 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)
quat
s 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 singlefloat
s ensure, you can add :3dvectorsdoublefloats
to *features*
and recompile the library (asdf:compilesystem :3dquaternions :force T)
. Similarly, if you want to switch back to singlefloat
s, 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
3dvectors for Vector operations in conjunction with this library.
3dmatrices for Matrix operations in conjunction with this library.
System Information
Definition Index

ORG.SHIRAKUMO.FLARE.QUATERNION
No documentation provided.
EXTERNAL STRUCTURE DQUAT
Encompasses a dualquaternion. Dualquaternions are composed of two quaternions, the 'real' representing a rotation, and the 'dual' representing a translation. See DQUAT (type) See DQCOPY See DQUATP 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 substructure of a VEC3, and as such can be used with any functions from 3DVECTORS that support VEC3s. See 3DVECTORS:VEC3 See QUAT (function) See QCOPY See QUATP See QX See QY See QZ See QW See QSETF See QFROMANGLE 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 QFROMMAT

EXTERNAL FUNCTION DQCOPY
 INSTANCE
Returns a fresh copy of the dualquaternion. See DQUAT

EXTERNAL FUNCTION DQUAT
 &OPTIONAL
 REAL
 DUAL
Constructs a dualquaternion If no arguments are passed, an "empty" dualquaternion is returned. See DQUAT (type)

EXTERNAL FUNCTION DQUATP
 OBJECT
Returns true if the given object is a dualquaternion. 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* elementwise multiplication. If passed a dualquaternion, 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

EXTERNAL FUNCTION NQ
 VAL
 &REST
 VALS

EXTERNAL FUNCTION NQ/
 VAL
 &REST
 VALS

EXTERNAL FUNCTION NQEXPT
 QUAT
 EXP
Compute the exponentiation of a quaternion. Returns the modified quaternion. See QUAT

EXTERNAL FUNCTION NQUNIT
 A

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* elementwise multiplication. If passed a dualquaternion, 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 dualquaternion, the vector is first rotated, then translated by the encoded transforms. See QUAT See 3DVECTORS:VEC3

EXTERNAL FUNCTION Q+
 VAL
 &REST
 VALS

EXTERNAL FUNCTION Q
 VAL
 &REST
 VALS

EXTERNAL FUNCTION Q.
 A
 B
Returns the dot product of the two quaternions. If passed a dualquaternion, only the real quaternion is dotted. See QUAT

EXTERNAL FUNCTION Q/
 VAL
 &REST
 VALS

EXTERNAL FUNCTION Q/=
 VAL
 &REST
 VALS
Returns true if any of the quaternions passed are not the same. This does not test for elementwise float exact equality, and instead compares accounting for a minimal epsilon of difference. If passed a dualquaternion, 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 elementwise float exact equality, and instead compares accounting for a minimal epsilon of difference. If passed a dualquaternion, 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 3DVECTORS:VUNIT

EXTERNAL FUNCTION QCONJUGATE
 A
Returns the conjugate of the quaternion. If passed a dualquaternion, 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

EXTERNAL FUNCTION (SETF QDUAL)
 VALUE
 INSTANCE
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 dualquaternion, 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 QFROMANGLE
 AXIS
 ANGLE
Construct a quaternion from an axis and a rotation. Returns the freshly constructed quaternion. See QUAT

EXTERNAL FUNCTION QFROMMAT
 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 3DMATRICES:MAT3 See 3DMATRICES:MAT4

EXTERNAL FUNCTION QFROMPOSITION
 QUAT
 VEC
Turn a rotation quaternion and a position vector into a dualquaternion. See QUAT See 3DVECTORS:VEC3 See DQUAT

EXTERNAL FUNCTION QINV
 A
Returns the inverses of the quaternion. See QUAT

EXTERNAL FUNCTION QLENGTH
 A

EXTERNAL FUNCTION QLENGTH2
 A

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 QFROMMAT See 3DMATRICES:MAT3

EXTERNAL FUNCTION QMAT4
 QUAT
Returns a MAT4 that encompasses the rotation described by the quaternion. See QUAT See QMAT3 See QFROMMAT See 3DMATRICES:MAT4

EXTERNAL FUNCTION QMIX
 FROM
 TO
 X
Returns a new quaternion mixed with the two. This is essentially Q = A*(1X) + B*X See QUAT

EXTERNAL FUNCTION QNLERP
 FROM
 TO
 X
Returns the linearly interpolated quaternion between the two. This is essentially Q = A + (BA)*X See QUAT

EXTERNAL FUNCTION QPOSITION
 DQUAT
Return the position vector encoded by the dualquaternion. See 3DVECTORS:VEC3 See DQUAT

EXTERNAL FUNCTION QREAL
 INSTANCE

EXTERNAL FUNCTION (SETF QREAL)
 VALUE
 INSTANCE
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 QUATP
 OBJECT
Returns true if the passed object is a quaternion. See QUAT

EXTERNAL FUNCTION QUNIT
 A

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 dualquaternion. Returns the modified dualquaternion. See DQUAT

EXTERNAL MACRO QSETF
 QUAT
 X
 Y
 Z
 W
Update the fields of a quaternion. Returns the modified quaternion. See QUAT
