@needle-tools/three 0.169.12 → 0.169.14

package/types/src/math/MathUtils.d.ts

@@ -0,0 +1,137 @@
+import { Quaternion } from "./Quaternion.js";
+
+/**
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/math/MathUtils.js|src/math/MathUtils.js}
+ */
+
+export const DEG2RAD: number;
+
+export const RAD2DEG: number;
+
+export function generateUUID(): string;
+
+/**
+ * Clamps the x to be between a and b.
+ *
+ * @param value Value to be clamped.
+ * @param min Minimum value.
+ * @param max Maximum value.
+ */
+export function clamp(value: number, min: number, max: number): number;
+
+export function euclideanModulo(n: number, m: number): number;
+
+/**
+ * Linear mapping of x from range [a1, a2] to range [b1, b2].
+ *
+ * @param x Value to be mapped.
+ * @param a1 Minimum value for range A.
+ * @param a2 Maximum value for range A.
+ * @param b1 Minimum value for range B.
+ * @param b2 Maximum value for range B.
+ */
+export function mapLinear(x: number, a1: number, a2: number, b1: number, b2: number): number;
+
+export function inverseLerp(x: number, y: number, t: number): number;
+
+/**
+ * Returns a value linearly interpolated from two known points based
+ * on the given interval - t = 0 will return x and t = 1 will return y.
+ *
+ * @param x Start point.
+ * @param y End point.
+ * @param t interpolation factor in the closed interval [0, 1]
+ */
+export function lerp(x: number, y: number, t: number): number;
+
+/**
+ * Smoothly interpolate a number from x toward y in a spring-like
+ * manner using the dt to maintain frame rate independent movement.
+ *
+ * @param x Current point.
+ * @param y Target point.
+ * @param lambda A higher lambda value will make the movement more sudden, and a lower value will make the movement more gradual.
+ * @param dt Delta time in seconds.
+ */
+export function damp(x: number, y: number, lambda: number, dt: number): number;
+
+/**
+ * Returns a value that alternates between 0 and length.
+ *
+ * @param x The value to pingpong.
+ * @param length The positive value the export function will pingpong to. Default is 1.
+ */
+export function pingpong(x: number, length?: number): number;
+
+export function smoothstep(x: number, min: number, max: number): number;
+
+export function smootherstep(x: number, min: number, max: number): number;
+
+/**
+ * Random integer from low to high interval.
+ */
+export function randInt(low: number, high: number): number;
+
+/**
+ * Random float from low to high interval.
+ */
+export function randFloat(low: number, high: number): number;
+
+/**
+ * Random float from - range / 2 to range / 2 interval.
+ */
+export function randFloatSpread(range: number): number;
+
+/**
+ * Deterministic pseudo-random float in the interval [ 0, 1 ].
+ */
+export function seededRandom(seed?: number): number;
+
+export function degToRad(degrees: number): number;
+
+export function radToDeg(radians: number): number;
+
+export function isPowerOfTwo(value: number): boolean;
+
+export function ceilPowerOfTwo(value: number): number;
+
+export function floorPowerOfTwo(value: number): number;
+
+export function setQuaternionFromProperEuler(q: Quaternion, a: number, b: number, c: number, order: string): void;
+
+export function denormalize(
+    value: number,
+    array: Float32Array | Uint32Array | Uint16Array | Uint8Array | Int32Array | Int16Array | Int8Array,
+): number;
+
+export function normalize(
+    value: number,
+    array: Float32Array | Uint32Array | Uint16Array | Uint8Array | Int32Array | Int16Array | Int8Array,
+): number;
+
+export const MathUtils: {
+    DEG2RAD: typeof DEG2RAD;
+    RAD2DEG: typeof RAD2DEG;
+    generateUUID: typeof generateUUID;
+    clamp: typeof clamp;
+    euclideanModulo: typeof euclideanModulo;
+    mapLinear: typeof mapLinear;
+    inverseLerp: typeof inverseLerp;
+    lerp: typeof lerp;
+    damp: typeof damp;
+    pingpong: typeof pingpong;
+    smoothstep: typeof smoothstep;
+    smootherstep: typeof smootherstep;
+    randInt: typeof randInt;
+    randFloat: typeof randFloat;
+    randFloatSpread: typeof randFloatSpread;
+    seededRandom: typeof seededRandom;
+    degToRad: typeof degToRad;
+    radToDeg: typeof radToDeg;
+    isPowerOfTwo: typeof isPowerOfTwo;
+    ceilPowerOfTwo: typeof ceilPowerOfTwo;
+    floorPowerOfTwo: typeof floorPowerOfTwo;
+    setQuaternionFromProperEuler: typeof setQuaternionFromProperEuler;
+    normalize: typeof normalize;
+    denormalize: typeof denormalize;
+};

