Skip to main content
Version: Current

Rotations

  • Rotation

    Defines a class that can represent geometric rotations.

    Members

    • quaternion Quaternion

    • constructor(rotation?: (Quaternion | FromToRotation | AxisAndAngle | QuaternionRotation | SequenceRotation | EulerAnglesRotation | LookRotation)): Rotation

      Creates a new rotation using the given parameters.

      The first parameter is optional and is a (Quaternion | FromToRotation | AxisAndAngle | QuaternionRotation | SequenceRotation | EulerAnglesRotation | LookRotation) and is the information that should be used to construct the rotation.

      Examples
      Create a rotation from an axis and angle.
      const rotation = new Rotation({
      axis: new Vector3(0, 0, 1),
      angle: Math.PI / 2
      }); // 90 degree rotation around Z axis
      Create a rotation from two vectors.
      const rotation = new Rotation({
      from: new Vector3(1, 0, 0),
      to: new Vector3(0, 1, 0)
      }); // Rotation that rotates (1, 0, 0) to (0, 1, 0)
      Create a rotation that looks along the X axis.
      const rotation = new Rotation({
      direction: new Vector3(1, 0, 0),
      upwards: new Vector3(0, 0, 1),
      errorHandling: 'nudge'
      });
      Tilt this bot forwards in the home dimension.
      tags.homeRotation = new Rotation({
      axis: new Vector3(1, 0, 0),
      angle: Math.PI / 6 // 30 degrees
      });
    • axisAndAngle(): AxisAndAngle

      Gets the axis and angle that this rotation rotates around.

    • combineWith(other: Rotation): Rotation

      Combines this rotation with the other rotation and returns a new rotation that represents the combination of the two.

      The first parameter is a Rotation and is the other rotation.

      Examples
      Combine two rotations together.
      const first = new Rotation({
      axis: new Vector3(1, 0, 0),
      angle: Math.PI / 4
      }); // 45 degree rotation around X axis
      const second = new Rotation({
      axis: new Vector3(1, 0, 0),
      angle: Math.PI / 4
      }); // 45 degree rotation around X axis

      const third = first.combineWith(second); // 90 degree rotation around X

      os.toast(third);
    • equals(other: Rotation): boolean

      Determines if this rotation equals the other rotation.

      The first parameter is a Rotation and is the rotation to check.

    • invert(): Rotation

      Calculates the inverse rotation of this rotation and returns a new rotation with the result.

      Examples
      Calculate the inverse of a rotation.
      const first = new Rotation({
      axis: new Vector3(1, 0, 0),
      angle: Math.PI / 4
      }); // 45 degree rotation around X axis
      const inverse = first.inverse();

      const result = first.combineWith(inverse);

      os.toast(result);
    • rotateVector2(vector: Vector2): Vector3

      Rotates the given Vector2 by this quaternion and returns a new vector containing the result. Note that rotations around any other axis than (0, 0, 1) or (0, 0, -1) can produce results that contain a Z component.

      The first parameter is a Vector2 and is the 2D vector that should be rotated.

      Examples
      Apply a rotation to a Vector2 object.
      const rotation = new Rotation({
      axis: new Vector3(1, 0, 0),
      angle: Math.PI / 4
      }); // 45 degree rotation around X axis

      const point = new Vector2(1, 2);
      const rotated = rotation.rotateVector2(point);
      os.toast(rotated);
    • rotateVector3(vector: Vector3): Vector3

      Rotates the given Vector3 by this quaternion and returns a new vector containing the result.

      The first parameter is a Vector3 and is the 3D vector that should be rotated.

      Examples
      Apply a rotation to a Vector3 object.
      const rotation = new Rotation({
      axis: new Vector3(1, 0, 0),
      angle: Math.PI / 4
      }); // 45 degree rotation around X axis

      const point = new Vector3(1, 2, 0);
      const rotated = rotation.rotateVector3(point);
      os.toast(rotated);
    • toString(): string

      Converts this rotation to a human-readable string representation.

      Examples
      Get a string of a rotation.
      const myRotation = new Rotation({
      axis: new Vector3(1, 0, 0),
      angle: Math.PI / 4
      }); // 45 degree rotation around X axis
      const rotationString = myRotation.toString();

      os.toast('My Rotation: ' + rotationString);
    • static angleBetween(first: Rotation, second: Rotation): number

      Determines the angle between the two given quaternions and returns the result in radians.

      The first parameter is a Rotation and is the first quaternion. Must be a quaterion that represents a rotation

      The second parameter is a Rotation and is the second quaternion.

    • static interpolate(first: Rotation, second: Rotation, amount: number): Rotation

      Constructs a new rotation that is the spherical linear interpolation between the given first and second rotations. The degree that the result is interpolated is determined by the given amount parameter.

      The first parameter is a Rotation and is the first rotation.

      The second parameter is a Rotation and is the second rotation.

      The third parameter is a number and is the amount that the resulting rotation should be interpolated between the first and second rotations. Values near 0 indicate rotations close to the first and values near 1 indicate rotations close to the second.

    • static quaternionFromAxisAndAngle(axisAndAngle: AxisAndAngle): Quaternion

      Constructs a new Quaternion from the given axis and angle.

      The first parameter is a AxisAndAngle and is the object that contains the axis and angle values.

    • static quaternionFromTo(fromToRotation: FromToRotation): Quaternion

      Constructs a new Quaternion from the given from/to rotation. This is equivalent to calculating the cross product and angle between the two vectors and constructing an axis/angle quaternion.

      The first parameter is a FromToRotation and is the object that contains the from and to values.

    • static quaternionLook(look: LookRotation): Quaternion

      Constructs a new Quaternion from the given look rotation.

      The first parameter is a LookRotation and is the object that contains the look rotation values.

  • AxisAndAngle

    Defines an interface that represents an Axis and Angle pair.

    Members

    • angle number

      The number of radians that should be rotated around the axis.

    • axis Vector3

      The axis about which the angle should rotate around.

  • FromToRotation

    Defines an interface that represents a from/to rotation. That is, a rotation that is able to rotate a vector from the given vector direction to the given vector direction.

    Members

    • from Vector3

      The direction that the rotation should rotate from.

    • to Vector3

      The direction that the rotation should rotate to.

  • EulerAnglesRotation

    Defines an interface that represents an Euler Angles rotation.

    Members

    • euler object

  • SequenceRotation

    Defines an interface that represents a sequence of rotations.

    Members

    • sequence Rotation[]

      The sequence of successive rotations.

  • QuaternionRotation

    Defines an interface that represents a rotation constructed from a Quaternion.

    Members

    • quaternion object

  • LookRotation

    Defines an interface that represents a rotation transforms (0, 1, 0) and (0, 0, 1) to look along the given direction and upwards axes.

    Members

    • direction Vector3

      The direction that (0, 1, 0) should be pointing along after the rotation is applied.

    • errorHandling ("error" | "nudge")

      How errors with the direction and upwards vectors should be handled. If the direction and upwards vectors are parallel or perpendicular, then it is not possible to create a rotation that looks along the direction and uses the upwards vector. The upwards vector is essentially useless in this scenario and as a result there are an infinite number of possible valid rotations that look along direction vector.

      This parameter provides two ways to handle this situation:

      • "error" indicates that an error should be thrown when this situation arises.
      • "nudge" indicates that the direction vector should be nudged by a miniscule amount in an arbitrary direction. This causes the upwards and direction vectors to no longer be parallel, but it can also cause rotation bugs when the direction and upwards are the same.
    • upwards Vector3

      The direction that the upward axis should be pointing along after the rotation is applied. If the direction and upwards vectors are not perpendicular, then the direction will be prioritized and the angle between upwards and the resulting upwards vector will be minimized.

      If direction and upwards are perpendicular, then applying the rotation to (0, 0, 1) will give the upwards vector.