# Quat

Interface representing a quaternion. A quaternion is represented by (x, y, z, w) coordinates, and
represents a 3D rotation. Quaternions can be converted to and from 4x4 rotation matrices with the
interfaces in Mat4. Quaternion objects are created with the `ecs.math.quat`

QuatFactory, or through
operations on other Quat objects.

## Code Example

`const {quat} = ecs.math `

const a = quat.zero()

const b = quat.yDegrees(45)

const c = a.slerp(b, 0.1)

## Source

The QuatSource interface represents any object that has x, y, z, and w properties and hence can be
used as a data source to create a Quat. In addition, QuatSource can be used as an argument to Quat
algorithms, meaning that any object with `{x: number, y: number, z: number, w: number}`

properties
can be used.

QuatSource has the following enumerable properties:

`readonly x: number`

Access the x component of the vector.

`readonly y: number`

Access the y component of the vector.

`readonly z: number`

Access the z component of the vector.

`readonly w: number`

Access the w component of the vector.

## Factory

Quat objects are created with the `ecs.math.quat`

QuatFactory, with the following methods:

### quat.axisAngle()

`quat.axisAngle: (aa: Vec3Source, target?: Quat) => Quat`

Create a Quat from an axis-angle representation. The direction of the `aa`

vector gives the axis of
rotation, and the magnitude of the vector gives the angle, in radians. For example,
`quat.axisAngle(vec3.up().scale(Math.PI / 2))`

represents a 90-degree rotation about the y-axis, and
is equivalent to `quat.yDegrees(90)`

. If `target`

is supplied, the result will be stored in `target`

and `target`

will be returned. Otherwise, a new Quat will be created and returned.

### quat.from()

`quat.from: ({x, y, z, w}: {readonly x: number, readonly y: number, readonly z: number, readonly w: number) => Quat`

Create a Quat from an object with x, y, z, w properties.

### quat.lookAt()

`quat.lookAt: (eye: Vec3Source, target: Vec3Source, up: Vec3Source) => Quat`

Create a Quat representing the rotation required for an object positioned at ‘eye’ to look at an object positioned at ‘target’, with the given ‘up vector.

### quat.pitchYawRollDegrees()

`quat.pitchYawRollDegrees: (v: Vec3Source) => Quat`

Construct a quaternion from a pitch / yaw / roll representation, also known as YXZ Euler angles. Rotation is specified in degrees.

### quat.pitchYawRollRadians()

`quat.pitchYawRollRadians: (v: Vec3Source) => Quat`

Construct a quaternion from a pitch / yaw / roll representation, also known as YXZ Euler angles. Rotation is specified in radians.

### quat.xDegrees()

`quat.xDegrees: (degrees: number) => Quat`

Create a Quat which represents a rotation about the x-axis. Rotation is specified in degrees.

### quat.xRadians()

`quat.xRadians: (radians: number) => Quat`

Create a Quat which represents a rotation about the x-axis. Rotation is specified in radians.

### quat.xyzw()

`quat.xyzw: (x: number, y: number, z: number, w: number) => Quat`

Create a Quat from x, y, z, w values.

### quat.yDegrees()

`quat.yDegrees: (degrees: number) => Quat`

Create a Quat which represents a rotation about the y-axis. Rotation is specified in degrees.

### quat.yRadians()

`quat.yRadians: (radians: number) => Quat`

Create a Quat which represents a rotation about the z-axis. Rotation is specified in radians.

### quat.zDegrees()

`quat.zDegrees: (degrees: number) => Quat`

Create a Quat which represents a rotation about the z-axis. Rotation is specified in degrees.

### quat.zRadians()

`quat.zRadians: (radians: number) => Quat`

Create a Quat which represents a rotation about the y-axis. Rotation is specified in radians.

### quat.zero()

`quat.zero: () => Quat`

Create a Quat which represents a zero rotation.

## Properties

Quat has the following enumerable properties:

`readonly x: number`

Access the x component of the quaternion.

`readonly y: number`

Access the y component of the quaternion.

`readonly z: number`

Access the z component of the quaternion.

`readonly w: number`

Access the w component of the quaternion.

## Immutable API

