# Quat

Class · category: Math

Source: https://github.com/playcanvas/engine/blob/b5b983982a9860d21e0c1dafb2f85f72e2c01afb/src/core/math/quat.js#L15

A quaternion representing rotation in 3D space. Quaternions are typically used to represent
rotations in 3D applications, offering advantages over Euler angles including no gimbal lock and
more efficient interpolation.

## Constructors

### constructor

```ts
new Quat(x?: number, y?: number, z?: number, w?: number)
```

Creates a new Quat instance.

**Parameters**

- `x` (`number`, optional): The x value. Defaults to 0.
- `y` (`number`, optional): The y value. Defaults to 0.
- `z` (`number`, optional): The z value. Defaults to 0.
- `w` (`number`, optional): The w value. Defaults to 1.

**Example**

```ts
const q1 = new Quat(); // defaults to 0, 0, 0, 1
const q2 = new Quat(1, 2, 3, 4);
```

```ts
new Quat(arr: number[])
```

Creates a new Quat instance.

**Parameters**

- `arr` (`number[]`): The array to set the quaternion values from.

**Example**

```ts
const q = new Quat([1, 2, 3, 4]);
```

## Properties

### w

```ts
w: number
```

The w component of the quaternion.

### x

```ts
x: number
```

The x component of the quaternion.

### y

```ts
y: number
```

The y component of the quaternion.

### z

```ts
z: number
```

The z component of the quaternion.

### IDENTITY

```ts
static readonly IDENTITY: Quat
```

A constant quaternion set to [0, 0, 0, 1] (the identity). Represents no rotation.

### ZERO

```ts
static readonly ZERO: Quat
```

A constant quaternion set to [0, 0, 0, 0].

## Methods

### clone

```ts
clone(): Quat
```

Returns an identical copy of the specified quaternion.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): A new quaternion identical to this one.

**Example**

```ts
const q = new Quat(-0.11, -0.15, -0.46, 0.87);
const qclone = q.clone();

console.log("The result of the cloning is: " + qclone.toString());
```

### copy

```ts
copy(rhs: Quat): Quat
```

Copies the contents of a source quaternion to a destination quaternion.

**Parameters**

- `rhs` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md)): The quaternion to be copied.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): Self for chaining.

**Example**

```ts
const src = new Quat();
const dst = new Quat();
dst.copy(src);
console.log("The two quaternions are " + (src.equals(dst) ? "equal" : "different"));
```

### dot

```ts
dot(other: Quat): number
```

Calculates the dot product of two quaternions.

**Parameters**

- `other` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md)): The quaternion to calculate the dot product with.

**Returns** `number`: The dot product of the two quaternions.

**Example**

```ts
const a = new Quat(1, 0, 0, 0);
const b = new Quat(0, 1, 0, 0);
console.log("Dot product: " + a.dot(b)); // Outputs 0
```

### equals

```ts
equals(rhs: Quat): boolean
```

Reports whether two quaternions are equal.

**Parameters**

- `rhs` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md)): The quaternion to be compared against.

**Returns** `boolean`: True if the quaternions are equal and false otherwise.

**Example**

```ts
const a = new Quat();
const b = new Quat();
console.log("The two quaternions are " + (a.equals(b) ? "equal" : "different"));
```

### equalsApprox

```ts
equalsApprox(rhs: Quat, epsilon?: number): boolean
```

Reports whether two quaternions are equal using an absolute error tolerance.

**Parameters**

- `rhs` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md)): The quaternion to be compared against.
- `epsilon` (`number`, optional, default `1e-6`): The maximum difference between each component of the two
  quaternions. Defaults to 1e-6.

**Returns** `boolean`: True if the quaternions are equal and false otherwise.

**Example**

```ts
const a = new Quat();
const b = new Quat();
console.log("The two quaternions are approximately " + (a.equalsApprox(b, 1e-9) ? "equal" : "different"));
```

### fromArray

```ts
fromArray(arr: number[] | ArrayBufferView<ArrayBufferLike>, offset?: number): Quat
```

Set the values of the quaternion from an array.

**Parameters**

