A quaternion.

Constructors

  • 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

Properties

w: number

The w component of the quaternion.

x: number

The x component of the quaternion.

y: number

The y component of the quaternion.

z: number

The z component of the quaternion.

IDENTITY: Quat = ...

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

ZERO: Quat = ...

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

Methods

  • Returns an identical copy of the specified quaternion.

    Returns Quat

    A quaternion containing the result of the cloning.

    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());
  • Copies the contents of a source quaternion to a destination quaternion.

    Parameters

    • rhs: Quat

      The quaternion to be copied.

    Returns Quat

    Self for chaining.

    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"));
  • 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.

    const a = new pc.Quat();
    const b = new pc.Quat();
    console.log("The two quaternions are " + (a.equals(b) ? "equal" : "different"));
  • 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.

    const a = new pc.Quat();
    const b = new pc.Quat();
    console.log("The two quaternions are approximately " + (a.equalsApprox(b, 1e-9) ? "equal" : "different"));
  • 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.

    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());
  • 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.

  • 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.

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

    // Invert in place
    rot.invert();
  • Returns the magnitude of the specified quaternion.

    Returns number

    The magnitude of the specified quaternion.

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

    Returns number

    The magnitude of the specified quaternion.

    const q = new pc.Quat(3, 4, 0);
    const lenSq = q.lengthSq();
    // Outputs 25
    console.log("The length squared of the quaternion is: " + lenSq);
  • 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.

    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());
  • 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.

    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());
  • 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.

  • 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.

    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());
  • 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.

    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());
  • 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.

    const q = new pc.Quat();
    q.setFromAxisAngle(pc.Vec3.UP, 90);
  • 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

  • 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.

    // 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);
  • 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.

    // 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);
  • 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.

    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
  • Converts the quaternion to string form.

    Returns string

    The quaternion in string form.

    const v = new pc.Quat(0, 0, 0, 1);
    // Outputs [0, 0, 0, 1]
    console.log(v.toString());
  • 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.

    // 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);