Class Quat

constructor

• new Quat(x?: number | number[], y?: number, z?: number, w?: number): Quat

• Create a new Quat instance.

  Parameters

  • Optionalx: number | number[] = 0

    The quaternion's x component. Defaults to 0. If x is an array of length 4, the array will be used to populate all components.
  • Optionaly: number = 0

    The quaternion's y component. Defaults to 0.
  • Optionalz: number = 0

    The quaternion's z component. Defaults to 0.
  • Optionalw: number = 1

    The quaternion's w component. Defaults to 1.

  Returns Quat

w

x

y

z

Static ReadonlyIDENTITY

Static ReadonlyZERO

clone

• clone(): Quat

• Returns an identical copy of the specified quaternion.

  Returns Quat

  A quaternion containing the result of the cloning.

  Example

  const q = new pc.Quat(-0.11, -0.15, -0.46, 0.87);
  const qclone = q.clone();
  
  console.log("The result of the cloning is: " + q.toString());
  Copy

copy

• copy(rhs: Quat): Quat

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

  Parameters

  • rhs: Quat

    The quaternion to be copied.

  Returns Quat

  Self for chaining.

  Example

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

equals

• equals(rhs: Quat): boolean

• Reports whether two quaternions are equal.

  Parameters

  • rhs: Quat

    The quaternion to be compared against.

  Returns boolean

  True if the quaternions are equal and false otherwise.

  Example

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

equalsApprox

• equalsApprox(rhs: Quat, epsilon?: number): boolean

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

  Parameters

  • rhs: Quat

    The quaternion to be compared against.
  • Optionalepsilon: number = 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

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

getAxisAngle

• 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

    The 3-dimensional vector to receive the axis of rotation.

  Returns number

  Angle, in degrees, of the rotation.

  Example

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

getEulerAngles

• getEulerAngles(eulers?: Vec3): Vec3

• Converts the supplied quaternion to Euler angles.

  Parameters

  • Optionaleulers: Vec3 = ...

    The 3-dimensional vector to receive the Euler angles.

  Returns Vec3

  The 3-dimensional vector holding the Euler angles that correspond to the supplied quaternion.

invert

• invert(src?: Quat): Quat

• Generates the inverse of the specified quaternion.

  Parameters

  • Optionalsrc: Quat = ...

    The quaternion to invert. If not set, the operation is done in place.

  Returns Quat

  Self for chaining.

  Example

  // Create a quaternion rotated 180 degrees around the y-axis
  const rot = new pc.Quat().setFromEulerAngles(0, 180, 0);
  
  // Invert in place
  rot.invert();
  Copy

length

• length(): number

• Returns the magnitude of the specified quaternion.

  Returns number

  The magnitude of the specified quaternion.

  Example

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

lengthSq

• lengthSq(): number

• Returns the magnitude squared of the specified quaternion.

  Returns number

  The magnitude of the specified quaternion.

  Example

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

mul

• mul(rhs: Quat): Quat

• Returns the result of multiplying the specified quaternions together.

  Parameters

  • rhs: Quat

    The quaternion used as the second multiplicand of the operation.

  Returns Quat

  Self for chaining.

  Example

  const a = new pc.Quat().setFromEulerAngles(0, 30, 0);
  const b = new pc.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());
  Copy

mul2

• mul2(lhs: Quat, rhs: Quat): Quat

• Returns the result of multiplying the specified quaternions together.

  Parameters

  • lhs: Quat

    The quaternion used as the first multiplicand of the operation.
  • rhs: Quat

    The quaternion used as the second multiplicand of the operation.

  Returns Quat

  Self for chaining.

  Example

  const a = new pc.Quat().setFromEulerAngles(0, 30, 0);
  const b = new pc.Quat().setFromEulerAngles(0, 60, 0);
  const r = new pc.Quat();
  
  // r is set to a 90 degree rotation around the Y axis
  // In other words, r = a * b
  r.mul2(a, b);
  
  console.log("The result of the multiplication is: " + r.toString());
  Copy

mulScalar

• mulScalar(scalar: number, src?: Quat): Quat

• Multiplies each element of a quaternion by a number.

  Parameters

  • scalar: number

    The number to multiply by.
  • Optionalsrc: Quat = ...

    The quaternion to scale. If not set, the operation is done in place.

  Returns Quat

  Self for chaining.

normalize

• normalize(src?: Quat): Quat

