# The 3d-quaternions Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

# The 3d-quaternions Reference Manual

This is the 3d-quaternions Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 03:10:32 2022 GMT+0.

## 1 Introduction

```## 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 ``float``s, which by default are ``single-float``s, as they do not require value boxing on most modern systems and compilers.

## How To
Load it through ASDF or Quicklisp

::
(use-package :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)
(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)
::

``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 ``single-float``s 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-float``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
- "3d-vectors"(https://shinmera.github.io/3d-vectors) for Vector operations in conjunction with this library.
- "3d-matrices"(https://shinmera.github.io/3d-matrices) for Matrix operations in conjunction with this library.

```

## 2 Systems

The main system appears first, followed by any subsystem dependency.

Previous: , Up: Systems   [Contents][Index]

### 2.1 3d-quaternions

A utility library implementing quaternion and dual-quaternion functionality.

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Source Control

(GIT https://github.com/Shinmera/3d-quaternions.git)

Bug Tracker

zlib

Version

1.0.0

Dependencies
• documentation-utils (system).
• 3d-vectors (system).
• 3d-matrices (system).
Source
Child Components

## 3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

Previous: , Up: Files   [Contents][Index]

### 3.1 Lisp

Next: , Previous: , Up: Lisp   [Contents][Index]

#### 3.1.1 3d-quaternions/3d-quaternions.asd

Source
Parent Component

3d-quaternions (system).

ASDF Systems

#### 3.1.2 3d-quaternions/package.lisp

Source
Parent Component

3d-quaternions (system).

Packages

#### 3.1.3 3d-quaternions/struct.lisp

Dependency

package.lisp (file).

Source
Parent Component

3d-quaternions (system).

Public Interface
Internals

#### 3.1.4 3d-quaternions/ops.lisp

Dependency

struct.lisp (file).

Source
Parent Component

3d-quaternions (system).

Public Interface
Internals

#### 3.1.5 3d-quaternions/documentation.lisp

Dependency

ops.lisp (file).

Source
Parent Component

3d-quaternions (system).

## 4 Packages

Packages are listed by definition order.

Previous: , Up: Packages   [Contents][Index]

Source
Use List
• 3d-matrices.
• 3d-vectors.
• common-lisp.
Public Interface
Internals

## 5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

Next: , Previous: , Up: Definitions   [Contents][Index]

### 5.1 Public Interface

#### 5.1.1 Macros

Macro: dqsetf (quat real dual)

Update the fields of a dual-quaternion.

Returns the modified dual-quaternion.

See DQUAT

Package
Source
Macro: qsetf (quat x y z w)

Update the fields of a quaternion.

Returns the modified quaternion.

See QUAT

Package
Source

Next: , Previous: , Up: Public Interface   [Contents][Index]

#### 5.1.2 Compiler macros

Compiler Macro: dquat (&optional real dual)
Package
Source
Compiler Macro: nq* (val &rest vals)
Package
Source
Compiler Macro: nq+ (val &rest vals)
Package
Source
Compiler Macro: nq- (val &rest vals)
Package
Source
Compiler Macro: nq/ (val &rest vals)
Package
Source
Compiler Macro: q* (val &rest vals)
Package
Source
Compiler Macro: q+ (val &rest vals)
Package
Source
Compiler Macro: q- (val &rest vals)
Package
Source
Compiler Macro: q/ (val &rest vals)
Package
Source
Compiler Macro: q/= (val &rest vals)
Package
Source
Compiler Macro: q= (val &rest vals)
Package
Source
Compiler Macro: quat (&optional x y z w)
Package
Source

#### 5.1.3 Setf expanders

Setf Expander: (setf qw) (vec)
Package
Source

qw (function).

Setf Expander: (setf qx) (vec)
Package
Source

qx (function).

Setf Expander: (setf qy) (vec)
Package
Source

qy (function).

Setf Expander: (setf qz) (vec)
Package
Source

qz (function).

#### 5.1.4 Ordinary functions

Function: dqcopy (instance)

Returns a fresh copy of the dual-quaternion.

See DQUAT

Package
Source
Function: dquat (&optional real dual)

Constructs a dual-quaternion

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

See DQUAT (type)

Package
Source
Function: dquat-p (object)

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

See DQUAT

Package
Source
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*

Package
Source
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+

Package
Source
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-

Package
Source
Function: nq/ (val &rest vals)
Package
Source
Function: nqexpt (quat exp)

Compute the exponentiation of a quaternion.

Returns the modified quaternion.

See QUAT

Package
Source
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

Package
Source
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*

Package
Source
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

Package
Source
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+

Package
Source
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+

Package
Source
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

Package
Source
Function: q/ (val &rest vals)
Package
Source
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

Package
Source
Function: q<- (target source)

Copies the quaternion information into the target from the source.

Returns the modified quaternion.

See QUAT

Package
Source
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

Package
Source
Function: qangle (quat)

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

See QUAT

Package
Source
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

Package
Source
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

Package
Source
Function: qcopy (instance)

Creates an exact copy of the quaternion.

See QUAT

Package
Source

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

See QUAT
See DQUAT

Package
Source
Target Slot
Writer: (setf qdual) (instance)
Package
Source
Target Slot
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=

Package
Source
Function: qexpt (quat exp)

Compute the exponentiation of a quaternion.

Returns a fresh quaternion.

See QUAT

Package
Source
Function: qfrom-angle (axis angle)

Construct a quaternion from an axis and a rotation.

Returns the freshly constructed quaternion.

See QUAT

Package
Source
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

Package
Source
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

Package
Source
Function: qinv (a)

Returns the inverses of the quaternion.

See QUAT

Package
Source
Function: qlength (a)

Returns the length of the quaternion.

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

See QUAT
See QLENGTH2

Package
Source
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

Package
Source
Function: qlookat (dir up)

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

See QUAT

Package
Source
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

Package
Source
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

Package
Source
Function: qmix (from to x)

Returns a new quaternion mixed with the two.

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

See QUAT

Package
Source
Function: qnlerp (from to x)

Returns the linearly interpolated quaternion between the two.

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

See QUAT

Package
Source
Function: qposition (dquat)

Return the position vector encoded by the dual-quaternion.

See 3D-VECTORS:VEC3
See DQUAT

Package
Source

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

see QUAT
See DQUAT

Package
Source
Target Slot
Writer: (setf qreal) (instance)
Package
Source
Target Slot
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

Package
Source
Function: qtowards (from to)

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

Returns the freshly constructed quaternion.

See QUAT

Package
Source
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)

