@casual-simulation/aux-common/math/Rotation.d.ts

Common library for AUX projects

import { Quaternion } from './Quaternion';
import type { Vector2 } from './Vector2';
import { Vector3 } from './Vector3';
/**
 * Defines a class that can represent geometric rotations.
 *
 * @dochash types/math/rotations
 * @docorder 0
 * @doctitle Rotations
 * @docsidebar Rotations
 * @docdescription Rotations help represent orientation.
 * @docname Rotation
 */
export declare class Rotation {
    private _q;
    /**
     * The quaternion that this rotation uses.
     */
    get quaternion(): Quaternion;
    /**
     * Creates a new rotation using the given parameters.
     * @param rotation The information that should be used to construct the rotation.
     *
     * @example 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
     *
     * @example 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)
     *
     * @example 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'
     * });
     *
     * @example Tilt this bot forwards in the home dimension.
     * tags.homeRotation = new Rotation({
     *     axis: new Vector3(1, 0, 0),
     *     angle: Math.PI / 6 // 30 degrees
     * });
     */
    constructor(rotation?: FromToRotation | AxisAndAngle | QuaternionRotation | Quaternion | SequenceRotation | EulerAnglesRotation | LookRotation);
    /**
     * Constructs a new Quaternion from the given axis and angle.
     * @param axisAndAngle The object that contains the axis and angle values.
     */
    static quaternionFromAxisAndAngle(axisAndAngle: AxisAndAngle): 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.
     * @param fromToRotation The object that contains the from and to values.
     */
    static quaternionFromTo(fromToRotation: FromToRotation): Quaternion;
    /**
     * Constructs a new Quaternion from the given look rotation.
     * @param look The object that contains the look rotation values.
     */
    static quaternionLook(look: LookRotation): Quaternion;
    /**
     * Determines the angle between the two given quaternions and returns the result in radians.
     * @param first The first quaternion. Must be a quaterion that represents a rotation
     * @param second The second quaternion.
     */
    static angleBetween(first: Rotation, second: Rotation): number;
    /**
     * 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.
     * @param first The first rotation.
     * @param second The second rotation.
     * @param amount 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 interpolate(first: Rotation, second: Rotation, amount: number): Rotation;
    /**
     * Rotates the given {@link Vector3} by this quaternion and returns a new vector containing the result.
     * @param vector The 3D vector that should be rotated.
     *
     * @example 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);
     */
    rotateVector3(vector: Vector3): Vector3;
    /**
     * Rotates the given {@link 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.
     * @param vector The 2D vector that should be rotated.
     *
     * @example 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);
     */
    rotateVector2(vector: Vector2): Vector3;
    /**
     * Combines this rotation with the other rotation and returns a new rotation that represents the combination of the two.
     * @param other The other rotation.
     *
     * @example 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);
     */
    combineWith(other: Rotation): Rotation;
    /**
     * Calculates the inverse rotation of this rotation and returns a new rotation with the result.
     *
     * @example 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);
     */
    invert(): Rotation;
    /**
     * Gets the axis and angle that this rotation rotates around.
     */
    axisAndAngle(): AxisAndAngle;
    /**
     * Determines if this rotation equals the other rotation.
     * @param other The rotation to check.
     */
    equals(other: Rotation): boolean;
    /**
     * Converts this rotation to a human-readable string representation.
     *
     * @example 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);
     */
    toString(): string;
}
/**
 * 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.
 *
 * @dochash types/math/rotations
 * @docorder 3
 * @doctitle Rotations
 * @docsidebar Rotations
 * @docdescription Rotations help represent orientation.
 * @docname FromToRotation
 */
export interface FromToRotation {
    /**
     * The direction that the rotation should rotate from.
     */
    from: Vector3;
    /**
     * The direction that the rotation should rotate to.
     */
    to: Vector3;
}
/**
 * Defines an interface that represents an Axis and Angle pair.
 *
 * @dochash types/math/rotations
 * @docorder 2
 * @doctitle Rotations
 * @docsidebar Rotations
 * @docdescription Rotations help represent orientation.
 * @docname AxisAndAngle
 */
export interface AxisAndAngle {
    /**
     * The axis about which the angle should rotate around.
     */
    axis: Vector3;
    /**
     * The number of radians that should be rotated around the axis.
     */
    angle: number;
}
/**
 * Defines an interface that represents an Euler Angles rotation.
 *
 * @dochash types/math/rotations
 * @docorder 4
 * @doctitle Rotations
 * @docsidebar Rotations
 * @docdescription Rotations help represent orientation.
 * @docname EulerAnglesRotation
 */
export interface EulerAnglesRotation {
    euler: {
        /**
         * The amount to rotate around the X axis.
         */
        x: number;
        /**
         * The amount to rotate around the Y axis.
         */
        y: number;
        /**
         * The amount to rotate around the Z axis.
         */
        z: number;
        /**
         * The order that the rotations should be applied in.
         * Defaults to XYZ.
         */
        order?: string;
        /**
         * Whether the euler angles are extrinsic.
         * Defaults to false.
         */
        extrinsic?: boolean;
    };
}
/**
 * Defines an interface that represents a sequence of rotations.
 *
 * @dochash types/math/rotations
 * @docorder 5
 * @doctitle Rotations
 * @docsidebar Rotations
 * @docdescription Rotations help represent orientation.
 * @docname SequenceRotation
 */
export interface SequenceRotation {
    /**
     * The sequence of successive rotations.
     */
    sequence: Rotation[];
}
/**
 * Defines an interface that represents a rotation constructed from a Quaternion.
 *
 * @dochash types/math/rotations
 * @docorder 6
 * @doctitle Rotations
 * @docsidebar Rotations
 * @docdescription Rotations help represent orientation.
 * @docname QuaternionRotation
 */
export interface QuaternionRotation {
    quaternion: {
        x: number;
        y: number;
        z: number;
        w: number;
    };
}
/**
 * Defines an interface that represents a rotation transforms (0, 1, 0) and (0, 0, 1) to look along the given direction and upwards axes.
 *
 * @dochash types/math/rotations
 * @docorder 7
 * @doctitle Rotations
 * @docsidebar Rotations
 * @docdescription Rotations help represent orientation.
 * @docname LookRotation
 */
export interface LookRotation {
    /**
     * The direction that (0, 1, 0) should be pointing along after the rotation is applied.
     */
    direction: 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.
     */
    upwards: Vector3;
    /**
     * 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.
     */
    errorHandling: 'error' | 'nudge';
}
/**
 * Defines a constant that contains a rotation that, when combined with a rotation, converts a rotation in AUX coordinates to THREE.js coordinates.
 */
export declare const AUX_ROTATION_TO_THREEJS: Rotation;
/**
 * Copies the sign from signGiver onto signTaker and returns the result.
 * @param signGiver The number whose sign should be given to the other number.
 * @param signTaker The number whose sign should be set.
 */
export declare function copySign(signGiver: number, signTaker: number): number;
//# sourceMappingURL=Rotation.d.ts.map