Class Quaternion

A rotation in 3D, stored as four numbers (x, y, z, w)

Unlike Euler angles, a quaternion doesn't lose a degree of freedom when two axes line up, and Quaternion#slerp blends between two of them smoothly. QuaternionData says what the four numbers mean. A rotation quaternion has length 1. Most methods assume so, and long chains of Quaternion#multiply drift from it, which Quaternion#normalize fixes.

Methods change the quaternion they're called on and return it, so calls chain. Pass an out target last to write the result there instead and leave this one as it is.

Example

const up = { x: 0, y: 1, z: 0 };
const spin = new Quaternion();

app.ticker.add((ticker) => {
  spin.setFromAxisAngle(up, spinSpeed * (ticker.deltaMS / 1000));
  coin.quaternion.multiply(spin);
});

See

Vector3#applyQuaternion For applying a quaternion rotation to a point

Implements

QuaternionData

Index

Constructors

constructor

new Quaternion(x?: number, y?: number, z?: number, w?: number): Quaternion
Creates a new Quaternion, defaulting to identity (0, 0, 0, 1)
Parameters
- x: number = 0
  The x component
- y: number = 0
  The y component
- z: number = 0
  The z component
- w: number = 1
  The w component
Returns Quaternion

Properties

w

w: number = 0

The w component; QuaternionData says what it means

Example

const angle = 2 * Math.acos(rotation.w);

x

x: number = 0

The x component; QuaternionData says what it means

Example

const axisX = rotation.x / Math.sqrt(1 - rotation.w * rotation.w);

y

y: number = 0

The y component; QuaternionData says what it means

Example

const axisY = rotation.y / Math.sqrt(1 - rotation.w * rotation.w);

z

z: number = 0

The z component; QuaternionData says what it means

Example

const axisZ = rotation.z / Math.sqrt(1 - rotation.w * rotation.w);

Accessors

`Static`shared

get shared(): Quaternion
A static Quaternion reset to identity on every access, for a result used straight away

Important
This quaternion is shared and temporary. Do not store references to it.

Returns Quaternion
Example
```
kickOffset.applyQuaternion(Quaternion.shared.setFromEuler(recoil));
```

Methods

angleTo

angleTo(q: QuaternionData): number
Returns the angle of the turn from this rotation to q

Both quaternions are assumed unit-length.
Parameters
- q: QuaternionData
  The other quaternion
Returns number
The angle in radians, from 0 to π
Example
```
if (aimRotation.angleTo(targetRotation) < 0.01) fire();
```

clone

clone(): Quaternion
Creates a new Quaternion with the same values

Returns Quaternion
The new quaternion
Example
```
const restRotation = aimRotation.clone();
```

conjugate

conjugate(out?: QuaternionData): this
Negates x, y and z, leaving w, which reverses a unit quaternion's turn
Parameters
- out: QuaternionData = ...
  Target to write the result into instead of this quaternion
Returns this
The result quaternion for chaining
Example
```
recoil.conjugate(recovery);
```

copyFrom

copyFrom(q: QuaternionData): this
Copies q into this quaternion
Parameters
- q: QuaternionData
  The quaternion to copy from
Returns this
This quaternion for chaining
Example
```
savedRotation.copyFrom(door.quaternion);
```

copyTo

copyTo<T extends QuaternionData>(target: T): T
Copies this quaternion into target and returns it
Type Parameters
- T extends QuaternionData
Parameters
- target: T
  The quaternion to copy into
Returns T
The given target
Example
```
savedRotation.copyTo(door.quaternion);
```

dot

dot(q: QuaternionData): number
Returns the dot product of this quaternion and q

For unit quaternions its absolute value is the cosine of half the angle between the two rotations: 1 for the same rotation.
Parameters
- q: QuaternionData
  The other quaternion
Returns number
The dot product
Example
```
const sameRotation = Math.abs(current.dot(target)) > 0.99999;
```

equals

equals(q: QuaternionData): boolean
Returns true when x, y, z and w match q exactly, with no tolerance

q and its negation are the same rotation but don't compare equal.
Parameters
- q: QuaternionData
  The quaternion to compare with
Returns boolean
Whether all components match
Example
```
if (!aimRotation.equals(lastAimRotation)) updateCrosshair();
```

fromArray

fromArray(
array: Float32Array<ArrayBufferLike> | number[],
offset?: number,
): this
Reads x, y, z, w from array starting at offset
Parameters
- array: Float32Array<ArrayBufferLike> | number[]
  The array to read from
- offset: number = 0
  The offset into array to read at
Returns this
This quaternion for chaining
Example
```
keyRotation.fromArray(keyframes, frame * 4);
```