The following methods perform computations based on the current value of a Quat, but do not modify its contents. Methods that return Quat types return new objects. Immutable APIs are typically safer, more readable, and less error-prone than mutable APIs, but may be inefficient in situations where thousands of objects are allocated each frame. In cases where object garbage collection is a performance concern, prefer the Mutable API (below).

### .axisAngle()

`axisAngle: (target?: Vec3) => Vec3`

Convert the quaternion to an axis-angle representation. The direction of the vector gives the axis of rotation, and the magnitude of the vector gives the angle, in radians. If ‘target’ is supplied, the result will be stored in ‘target’ and ‘target’ will be returned. Otherwise, a new Vec3 will be created and returned.

### .clone()

`clone: () => Quat`

Create a new quaternion with the same components as this quaternion.

### .conjugate()

`conjugate: () => Quat`

Return the rotational conjugate of this quaternion. The conjugate of a quaternion represents the same rotation in the opposite direction about the rotational axis.

### .data()

`data: () => number[]`

Access the quaternion as an array of [x, y, z, w].

### .degreesTo()

`degreesTo: (target: QuatSource) => number`

Angle between two quaternions, in degrees.

### .delta()

`delta: (target: QuatSource) => Quat`

Compute the quaternion required to rotate this quaternion to the target quaternion.

### .dot()

`dot: (q: QuatSource) => number`

Compute the dot product of this quaternion with another quaternion.

### .equals()

`equals: (q: QuatSource, tolerance: number) => boolean`

Check whether two quaternions are equal, with a specified floating point tolerance.

### .inv()

`inv: () => Quat`

Compute the quaternion which multiplies this quaternion to get a zero rotation quaternion.

### .negate()

`negate: () => Quat`

Negate all components of this quaternion. The result is a quaternion representing the same rotation as this quaternion.

### .normalize()

`normalize: () => Quat`

Get the normalized version of this quaternion with a length of 1.

### .pitchYawRollRadians()

`pitchYawRollRadians: (target?: Vec3) => Vec3`

Convert the quaternion to pitch, yaw, and roll angles in radians.

### .pitchYawRollDegrees()

`pitchYawRollDegrees: (target?: Vec3) => Vec3`

Convert the quaternion to pitch, yaw, and roll angles in degrees.

### .plus()

`plus: (q: QuatSource) => Quat`

Add two quaternions together.

### .radiansTo()

`radiansTo: (target: QuatSource) => number`

Angle between two quaternions, in radians.

### .rotateToward()

`rotateToward: (target: QuatSource, radians: number) => Quat`

Rotate this quaternion towards the target quaternion by a given number of radians, clamped to the target.

### .slerp()

`slerp: (target: QuatSource, t: number) => Quat`

Spherical interpolation between two quaternions given a provided interpolation value. If the interpolation is set to 0, then it will return this quaternion. If the interpolation is set to 1, then it will return the target quaternion.

### .times()

`times: (q: QuatSource) => Quat`

Multiply two quaternions together.

### .timesVec()

`timesVec: (v: Vec3Source, target?: Vec3) => Vec3`

Multiply the quaternion by a vector. This is equivalent to converting the quaternion to a rotation matrix and multiplying the matrix by the vector.

## Mutable API

The following methods perform computations based on the current value of a Quat, and modify its contents in place. They are parallel to methods in the mutable API above. Methods that return Quat types return a reference to the current object for convenient method chaining. Mutable APIs can be more performant than Immutable APIs, but are typically less safe, less readable, and more error-prone. In cases where a section of code will likely not be called many times on a given frame, consider using the Immutable API (above).

This next example is equivalent to the Immutable API example above, but allocates two Quat objects instead of three:

`const {quat} = ecs.math`

const a = quat.zero()

const b = quat.yDegrees(45)

a.setSlerp(b, 0.1)

### .setConjugate()

`setConjugate: () => Quat`

Set this quaternion to its rotational conjugate. The conjugate of a quaternion represents the same rotation in the opposite direction about the rotational axis. Store the result in this Quat and return this Quat for chaining.

### .setDelta()

`setDelta: (target: QuatSource) => Quat`

Compute the quaternion required to rotate this quaternion to the target quaternion. Store the result in this Quat and return this Quat for chaining.

### .setInv()

`setInv: () => Quat`

Set this to the quaternion which multiplies this quaternion to get a zero rotation quaternion. Store the result in this Quat and return this Quat for chaining.