package/types/src/math/Matrix2.d.ts

@@ -0,0 +1,53 @@
+export type Matrix2Tuple = [
+    n11: number,
+    n12: number,
+    n21: number,
+    n22: number,
+];
+
+/**
+ * A class representing a 2x2 {@link https://en.wikipedia.org/wiki/Matrix_(mathematics) matrix}.
+ *
+ * @example
+ * const m = new Matrix2();
+ */
+export class Matrix2 {
+    readonly isMatrix2: true;
+
+    /**
+     * A {@link https://en.wikipedia.org/wiki/Row-_and_column-major_order column-major} list of matrix values.
+     */
+    elements: Matrix2Tuple;
+
+    /**
+     * Creates a 2x2 {@link https://en.wikipedia.org/wiki/Identity_matrix identity matrix}.
+     */
+    constructor();
+
+    /**
+     * Creates a 2x2 matrix with the given arguments in row-major order.
+     */
+    constructor(n11: number, n12: number, n21: number, n22: number);
+
+    /**
+     * Resets this matrix to the 2x2 identity matrix:
+     */
+    identity(): this;
+
+    /**
+     * Sets the elements of this matrix based on an array in
+     * {@link https://en.wikipedia.org/wiki/Row-_and_column-major_order#Column-major_order column-major} format.
+     *
+     * @param array the array to read the elements from
+     * @param offset (optional) index of first element in the array. Default is `0`.
+     */
+    fromArray(array: ArrayLike<number>, offset?: number): this;
+
+    /**
+     * Sets the 2x2 matrix values to the given
+     * {@link https://en.wikipedia.org/wiki/Row-_and_column-major_order row-major} sequence of values:
+     * [n11, n12,
+     *  n21, n22]
+     */
+    set(n11: number, n12: number, n21: number, n22: number): this;
+}

package/types/src/math/Matrix3.d.ts

