Class ObservableQuaternion

A Quaternion that tells an observer when it changes

A node's quaternion is one, so changing it turns the node. It has the same methods as Quaternion. Each in-place method notifies the observer at most once, and not at all when no component changed. Given an out target, a method writes there and leaves this quaternion and its observer alone.

Example

const up = { x: 0, y: 1, z: 0 };

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

Implements

QuaternionData

Index

Constructors

constructor

Accessors

w x y z

Constructors

constructor

new ObservableQuaternion(
    observer: Observer<ObservableQuaternion>,
    x?: number,
    y?: number,
    z?: number,
    w?: number,
): ObservableQuaternion
Creates a new ObservableQuaternion, defaulting to identity (0, 0, 0, 1)
Parameters
- observer: Observer<ObservableQuaternion>
  Observer notified when any component changes
- 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 ObservableQuaternion

Accessors

w

get w(): number
The w component; assigning a different value notifies the observer

Returns number
Example
```
const angle = 2 * Math.acos(node.quaternion.w);
```
Implementation of QuaternionData.w
set w(value: number): void
Sets the w component
Parameters
- value: number
  New w component
Returns void

Implementation of QuaternionData.w

x

get x(): number
The x component; assigning a different value notifies the observer

Returns number
Example
```
const axisX = node.quaternion.x / Math.sqrt(1 - node.quaternion.w ** 2);
```
Implementation of QuaternionData.x
set x(value: number): void
Sets the x component
Parameters
- value: number
  New x component
Returns void

Implementation of QuaternionData.x

y

get y(): number
The y component; assigning a different value notifies the observer

Returns number
Example
```
const axisY = node.quaternion.y / Math.sqrt(1 - node.quaternion.w ** 2);
```
Implementation of QuaternionData.y
set y(value: number): void
Sets the y component
Parameters
- value: number
  New y component
Returns void

Implementation of QuaternionData.y

z

get z(): number
The z component; assigning a different value notifies the observer

Returns number
Example
```
const axisZ = node.quaternion.z / Math.sqrt(1 - node.quaternion.w ** 2);
```
Implementation of QuaternionData.z
set z(value: number): void
Sets the z component
Parameters
- value: number
  New z component
Returns void

Implementation of QuaternionData.z

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 (turret.quaternion.angleTo(aimRotation) < 0.01) fire();
```

clone

clone(observer?: Observer<ObservableQuaternion>): ObservableQuaternion
Creates a copy of this quaternion that notifies observer, or this quaternion's observer when left out

A copy of a node's quaternion that keeps the node as its observer makes the node recompute its transform on every change, though the node doesn't turn. For a plain copy, use new Quaternion().copyFrom(node.quaternion).
Parameters
- Optionalobserver: Observer<ObservableQuaternion>
  Observer for the copy
Returns ObservableQuaternion
The new quaternion

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
```
const reverseTurn = door.quaternion.conjugate(new Quaternion());
```

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
```
door.quaternion.copyFrom(closedRotation);
```

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
```
door.quaternion.copyTo(closedRotation);
```

dot

dot(q: QuaternionData): number
Returns the dot product of this quaternion and q
Parameters
- q: QuaternionData
  The other quaternion
Returns number
The dot product
Example
```
const facingTarget = Math.abs(turret.quaternion.dot(aimRotation)) > 0.99999;
```

equals

equals(q: QuaternionData): boolean
Returns true when x, y, z and w match q exactly, with no tolerance
Parameters
- q: QuaternionData
  The quaternion to compare with
Returns boolean
Whether all components match
Example
```
const closed = door.quaternion.equals(closedRotation);
```

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
```
crates.forEach((crate: Container3D, i: number) => crate.quaternion.fromArray(savedRotations, i * 4));
```

identity

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

Returns this
This quaternion for chaining
Example
```
crate.quaternion.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.
Parameters
- out: QuaternionData = ...
  Target to write the result into instead of this quaternion
Returns this
The result quaternion for chaining
Example
```
turret.quaternion.inverse(parentToTurret);
```

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(ship.quaternion.magnitude() - 1) > 1e-6) ship.quaternion.normalize();
```

magnitudeSquared

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

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

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

multiply

multiply(q: QuaternionData, out?: QuaternionData): this
Multiplies this quaternion by q (this = this * q), turning the node by q around its own axes

Quaternion#multiply explains the order.
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);
ship.quaternion.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
```
ship.quaternion.multiply(roll).normalize();
```

premultiply

premultiply(q: QuaternionData, out?: QuaternionData): this
Pre-multiplies this quaternion by q (this = q * this), turning the node by q around its parent's axes
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);
globe.quaternion.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
```
door.quaternion.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
```
wheel.quaternion.setFromAxisAngle({ x: 1, y: 0, z: 0 }, distanceDriven / wheelRadius);
```

setFromEuler

setFromEuler(rotation: PointData3D, out?: QuaternionData): this
Sets this quaternion from Euler angles in radians, in the XYZ order of Container3D#rotation
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
```
door.quaternion.setFromEuler({ x: 0, y: openAngle, 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 ObservableQuaternion#setFromScaledRotationMatrix for a matrix with scale.
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
```
securityCamera.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

Quaternion#setFromScaledRotationMatrix says what a zero or mirrored scale gives.
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
```
debris.quaternion.setFromScaledRotationMatrix(wreck.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

Quaternion#setFromUnitVectors says what happens when they point opposite ways.
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
```
tree.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
```
turret.quaternion.slerp(aimRotation, 1 - Math.exp(-turnRate * dt));
```

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
```
crates.forEach((crate: Container3D, i: number) => crate.quaternion.toArray(savedRotations, i * 4));
```

toString

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

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

Class ObservableQuaternion

Example

Implements

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns ObservableQuaternion

Accessors

w

Returns number

Example

Parameters

Returns void

x

Returns number

Example

Parameters

Returns void

y

Returns number

Example

Parameters

Returns void

z

Returns number

Example

Parameters

Returns void

Methods

angleTo

Parameters

Returns number

Example

clone

Parameters

Returns ObservableQuaternion

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