- `arr` (`number[] | ArrayBufferView<ArrayBufferLike>`): The array to set the quaternion values from.
- `offset` (`number`, optional, default `0`): The zero-based index at which to start copying elements from the
  array. Default is 0.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): Self for chaining.

**Example**

```ts
const q = new Quat();
q.fromArray([20, 10, 5, 0]);
// q is set to [20, 10, 5, 0]
```

### getAxisAngle

```ts
getAxisAngle(axis: Vec3): number
```

Gets the rotation axis and angle for a given quaternion. If a quaternion is created with
`setFromAxisAngle`, this method will return the same values as provided in the original
parameter list OR functionally equivalent values.

**Parameters**

- `axis` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The 3-dimensional vector to receive the axis of rotation.

**Returns** `number`: Angle, in degrees, of the rotation.

**Example**

```ts
const q = new Quat();
q.setFromAxisAngle(new Vec3(0, 1, 0), 90);
const v = new Vec3();
const angle = q.getAxisAngle(v);
// Outputs 90
console.log(angle);
// Outputs [0, 1, 0]
console.log(v.toString());
```

### getEulerAngles

```ts
getEulerAngles(eulers?: Vec3): Vec3
```

Converts this quaternion to Euler angles, specified in degrees. The decomposition uses an
**intrinsic XYZ** order, representing the angles required to achieve the quaternion's
orientation by rotating sequentially: first around the X-axis, then around the newly
transformed Y-axis, and finally around the resulting Z-axis.

**Parameters**

- `eulers` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md), optional): An optional 3-dimensional vector to receive the calculated
  Euler angles (output parameter). If not provided, a new Vec3 object will be allocated
  and returned.