@@ -0,0 +1,184 @@
+// https://threejs.org/docs/#api/en/math/Matrix3
+
+import { Matrix4 } from "./Matrix4.js";
+import { Vector2 } from "./Vector2.js";
+import { Vector3 } from "./Vector3.js";
+
+export type Matrix3Tuple = [
+    n11: number,
+    n12: number,
+    n13: number,
+    n21: number,
+    n22: number,
+    n23: number,
+    n31: number,
+    n32: number,
+    n33: number,
+];
+
+export class Matrix3 {
+    readonly isMatrix3: true;
+
+    /**
+     * Array with matrix values.
+     * @default [1, 0, 0, 0, 1, 0, 0, 0, 1]
+     */
+    elements: Matrix3Tuple;
+
+    /**
+     * Creates an identity matrix.
+     */
+    constructor();
+    /**
+     * Creates a 3x3 matrix with the given arguments in row-major order.
+     */
+    constructor(
+        n11: number,
+        n12: number,
+        n13: number,
+        n21: number,
+        n22: number,
+        n23: number,
+        n31: number,
+        n32: number,
+        n33: number,
+    );
+
+    set(
+        n11: number,
+        n12: number,
+        n13: number,
+        n21: number,
+        n22: number,
+        n23: number,
+        n31: number,
+        n32: number,
+        n33: number,
+    ): Matrix3;
+
+    identity(): this;
+
+    copy(m: Matrix3): this;
+
+    extractBasis(xAxis: Vector3, yAxis: Vector3, zAxis: Vector3): this;
+
+    setFromMatrix4(m: Matrix4): Matrix3;
+
+    /**
+     * Multiplies this matrix by m.
+     */
+    multiply(m: Matrix3): this;
+
+    premultiply(m: Matrix3): this;
+
+    /**
+     * Sets this matrix to a x b.
+     */
+    multiplyMatrices(a: Matrix3, b: Matrix3): this;
+
+    multiplyScalar(s: number): this;
+
+    determinant(): number;
+
+    /**
+     * Inverts this matrix in place.
+     */
+    invert(): this;
+
+    /**
+     * Transposes this matrix in place.
+     */
+    transpose(): this;
+
+    getNormalMatrix(matrix4: Matrix4): this;
+
+    /**
+     * Transposes this matrix into the supplied array r, and returns itself.
+     */
+    transposeIntoArray(r: number[]): this;
+
+    setUvTransform(tx: number, ty: number, sx: number, sy: number, rotation: number, cx: number, cy: number): this;
+
+    scale(sx: number, sy: number): this;
+
+    rotate(theta: number): this;
+
+    translate(tx: number, ty: number): this;
+
+    /**
+     * Sets this matrix as a 2D translation transform:
+     *
+     * ```
+     * 1, 0, x,
+     * 0, 1, y,
+     * 0, 0, 1
+     * ```
+     *
+     * @param v the amount to translate.
+     */
+    makeTranslation(v: Vector2): this;
+    /**
+     * Sets this matrix as a 2D translation transform:
+     *
+     * ```
+     * 1, 0, x,
+     * 0, 1, y,
+     * 0, 0, 1
+     * ```
+     *
+     * @param x the amount to translate in the X axis.
+     * @param y the amount to translate in the Y axis.
+     */
+    makeTranslation(x: number, y: number): this;
+
+    /**
+     * Sets this matrix as a 2D rotational transformation by theta radians. The resulting matrix will be:
+     *
+     * ```
+     * cos(θ) -sin(θ) 0
+     * sin(θ) cos(θ)  0
+     * 0      0       1
+     * ```
+     *
+     * @param theta Rotation angle in radians. Positive values rotate counterclockwise.
+     */
+    makeRotation(theta: number): this;
+
+    /**
+     * Sets this matrix as a 2D scale transform:
+     *
+     * ```
+     * x, 0, 0,
+     * 0, y, 0,
+     * 0, 0, 1
+     * ```
+     *
+     * @param x the amount to scale in the X axis.
+     * @param y the amount to scale in the Y axis.
+     */
+    makeScale(x: number, y: number): this;
+
+    equals(matrix: Matrix3): boolean;
+
+    /**
+     * Sets the values of this matrix from the provided array or array-like.
+     * @param array the source array or array-like.
+     * @param offset (optional) offset into the array-like. Default is 0.
+     */
+    fromArray(array: ArrayLike<number>, offset?: number): this;
+
+    /**
+     * Writes the elements of this matrix to an array in
+     * {@link https://en.wikipedia.org/wiki/Row-_and_column-major_order#Column-major_order column-major} format.
+     */
+    toArray(): Matrix3Tuple;
+    /**
+     * Writes the elements of this matrix to an array in
+     * {@link https://en.wikipedia.org/wiki/Row-_and_column-major_order#Column-major_order column-major} format.
+     * @param array array to store the resulting vector in. If not given a new array will be created.
+     * @param offset (optional) offset in the array at which to put the result.
+     */
+    toArray<TArray extends ArrayLike<number>>(array: TArray, offset?: number): TArray;
+
+    clone(): this;
+}

package/types/src/math/Matrix4.d.ts