### .setNegate()

`setNegate: () => Quat`

Negate all components of this quaternion. The result is a quaternion representing the same rotation as this quaternion. Store the result in this Quat and return this Quat for chaining.

### .setNormalize()

`setNormalize: () => Quat`

Get the normalized version of this quaternion with a length of 1. Store the result in this Quat and return this Quat for chaining.

### .setPlus()

`setPlus: (q: QuatSource) => Quat`

Add this quaternion to another quaternion. Store the result in this Quat and return this Quat for chaining.

### .setPremultiply()

`setPremultiply: (q: QuatSource) => Quat`

Set this quaternion the result of q times this quaternion. Store the result in this Quat and return this Quat for chaining.

### .setRotateToward()

`setRotateToward: (target: QuatSource, radians: number) => Quat`

Rotate this quaternion towards the target quaternion by a given number of radians, clamped to the target. Store the result in this Quat and return this Quat for chaining.

### .setSlerp()

`setSlerp: (target: QuatSource, t: number) => Quat`

Spherical interpolation between two quaternions given a provided interpolation value. If the interpolation is set to 0, then it will return this quaternion. If the interpolation is set to 1, then it will return the target quaternion. Store the result in this Quat and return this Quat for chaining.

### .setTimes()

`setTimes: (q: QuatSource) => Quat`

Multiply two quaternions together. Store the result in this Quat and return this Quat for chaining.

## Set API

The following methods set the value of the current Quat object without regard to its current content, replacing whatever was there before.

### .makeAxisAngle()

`makeAxisAngle: (aa: Vec3Source) => Quat`

Set a Quat from an axis-angle representation. The direction of the vector gives the axis of rotation, and the magnitude of the vector gives the angle, in radians. Store the result in this Quat and return this Quat for chaining.

### .makePitchYawRollRadians()

`makePitchYawRollRadians: (v: Vec3Source) => Quat`

Set the quaternion to a rotation specified by pitch, yaw, and roll angles in radians. Store the result in this Quat and return this Quat for chaining.

### .makeLookAt()

`makeLookAt: (eye: Vec3Source, target: Vec3Source, up: Vec3Source) => Quat`

Set the quaternion to a rotation that would cause the eye to look at the target with the given up vector. Store the result in this Quat and return this Quat for chaining.

### .makePitchYawRollDegrees()

`makePitchYawRollDegrees: (v: Vec3Source) => Quat`

Set the quaternion to a rotation specified by pitch, yaw, and roll angles in degrees. Store the result in this Quat and return this Quat for chaining.

### .makeXDegrees()

`makeXDegrees: (degrees: number) => Quat`

Set the quaternion to a rotation about the x-axis (pitch) in degrees. Store the result in this Quat and return this Quat for chaining.

### .makeXRadians()

`makeXRadians: (radians: number) => Quat`

Set the quaternion to a rotation about the x-axis (pitch) in radians. Store the result in this Quat and return this Quat for chaining.

### .makeYDegrees()

`makeYDegrees: (degrees: number) => Quat`

Set the quaternion to a rotation about the y-axis (yaw) in degrees. Store the result in this Quat and return this Quat for chaining.

### .makeYRadians()

`makeYRadians: (radians: number) => Quat`

Set the quaternion to a rotation about the y-axis (yaw) in radians. Store the result in this Quat and return this Quat for chaining.

### .makeZDegrees()

`makeZDegrees: (degrees: number) => Quat`

Set the quaternion to a rotation about the z-axis (roll) in degrees. Store the result in this Quat and return this Quat for chaining.

### .makeZRadians()

`makeZRadians: (radians: number) => Quat`

Set the quaternion to a rotation about the z-axis (roll) in radians. Store the result in this Quat and return this Quat for chaining.

### .makeZero()

`makeZero: () => Quat`

Set the quaternion to a zero rotation. Store the result in this Quat and return this Quat for chaining.

### .setFrom()

`setFrom: (q: QuatSource) => Quat`

Set this quaternion to the value in another quaternion. Store the result in this Quat and return this Quat for chaining.

### .setXyzw()

`setXyzw: (x: number, y: number, z: number, w: number) => Quat`

Set the quaternion to the specified x, y, z and w values. Store the result in this Quat and return this Quat for chaining.