**Returns** [`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md): The 3-dimensional vector holding the Euler angles in degrees. This will be
the same object passed in as the `eulers` parameter (if one was provided).

**Example**

```ts
const q = new Quat();
q.setFromAxisAngle(Vec3.UP, 90);
const e = new Vec3();
q.getEulerAngles(e);
// Outputs [0, 90, 0]
console.log(e.toString());
```

### invert

```ts
invert(src?: Quat): Quat
```

Generates the inverse of the specified quaternion.

**Parameters**

- `src` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md), optional): The quaternion to invert. If not set, the operation is done in place.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): Self for chaining.

**Example**

```ts
// Create a quaternion rotated 180 degrees around the y-axis
const rot = new Quat().setFromEulerAngles(0, 180, 0);

// Invert in place
rot.invert();
```

### length

```ts
length(): number
```

Returns the magnitude of the specified quaternion.

**Returns** `number`: The magnitude of the specified quaternion.

**Example**

```ts
const q = new Quat(0, 0, 0, 5);
const len = q.length();
// Outputs 5
console.log("The length of the quaternion is: " + len);
```

### lengthSq

```ts
lengthSq(): number
```

Returns the magnitude squared of the specified quaternion.

**Returns** `number`: The magnitude squared of the quaternion.

**Example**

```ts
const q = new Quat(3, 4, 0, 0);
const lenSq = q.lengthSq();
// Outputs 25
console.log("The length squared of the quaternion is: " + lenSq);
```

### lerp

```ts
lerp(lhs: Quat, rhs: Quat, alpha: number): Quat
```

Performs a linear interpolation between two quaternions. The result of the interpolation
is written to the quaternion calling the function.

**Parameters**

- `lhs` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md)): The quaternion to interpolate from.
- `rhs` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md)): The quaternion to interpolate to.
- `alpha` (`number`): The unclamped interpolation factor. Values between 0 and 1 interpolate
  between lhs and rhs; values outside this range extrapolate beyond them.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): Self for chaining.

**Example**

```ts
const q1 = new Quat(-0.11, -0.15, -0.46, 0.87);
const q2 = new Quat(-0.21, -0.21, -0.67, 0.68);

const result = new Quat();
result.lerp(q1, q2, 0);   // Return q1
result.lerp(q1, q2, 0.5); // Return the midpoint interpolant
result.lerp(q1, q2, 1);   // Return q2
```

### mul

```ts
mul(rhs: Quat): Quat
```

Returns the result of multiplying the specified quaternions together.

**Parameters**

- `rhs` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md)): The quaternion used as the second multiplicand of the operation.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): Self for chaining.

**Example**

```ts
const a = new Quat().setFromEulerAngles(0, 30, 0);
const b = new Quat().setFromEulerAngles(0, 60, 0);

// a becomes a 90 degree rotation around the Y axis
// In other words, a = a * b
a.mul(b);

console.log("The result of the multiplication is: " + a.toString());
```

### mul2

```ts
mul2(lhs: Quat, rhs: Quat): Quat
```

Returns the result of multiplying the specified quaternions together.

**Parameters**

- `lhs` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md)): The quaternion used as the first multiplicand of the operation.
- `rhs` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md)): The quaternion used as the second multiplicand of the operation.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): Self for chaining.

**Example**

```ts
const a = new Quat().setFromEulerAngles(0, 30, 0);
const b = new Quat().setFromEulerAngles(0, 60, 0);
const r = new Quat();

// r is set to a 90 degree rotation around the Y axis
// In other words, r = a * b
r.mul2(a, b);
```

### mulScalar

```ts
mulScalar(scalar: number, src?: Quat): Quat
```

Multiplies each element of a quaternion by a number.

**Parameters**

- `scalar` (`number`): The number to multiply by.
- `src` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md), optional): The quaternion to scale. If not set, the operation is done in place.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): Self for chaining.

**Example**

```ts
const q = new Quat(1, 2, 3, 4);
q.mulScalar(2);
// q is now [2, 4, 6, 8]
```

### normalize

```ts
normalize(src?: Quat): Quat
```

Normalizes the specified quaternion.

**Parameters**

- `src` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md), optional): The quaternion to normalize. If not set, the operation is done in place.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): Self for chaining.

**Example**

```ts
const v = new Quat(0, 0, 0, 5);
v.normalize();
// Outputs [0, 0, 0, 1]
console.log(v.toString());
```

### set

```ts
set(x: number, y: number, z: number, w: number): Quat
```

Sets the specified quaternion to the supplied numerical values.

**Parameters**

- `x` (`number`): The x component of the quaternion.
- `y` (`number`): The y component of the quaternion.
- `z` (`number`): The z component of the quaternion.
- `w` (`number`): The w component of the quaternion.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): Self for chaining.

**Example**

```ts
const q = new Quat();
q.set(1, 0, 0, 0);

// Outputs 1, 0, 0, 0
console.log("The result of the quaternion set is: " + q.toString());
```

### setFromAxisAngle

```ts
setFromAxisAngle(axis: Vec3, angle: number): Quat
```

Sets a quaternion from an angular rotation around an axis.

**Parameters**

- `axis` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): World space axis around which to rotate. Should be normalized.
- `angle` (`number`): Angle to rotate around the given axis in degrees.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): Self for chaining.

**Example**

```ts
const q = new Quat();
q.setFromAxisAngle(Vec3.UP, 90);
```

### setFromDirections

```ts
setFromDirections(from: Vec3, to: Vec3): Quat
```

Set the quaternion that represents the shortest rotation from one direction to another.

**Parameters**

- `from` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The direction to rotate from. It should be normalized.
- `to` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The direction to rotate to. It should be normalized.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): Self for chaining.

**Example**

```ts
const q = new Quat();
const from = new Vec3(0, 0, 1);
const to = new Vec3(0, 1, 0);
q.setFromDirections(from, to);
```

### setFromEulerAngles

```ts
setFromEulerAngles(ex: number | Vec3, ey?: number, ez?: number): Quat
```

Sets this quaternion to represent a rotation specified by Euler angles in degrees.
The rotation is applied using an **intrinsic XYZ** order: first around the X-axis, then
around the newly transformed Y-axis, and finally around the resulting Z-axis.

**Parameters**

- `ex` (`number |` [`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The angle to rotate around the X-axis in degrees, or a Vec3
  object containing the X, Y, and Z angles in degrees in its respective components (`ex.x`,
  `ex.y`, `ex.z`).
- `ey` (`number`, optional): The angle to rotate around the Y-axis in degrees. This parameter is
  only used if `ex` is provided as a number.
- `ez` (`number`, optional): The angle to rotate around the Z-axis in degrees. This parameter is
  only used if `ex` is provided as a number.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): The quaternion itself (this), now representing the orientation from the