@@ -0,0 +1,284 @@
+import { CoordinateSystem } from "../constants.js";
+import { Euler } from "./Euler.js";
+import { Matrix3 } from "./Matrix3.js";
+import { Quaternion } from "./Quaternion.js";
+import { Vector3 } from "./Vector3.js";
+
+export type Matrix4Tuple = [
+    n11: number,
+    n12: number,
+    n13: number,
+    n14: number,
+    n21: number,
+    n22: number,
+    n23: number,
+    n24: number,
+    n31: number,
+    n32: number,
+    n33: number,
+    n34: number,
+    n41: number,
+    n42: number,
+    n43: number,
+    n44: number,
+];
+
+/**
+ * A 4x4 Matrix.
+ *
+ * @example
+ * // Simple rig for rotating around 3 axes
+ * const m = new THREE.Matrix4();
+ * const m1 = new THREE.Matrix4();
+ * const m2 = new THREE.Matrix4();
+ * const m3 = new THREE.Matrix4();
+ * const alpha = 0;
+ * const beta = Math.PI;
+ * const gamma = Math.PI/2;
+ * m1.makeRotationX( alpha );
+ * m2.makeRotationY( beta );
+ * m3.makeRotationZ( gamma );
+ * m.multiplyMatrices( m1, m2 );
+ * m.multiply( m3 );
+ */
+export class Matrix4 {
+    readonly isMatrix4: true;
+
+    /**
+     * Array with matrix values.
+     * @default [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
+     */
+    elements: Matrix4Tuple;
+
+    /**
+     * Creates an identity matrix.
+     */
+    constructor();
+    /**
+     * Creates a 4x4 matrix with the given arguments in row-major order.
+     */
+    constructor(
+        n11: number,
+        n12: number,
+        n13: number,
+        n14: number,
+        n21: number,
+        n22: number,
+        n23: number,
+        n24: number,
+        n31: number,
+        n32: number,
+        n33: number,
+        n34: number,
+        n41: number,
+        n42: number,
+        n43: number,
+        n44: number,
+    );
+
+    /**
+     * Sets all fields of this matrix.
+     */
+    set(
+        n11: number,
+        n12: number,
+        n13: number,
+        n14: number,
+        n21: number,
+        n22: number,
+        n23: number,
+        n24: number,
+        n31: number,
+        n32: number,
+        n33: number,
+        n34: number,
+        n41: number,
+        n42: number,
+        n43: number,
+        n44: number,
+    ): this;
+
+    /**
+     * Resets this matrix to identity.
+     */
+    identity(): this;
+
+    clone(): Matrix4;
+
+    copy(m: Matrix4): this;
+
+    copyPosition(m: Matrix4): this;
+
+    /**
+     * Set the upper 3x3 elements of this matrix to the values of the Matrix3 m.
+     */
+    setFromMatrix3(m: Matrix3): this;
+
+    extractBasis(xAxis: Vector3, yAxis: Vector3, zAxis: Vector3): this;
+
+    makeBasis(xAxis: Vector3, yAxis: Vector3, zAxis: Vector3): this;
+
+    /**
+     * Copies the rotation component of the supplied matrix m into this matrix rotation component.
+     */
+    extractRotation(m: Matrix4): this;
+
+    makeRotationFromEuler(euler: Euler): this;
+
+    makeRotationFromQuaternion(q: Quaternion): this;
+
+    /**
+     * Constructs a rotation matrix, looking from eye towards center with defined up vector.
+     */
+    lookAt(eye: Vector3, target: Vector3, up: Vector3): this;
+
+    /**
+     * Multiplies this matrix by m.
+     */
+    multiply(m: Matrix4): this;
+
+    premultiply(m: Matrix4): this;
+
+    /**
+     * Sets this matrix to a x b.
+     */
+    multiplyMatrices(a: Matrix4, b: Matrix4): this;
+
+    /**
+     * Multiplies this matrix by s.
+     */
+    multiplyScalar(s: number): this;
+
+    /**
+     * Computes determinant of this matrix.
+     * Based on http://www.euclideanspace.com/maths/algebra/matrix/functions/inverse/fourD/index.htm
+     */
+    determinant(): number;
+
+    /**
+     * Transposes this matrix.
+     */
+    transpose(): this;
+
+    /**
+     * Sets the position component for this matrix from vector v.
+     */
+    setPosition(v: Vector3): this;
+    setPosition(x: number, y: number, z: number): this;
+
+    /**
+     * Inverts this matrix.
+     */
+    invert(): this;
+
+    /**
+     * Multiplies the columns of this matrix by vector v.
+     */
+    scale(v: Vector3): this;
+
+    getMaxScaleOnAxis(): number;
+
+    /**
+     * Sets this matrix as translation transform.
+     */
+    makeTranslation(v: Vector3): this;
+    makeTranslation(x: number, y: number, z: number): this;
+
+    /**
+     * Sets this matrix as rotation transform around x axis by theta radians.
+     *
+     * @param theta Rotation angle in radians.
+     */
+    makeRotationX(theta: number): this;
+
+    /**
+     * Sets this matrix as rotation transform around y axis by theta radians.
+     *
+     * @param theta Rotation angle in radians.
+     */
+    makeRotationY(theta: number): this;
+
+    /**
+     * Sets this matrix as rotation transform around z axis by theta radians.
+     *
+     * @param theta Rotation angle in radians.
+     */
+    makeRotationZ(theta: number): this;
+
+    /**
+     * Sets this matrix as rotation transform around axis by angle radians.
+     * Based on http://www.gamedev.net/reference/articles/article1199.asp.
+     *
+     * @param axis Rotation axis.
+     * @param angle Rotation angle in radians.
+     */
+    makeRotationAxis(axis: Vector3, angle: number): this;
+
+    /**
+     * Sets this matrix as scale transform.
+     */
+    makeScale(x: number, y: number, z: number): this;
+
+    /**
+     * Sets this matrix as shear transform.
+     */
+    makeShear(xy: number, xz: number, yx: number, yz: number, zx: number, zy: number): this;
+
+    /**
+     * Sets this matrix to the transformation composed of translation, rotation and scale.
+     */
+    compose(position: Vector3, quaternion: Quaternion, scale: Vector3): this;
+
+    /**
+     * Decomposes this matrix into it's position, quaternion and scale components.
+     */
+    decompose(position: Vector3, quaternion: Quaternion, scale: Vector3): this;
+
+    /**
+     * Creates a perspective projection matrix.
+     */
+    makePerspective(
+        left: number,
+        right: number,
+        top: number,
+        bottom: number,
+        near: number,
+        far: number,
+        coordinateSystem?: CoordinateSystem,
+    ): this;
+
+    /**
+     * Creates an orthographic projection matrix.
+     */
+    makeOrthographic(
+        left: number,
+        right: number,
+        top: number,
+        bottom: number,
+        near: number,
+        far: number,
+        coordinateSystem?: CoordinateSystem,
+    ): this;
+
+    equals(matrix: Matrix4): boolean;
+
+    /**
+     * Sets the values of this matrix from the provided array or array-like.
+     * @param array the source array or array-like.
+     * @param offset (optional) offset into the array-like. Default is 0.
+     */
+    fromArray(array: ArrayLike<number>, offset?: number): this;
+
+    /**
+     * Writes the elements of this matrix to an array in
+     * {@link https://en.wikipedia.org/wiki/Row-_and_column-major_order#Column-major_order column-major} format.
+     */
+    toArray(): Matrix4Tuple;
+    /**
+     * Writes the elements of this matrix to an array in
+     * {@link https://en.wikipedia.org/wiki/Row-_and_column-major_order#Column-major_order column-major} format.
+     * @param array array to store the resulting vector in.
+     * @param offset (optional) offset in the array at which to put the result.
+     */
+    toArray<TArray extends ArrayLike<number>>(array: TArray, offset?: number): TArray;
+}