identity

identity(): this
Resets this quaternion to identity (0, 0, 0, 1), no rotation

Returns this
This quaternion for chaining
Example
```
aimOffset.identity();
```

inverse

inverse(out?: QuaternionData): this
Inverts this rotation, so it turns the other way

Computes the conjugate, which is the inverse of a unit quaternion. For any other quaternion, call Quaternion#normalize first.
Parameters
- out: QuaternionData = ...
  Target to write the result into instead of this quaternion
Returns this
The result quaternion for chaining
Example
```
parentWorldRotation.inverse(worldToLocal);
direction.applyQuaternion(worldToLocal);
```

magnitude

magnitude(): number
Returns the length of this quaternion as a 4D vector, 1 for a rotation

Returns number
The magnitude
Example
```
if (Math.abs(rotation.magnitude() - 1) > 1e-6) rotation.normalize();
```

magnitudeSquared

magnitudeSquared(): number
Returns the squared length of this quaternion

Cheaper than Quaternion#magnitude and enough to check for drift.

Returns number
The squared magnitude
Example
```
if (Math.abs(rotation.magnitudeSquared() - 1) > 1e-6) rotation.normalize();
```

multiply

multiply(q: QuaternionData, out?: QuaternionData): this
Multiplies this quaternion by q (this = this * q)

The result turns by q first, then by this. On a node's rotation, that turns by q around the node's own axes; Quaternion#premultiply turns around its parent's axes.
Parameters
- q: QuaternionData
  The quaternion to multiply by
- out: QuaternionData = ...
  Target to write the result into instead of this quaternion
Returns this
The result quaternion for chaining
Example
```
roll.setFromAxisAngle(forwardAxis, rollSpeed * dt);
shipRotation.multiply(roll);
```

normalize

normalize(out?: QuaternionData): this
Scales this quaternion to unit length, undoing the drift of repeated multiplies

A zero quaternion becomes identity.
Parameters
- out: QuaternionData = ...
  Target to write the result into instead of this quaternion
Returns this
The result quaternion for chaining
Example
```
rotation.multiply(step).normalize();
```

premultiply

premultiply(q: QuaternionData, out?: QuaternionData): this
Pre-multiplies this quaternion by q (this = q * this)

The result turns by this first, then by q. On a node's rotation, that turns by q around the parent's axes; Quaternion#multiply turns around the node's own.
Parameters
- q: QuaternionData
  The quaternion to pre-multiply by
- out: QuaternionData = ...
  Target to write the result into instead of this quaternion
Returns this
The result quaternion for chaining
Example
```
spin.setFromAxisAngle(worldUp, spinSpeed * dt);
globeRotation.premultiply(spin);
```

set

set(x: number, y: number, z: number, w: number): this
Sets the components of this quaternion
Parameters
- x: number
  The x component
- y: number
  The y component
- z: number
  The z component
- w: number
  The w component
Returns this
This quaternion for chaining
Example
```
rotation.set(0, Math.SQRT1_2, 0, Math.SQRT1_2);
```

setFromAxisAngle

setFromAxisAngle(axis: PointData3D, angle: number, out?: QuaternionData): this
Sets this quaternion to a turn of angle radians around the unit-length axis
Parameters
- axis: PointData3D
  The unit-length rotation axis
- angle: number
  The rotation angle in radians
- out: QuaternionData = ...
  Target to write the result into instead of this quaternion
Returns this
The result quaternion for chaining
Example
```
const up = { x: 0, y: 1, z: 0 };

Quaternion.shared.setFromAxisAngle(up, yaw, rigidBody.quaternion);
```

setFromEuler

setFromEuler(rotation: PointData3D, out?: QuaternionData): this
Sets this quaternion from Euler angles in radians

Uses the XYZ order of Container3D#rotation, so it gives the rotation a node with those angles has.
Parameters
- rotation: PointData3D
  The Euler angles as (x, y, z) radians
- out: QuaternionData = ...
  Target to write the result into instead of this quaternion
Returns this
The result quaternion for chaining
Example
```
const facing = new Quaternion().setFromEuler({ x: 0, y: heading, z: 0 });
```

setFromRotationMatrix

setFromRotationMatrix(m: Matrix4, out?: QuaternionData): this
Sets this quaternion to the rotation in m

The upper-left 3x3 of m must be a pure rotation, with no scale. Use Quaternion#setFromScaledRotationMatrix for a matrix with scale, such as a node's world transform.
Parameters
- m: Matrix4
  The rotation matrix to extract from
- out: QuaternionData = ...
  Target to write the result into instead of this quaternion
