Quaternion.js - ℍ in JavaScript


Quaternion.js is a well tested JavaScript library for 3D rotations. Quaternions can be used everywhere, from the rotation calculation of your mobile phone over computer games to the rotation of satellites and all by avoiding the Gimbal lock. The library comes with examples to make you get started much quicker without worrying about the math behind. But if you care, have a look at the Quaternion Introduction.

Examples

``js
const Quaternion = require('quaternion');

const q = new Quaternion("99.3+8i");
c.mul(1,2,3,4).div([3,4,1]).sub(7, [1, 2, 3]);
`

$3

In order to create a HTML element, which always rotates in 3D with your mobile device, all you need is the following snippet. Look at the examples folder for a complete version.

`javascript
const deg = Math.PI / 180;
window.addEventListener("deviceorientation", function(ev) {

// Update the rotation object
const q = Quaternion.fromEulerLogical(ev.alpha deg, ev.beta deg, -ev.gamma * deg, 'ZXY');

// Set the CSS style to the element you want to rotate
elm.style.transform = q.toCSSTransform();

}, true);
`

Parser


Any function (see below) as well as the constructor of the Quaternion class parses its input like this.

You can pass either Objects, Doubles or Strings.

$3


Calling the constructor with no parameters will create a unit quaternion.

`javascript
new Quaternion() // 1 + 0i + 0j + 0k
`

The typical use case contains all quaternion parameters

`javascript
new Quaternion(w, x, y, z)
`

$3

Quaternion as angle and vector. Note: This is not equivalent to Quaternion.fromAxisAngle()!

`javascript
new Quaternion(w, [x, y, z])
`

Quaternion as an object (it's ok to leave components out)
`javascript
new Quaternion({w: w, x: x, y: y, z: z})
`

Quaternion out of a complex number, e.g. Complex.js, with y=z=0.
`javascript
new Quaternion({re: real, im: imaginary})
`

Quaternion out of a 4 elements vector
`javascript
new Quaternion([w, x, y, z])
`
Augmented Quaternion out of a 3 elements vector
`javascript
new Quaternion([x, y, z])
`

$3

`javascript
new Quaternion(55.4);
`

$3

`javascript
new Quaternion('1 - 2i - 3j - 4k')
new Quaternion("123.45");
new Quaternion("15+3i");
new Quaternion("i");
`

Functions


Every stated parameter n in the following list of functions behaves in the same way as the constructor examples above

Note: Calling a method like add() without parameters passes a quaternion with all elements zero, not one!

$3

Adds two quaternions Q1 and Q2

$3

Subtracts a quaternions Q2 from Q1

$3

Calculates the additive inverse, or simply it negates the quaternion

$3

Calculates the length/modulus/magnitude or the norm of a quaternion

$3

Calculates the squared length/modulus/magnitude or the norm of a quaternion

$3

Normalizes the quaternion to have |Q| = 1 as long as the norm is not zero. Alternative names are the signum, unit or versor

$3

Calculates the Hamilton product of two quaternions. Leaving out the imaginary part results in just scaling the quat.

Note: This function is not commutative, i.e. order matters!

$3

Scales a quaternion by a scalar, faster than using multiplication

$3

Calculates the dot product of two quaternions

$3

Calculates the inverse of a quat for non-normalized quats such that Q-1 Q = 1 and Q Q-1 = 1

$3

Multiplies a quaternion with the inverse of a second quaternion

$3

Calculates the conjugate of a quaternion. If the quaternion is normalized, the conjugate is the inverse of the quaternion - but faster.

$3

Calculates the power of a quaternion raised to the quaternion n

$3

Calculates the natural exponentiation of the quaternion

$3

Calculates the natural logarithm of the quaternion

$3

Returns the real w part of the quaternion

$3

Returns the imaginary part [x, y, z] of the quaternion as a 3D vector / array

$3

Checks if two quats are the same

$3

Checks if all parts of a quaternion are finite

$3

Checks if any of the parts of the quaternion is not a number

$3

Checks if the quaternion is a unit quaternion of length 1.

$3

Gets the Quaternion as a well formatted string

$3

Gets the actual quaternion as a 4D vector / array

$3

Calculates the 3x3 rotation matrix for the current quat as a 9 element array or alternatively as a 2D array

$3

Calculates the homogeneous 4x4 rotation matrix for the current quat as a 16 element array or alternatively as a 2D array

$3

Determines the homogeneous rotation matrix string used for CSS 3D transforms

$3

Calculates the axis and angle representation of the current quaternion

$3

Calculates the Euler angles represented by the current quat in the given Tait-Bryan order. The returned triplet order matches the order string.

$3

Clones the current object

$3

Rotates a 3 component vector, represented as an [x,y,z] array or an {x,y,z} object using the current quaternion in an efficient manner.

$3

Returns a function to spherically interpolate between two quaternions. Called with a percentage [0, 1], the function returns the interpolated Quaternion.

$3

Gets a quaternion by a rotation given as an axis and angle

$3

Gets a quaternion given a rotation matrix, either as a 1x9 array or a 3x3 array.

$3

Euler angles are probably the reason to use quaternions. The definition is mostly sloppy and you can only decide how it was defined based on the matrix representation. A ZXY in one definition is the multiplication order read from right to left and in another the execution order from left to right. Quaternion.js provides two functions, fromEulerLogical(), where the angles and order are applied from left to right (logical application order) and fromEuler() which reverses the order of the argument list (technical multiplication order).

So for fromEulerLogical(ϕ, θ, ψ, "ZXY"), for example means first rotate around Z axis by ϕ then around X axis by θ and then around axis Y by ψ (RotY(ψ)RotX(θ)RotZ(ϕ)).

The order of fromEuler() can take the string value ZXY (default), XYZ / RPY, YXZ, ZYX / YPR, YZX, XZY, ZYZ, ZXZ, YXY, YZY, XYX, XZX.

#### Relations

- fromEulerLogical(ϕ, θ, ψ, 'ZYX') = axisAngle([1, 0, 0], ψ) axisAngle([0, 1, 0], θ) axisAngle([0, 0, 1], ϕ)
- fromEulerLogical(ϕ, θ, ψ, 'ZYX') = fromEuler(ψ, θ, ϕ, 'YXZ')
- Mathematica RollPitchYawMatrix[{α, β, γ}] = fromEulerLogical(α, β, γ, 'ZYX')
- W3C devicemotion fromEulerLogical(ev.alpha DEG, ev.beta DEG, -ev.gamma * DEG, 'ZXY')
- Three.js chose a different argument format:
- fromEuler(x, y, z, 'XYZ') = ThreeJSfromEuler(x, y, z, 'XYZ')
- fromEuler(x, y, z, 'YXZ') = ThreeJSfromEuler(y, x, z, 'YXZ')
- fromEuler(x, y, z, 'ZXY') = ThreeJSfromEuler(y, z, x, 'ZXY')
- fromEuler(x, y, z, 'ZYX') = ThreeJSfromEuler(z, y, x, 'ZYX')
- fromEuler(x, y, z, 'YZX') = ThreeJSfromEuler(z, x, y, 'YZX')
- fromEuler(x, y, z, 'XZY') = ThreeJSfromEuler(x, z, y, 'XZY')

$3

Calculates the quaternion to rotate vector u onto vector v, represented as 3 element arrays, which can be done elegantly using quaternions.

$3

Gets a spherical random number

Constants

$3

A quaternion zero instance (additive identity)

$3

A quaternion one instance (multiplicative identity)

$3

An imaginary number i instance

$3

An imaginary number j instance

$3

An imaginary number k instance

Installation

You can install Quaternion.js via npm:

`bash
npm install quaternion
`

Or with yarn:

`bash
yarn add quaternion
`

Alternatively, download or clone the repository:

`bash
git clone https://github.com/rawify/Quaternion.js
`

Usage

Include the quaternion.min.js file in your project:

`html


`

Or in a Node.js project:

`javascript
const Quaternion = require('quaternion');
`

or

`javascript
import Quaternion from 'quaternion';
`

Coding Style

Like all my libraries, Quaternion.js is written to minimize size after compression with Google Closure Compiler in advanced mode. The code style is optimized to maximize compressibility. If you extend the library, please preserve this style.

Building the library

After cloning the Git repository run:

`
npm install
npm run build
`

Run a test

Testing the source against the shipped test suite is as easy as

`
npm run test
``

Copyright and Licensing

Copyright (c) 2025, Robert Eisele
Licensed under the MIT license.