package/types/src/math/Plane.d.ts

@@ -0,0 +1,47 @@
+import { Box3 } from "./Box3.js";
+import { Line3 } from "./Line3.js";
+import { Matrix3 } from "./Matrix3.js";
+import { Matrix4 } from "./Matrix4.js";
+import { Sphere } from "./Sphere.js";
+import { Vector3 } from "./Vector3.js";
+
+export class Plane {
+    constructor(normal?: Vector3, constant?: number);
+
+    /**
+     * @default new THREE.Vector3( 1, 0, 0 )
+     */
+    normal: Vector3;
+
+    /**
+     * @default 0
+     */
+    constant: number;
+
+    readonly isPlane: true;
+
+    set(normal: Vector3, constant: number): Plane;
+    setComponents(x: number, y: number, z: number, w: number): Plane;
+    setFromNormalAndCoplanarPoint(normal: Vector3, point: Vector3): Plane;
+    setFromCoplanarPoints(a: Vector3, b: Vector3, c: Vector3): Plane;
+    clone(): this;
+    copy(plane: Plane): this;
+    normalize(): Plane;
+    negate(): Plane;
+    distanceToPoint(point: Vector3): number;
+    distanceToSphere(sphere: Sphere): number;
+    projectPoint(point: Vector3, target: Vector3): Vector3;
+    intersectLine(line: Line3, target: Vector3): Vector3 | null;
+    intersectsLine(line: Line3): boolean;
+    intersectsBox(box: Box3): boolean;
+    intersectsSphere(sphere: Sphere): boolean;
+    coplanarPoint(target: Vector3): Vector3;
+    applyMatrix4(matrix: Matrix4, optionalNormalMatrix?: Matrix3): Plane;
+    translate(offset: Vector3): Plane;
+    equals(plane: Plane): boolean;
+
+    /**
+     * @deprecated Use {@link Plane#intersectsLine .intersectsLine()} instead.
+     */
+    isIntersectionLine(l: any): any;
+}