specified XYZ Euler angles. Allows for method chaining.

**Example**

```ts
// Create a quaternion from 3 individual Euler angles (interpreted as X, Y, Z order)
const q1 = new Quat();
q1.setFromEulerAngles(45, 90, 180); // 45 deg around X, then 90 deg around Y', then 180 deg around Z''
console.log("From numbers:", q1.toString());
```

**Example**

```ts
// Create the same quaternion from a Vec3 containing the angles (X, Y, Z)
const anglesVec = new Vec3(45, 90, 180);
const q2 = new Quat();
q2.setFromEulerAngles(anglesVec);
console.log("From Vec3:", q2.toString()); // Should match q1
```

### setFromMat4

```ts
setFromMat4(m: Mat4): Quat
```

Converts the specified 4x4 matrix to a quaternion. Note that since a quaternion is purely a
representation for orientation, only the rotational part of the matrix is used.

**Parameters**

- `m` ([`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md)): The 4x4 matrix to convert.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): Self for chaining.

**Example**

```ts
// Create a 4x4 rotation matrix of 180 degrees around the y-axis
const rot = new Mat4().setFromAxisAngle(Vec3.UP, 180);

// Convert to a quaternion
const q = new Quat().setFromMat4(rot);
```

### slerp

```ts
slerp(lhs: Quat, rhs: Quat, alpha: number): Quat
```

Performs a spherical interpolation between two quaternions. The result of the interpolation
is written to the quaternion calling the function.

**Parameters**

- `lhs` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md)): The quaternion to interpolate from.
- `rhs` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md)): The quaternion to interpolate to.
- `alpha` (`number`): The unclamped interpolation factor. Values between 0 and 1 interpolate
  between lhs and rhs; values outside this range extrapolate beyond them.

**Returns** [`Quat`](https://api.playcanvas.com/engine/classes/Quat.md): Self for chaining.

**Example**

```ts
const q1 = new Quat(-0.11, -0.15, -0.46, 0.87);
const q2 = new Quat(-0.21, -0.21, -0.67, 0.68);

const result = new Quat();
result.slerp(q1, q2, 0);   // Return q1
result.slerp(q1, q2, 0.5); // Return the midpoint interpolant
result.slerp(q1, q2, 1);   // Return q2
```

### toArray

```ts
toArray(arr?: number[], offset?: number): number[]
```

**Parameters**

- `arr` (`number[]`, optional): The array to populate with the quaternion's number
  components. If not specified, a new array is created.
- `offset` (`number`, optional): The zero-based index at which to start copying elements to the
  array. Default is 0.

**Returns** `number[]`: The quaternion as an array.

```ts
toArray(arr: ArrayBufferView, offset?: number): ArrayBufferView
```

**Parameters**

- `arr` (`ArrayBufferView`): The array to populate with the quaternion's number
  components. If not specified, a new array is created.
- `offset` (`number`, optional): The zero-based index at which to start copying elements to the
  array. Default is 0.

**Returns** `ArrayBufferView`: The quaternion as an array.

### toString

```ts
toString(): string
```

Converts the quaternion to string form.

**Returns** `string`: The quaternion in string form.

**Example**

```ts
const q = new Quat(0, 0, 0, 1);
// Outputs [0, 0, 0, 1]
console.log(q.toString());
```

### transformVector

```ts
transformVector(vec: Vec3, res?: Vec3): Vec3
```

Transforms a 3-dimensional vector by the specified quaternion.

**Parameters**

- `vec` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The 3-dimensional vector to be transformed.
- `res` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md), optional): An optional 3-dimensional vector to receive the result of the transformation.

**Returns** [`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md): The transformed vector (res if specified, otherwise a new Vec3).

**Example**

```ts
// Create a 3-dimensional vector
const v = new Vec3(1, 2, 3);

// Create a quaternion rotation
const q = new Quat().setFromEulerAngles(10, 20, 30);

const tv = q.transformVector(v);
```