Engine API Reference - v1.77.0
    Preparing search index...

    Class Quat

    A quaternion.

    Index

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