• Returns the specified quaternion converted in place to a unit quaternion.

  Parameters

  • Optionalsrc: Quat = ...

    The quaternion to normalize. If not set, the operation is done in place.

  Returns Quat

  The result of the normalization.

  Example

  const v = new pc.Quat(0, 0, 0, 5);
  
  v.normalize();
  
  // Outputs 0, 0, 0, 1
  console.log("The result of the vector normalization is: " + v.toString());
  Copy

set

• 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

  Self for chaining.

  Example

  const q = new pc.Quat();
  q.set(1, 0, 0, 0);
  
  // Outputs 1, 0, 0, 0
  console.log("The result of the vector set is: " + q.toString());
  Copy

setFromAxisAngle

• setFromAxisAngle(axis: Vec3, angle: number): Quat

• Sets a quaternion from an angular rotation around an axis.

  Parameters

  • axis: Vec3

    World space axis around which to rotate.
  • angle: number

    Angle to rotate around the given axis in degrees.

  Returns Quat

  Self for chaining.

  Example

  const q = new pc.Quat();
  q.setFromAxisAngle(pc.Vec3.UP, 90);
  Copy

setFromDirections

• setFromDirections(from: Vec3, to: Vec3): Quat

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

  Parameters

  • from: Vec3

    The direction to rotate from. It should be normalized.
  • to: Vec3

    The direction to rotate to. It should be normalized.

  Returns Quat

  Self for chaining.

  Proof of correctness

setFromEulerAngles

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

• Sets a quaternion from Euler angles specified in XYZ order.

  Parameters

  • ex: number | Vec3

    Angle to rotate around X axis in degrees. If ex is a Vec3, the three angles will be read from it instead.
  • Optionaley: number

    Angle to rotate around Y axis in degrees.
  • Optionalez: number

    Angle to rotate around Z axis in degrees.

  Returns Quat

  Self for chaining.

  Example

  // Create a quaternion from 3 euler angles
  const q = new pc.Quat();
  q.setFromEulerAngles(45, 90, 180);
  
  // Create the same quaternion from a vector containing the same 3 euler angles
  const v = new pc.Vec3(45, 90, 180);
  const r = new pc.Quat();
  r.setFromEulerAngles(v);
  Copy

setFromMat4

• 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 translational part of the matrix is lost.

  Parameters

  • m: Mat4

    The 4x4 matrix to convert.

  Returns Quat

  Self for chaining.

  Example

  // Create a 4x4 rotation matrix of 180 degrees around the y-axis
  const rot = new pc.Mat4().setFromAxisAngle(pc.Vec3.UP, 180);
  
  // Convert to a quaternion
  const q = new pc.Quat().setFromMat4(rot);
  Copy

slerp

• 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

    The quaternion to interpolate from.
  • rhs: Quat

    The quaternion to interpolate to.
  • alpha: number

    The value controlling the interpolation in relation to the two input quaternions. The value is in the range 0 to 1, 0 generating q1, 1 generating q2 and anything in between generating a spherical interpolation between the two.

  Returns Quat

  Self for chaining.

  Example

  const q1 = new pc.Quat(-0.11, -0.15, -0.46, 0.87);
  const q2 = new pc.Quat(-0.21, -0.21, -0.67, 0.68);
  
  const result;
  result = new pc.Quat().slerp(q1, q2, 0);   // Return q1
  result = new pc.Quat().slerp(q1, q2, 0.5); // Return the midpoint interpolant
  result = new pc.Quat().slerp(q1, q2, 1);   // Return q2
  Copy

toString

• toString(): string

• Converts the quaternion to string form.

  Returns string

  The quaternion in string form.

  Example

  const v = new pc.Quat(0, 0, 0, 1);
  // Outputs [0, 0, 0, 1]
  console.log(v.toString());
  Copy

transformVector

• transformVector(vec: Vec3, res?: Vec3): Vec3

• Transforms a 3-dimensional vector by the specified quaternion.

  Parameters

  • vec: Vec3

    The 3-dimensional vector to be transformed.
  • Optionalres: Vec3 = ...

    An optional 3-dimensional vector to receive the result of the transformation.

  Returns Vec3

  The input vector v transformed by the current instance.

  Example

  // Create a 3-dimensional vector
  const v = new pc.Vec3(1, 2, 3);
  
  // Create a 4x4 rotation matrix
  const q = new pc.Quat().setFromEulerAngles(10, 20, 30);
  
  const tv = q.transformVector(v);
  Copy