Returns this
The result quaternion for chaining
Example
```
const cameraRotation = new Quaternion().setFromRotationMatrix(new Matrix4().lookAt(eye, target, up));
```

setFromScaledRotationMatrix

setFromScaledRotationMatrix(m: Matrix4, out?: QuaternionData): this
Sets this quaternion to the rotation in m, a transform that may also scale each axis

A matrix with a zero scale has no rotation to read and gives NaN. A mirrored one (negative determinant) gives a quaternion that isn't a rotation; Matrix4#decompose handles it.
Parameters
- m: Matrix4
  The transform to extract from
- out: QuaternionData = ...
  Target to write the result into instead of this quaternion
Returns this
The result quaternion for chaining
Example
```
const worldRotation = new Quaternion().setFromScaledRotationMatrix(node.worldTransform);
```

setFromUnitVectors

setFromUnitVectors(
    vFrom: PointData3D,
    vTo: PointData3D,
    out?: QuaternionData,
): this
Sets this quaternion to the shortest turn that takes unit-length vFrom to unit-length vTo

When vTo points exactly opposite vFrom, the result is a half turn around some axis at right angles to vFrom.
Parameters
- vFrom: PointData3D
  The unit-length start direction
- vTo: PointData3D
  The unit-length end direction
- out: QuaternionData = ...
  Target to write the result into instead of this quaternion
Returns this
The result quaternion for chaining
Example
```
const tilt = new Quaternion().setFromUnitVectors({ x: 0, y: 1, z: 0 }, groundNormal);
```

slerp

slerp(qb: QuaternionData, t: number, out?: QuaternionData): this
Blends from this rotation toward qb by t, turning at an even rate the shorter way round
Parameters
- qb: QuaternionData
  The quaternion to interpolate towards
- t: number
  The interpolation factor in [0, 1]
- out: QuaternionData = ...
  Target to write the result into instead of this quaternion
Returns this
The result quaternion for chaining
Example
```
aimRotation.slerp(targetRotation, 1 - Math.exp(-turnRate * dt));
fromRotation.slerp(toRotation, t, blended);
```

toArray

toArray<T extends Float32Array<ArrayBufferLike> | number[] = number[]>(
array?: T,
offset?: number,
): T
Writes this quaternion's values into array starting at offset
Type Parameters
- T extends Float32Array<ArrayBufferLike> | number[] = number[]
Parameters
- array: T = ...
  The array to write into; a new array when omitted
- offset: number = 0
  The offset into array to write at
Returns T
The written array
Example
```
rotation.toArray(instanceRotations, instanceIndex * 4);
```

toString

toString(): string
Returns a string representation of this quaternion

Returns string
A string in the form [@pixi/3d/math:Quaternion x=0 y=0 z=0 w=1]
Example
```
console.log(aimRotation.toString());
```

`Static`slerpFlat

slerpFlat(
    dst: number[],
    dstOffset: number,
    src0: number[],
    srcOffset0: number,
    src1: number[],
    srcOffset1: number,
    t: number,
): void
Advanced
Spherically interpolates between two quaternions stored in flat arrays, writing the result into dst without creating a Quaternion

Like Quaternion#slerp, it takes the shorter way round. It costs one Math.sin where the textbook form costs three, so it suits blending many rotations every frame.
Parameters
- dst: number[]
  The array to write the result into
- dstOffset: number
  The offset into dst to write at
- src0: number[]
  The array holding the start quaternion
- srcOffset0: number
  The offset into src0 to read from
- src1: number[]
  The array holding the end quaternion
- srcOffset1: number
  The offset into src1 to read from
- t: number
  The interpolation factor in [0, 1]
Returns void
Example
```
Quaternion.slerpFlat(pose, boneIndex * 4, keyframes, frame * 4, keyframes, (frame + 1) * 4, blend);
```

Class Quaternion

Example

See

Implements

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns Quaternion

Properties

w

Example

x

Example

y

Example

z

Example

Accessors

Staticshared

Returns Quaternion

Example

Methods

angleTo

Parameters

Returns number

Example

clone

Returns Quaternion

Example

conjugate

Parameters

Returns this

Example

copyFrom

Parameters

Returns this

Example

copyTo

Type Parameters

Parameters

Returns T

Example

dot

Parameters

Returns number

Example

equals

Parameters

Returns boolean

Example

fromArray

Parameters

Returns this

Example

identity

Returns this

Example

inverse

Parameters

Returns this

Example

magnitude

Returns number

Example

magnitudeSquared

Returns number

Example

multiply

Parameters

Returns this

Example

normalize

Parameters

Returns this

Example

`Static`shared

`Static`slerpFlat