Package
Source
Function: quat-p (object)

Returns true if the passed object is a quaternion.

See QUAT

Package
Source
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

Package
Source
Function: qw (vec)

Accesses the fourth component of the quaternion.

See QUAT (type)

Package
Source
Setf expander for this function
Function: qx (vec)

Accesses the first component of the quaternion.

See QUAT (type)

Package
Source
Setf expander for this function
Function: qy (vec)

Accesses the second component of the quaternion.

See QUAT (type)

Package
Source
Setf expander for this function
Function: qz (vec)

Accesses the third component of the quaternion.

See QUAT (type)

Package
Source
Setf expander for this function

#### 5.1.5 Standalone methods

Method: make-load-form ((q quat) &optional env)
Source
Method: make-load-form ((d dquat) &optional env)
Source
Method: print-object ((q quat) stream)
Source
Method: print-object ((d dquat) stream)
Source

#### 5.1.6 Structures

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

Package
Source
Direct superclasses

structure-object.

Direct methods
Direct slots
Slot: qreal
Type

org.shirakumo.flare.quaternion:quat

Initform

(org.shirakumo.flare.quaternion:quat)

Writers
Slot: qdual
Type

org.shirakumo.flare.quaternion:quat

Initform

(org.shirakumo.flare.quaternion:quat)

Writers
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

Package
Source
Direct superclasses

vec3.

Direct methods
Direct slots
Slot: %qw
Type

single-float

Initform

(3d-vectors::ensure-float 1)

%qw.

Writers

### 5.2 Internals

Next: , Previous: , Up: Internals   [Contents][Index]

#### 5.2.1 Macros

Macro: %2quat-op (name a b combination qred dqred &optional 2q-override)
Package
Source
Macro: define-nquatop (name op &optional 2q-override)
Package
Source
Macro: define-quatcomp (name op &optional bundle)
Package
Source
Macro: define-quatop (name nname op &optional 2q-override)
Package
Source

Previous: , Up: Internals   [Contents][Index]

#### 5.2.2 Ordinary functions

Function: %dquat (qreal qdual)
Package
Source
Function: %quat (%vx3 %vy3 %vz3 %qw)
Package
Source