@types/three 0.165.0 → 0.167.0

three/src/math/Euler.d.ts

@@ -4,6 +4,8 @@ import { Vector3 } from "./Vector3.js";
 
 export type EulerOrder = "XYZ" | "YXZ" | "ZXY" | "ZYX" | "YZX" | "XZY";
 
+export type EulerTuple = [x: number, y: number, z: number, order?: EulerOrder];
+
 export class Euler {
     constructor(x?: number, y?: number, z?: number, order?: EulerOrder);
 
@@ -38,8 +40,8 @@ export class Euler {
     setFromVector3(v: Vector3, order?: EulerOrder): Euler;
     reorder(newOrder: EulerOrder): Euler;
     equals(euler: Euler): boolean;
-    fromArray(xyzo: [number, number, number, EulerOrder?, ...any[]]): Euler;
-    toArray(array?: Array<number | string | undefined>, offset?: number): Array<number | string | undefined>;
+    fromArray(array: EulerTuple): Euler;
+    toArray(array?: Partial<EulerTuple>, offset?: number): EulerTuple;
     _onChange(callback: () => void): this;
 
     static DEFAULT_ORDER: "XYZ";

three/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;
+}

three/src/math/Matrix3.d.ts

@@ -4,55 +4,26 @@ import { Matrix4 } from "./Matrix4.js";
 import { Vector2 } from "./Vector2.js";
 import { Vector3 } from "./Vector3.js";
 
-export type Matrix3Tuple = [number, number, number, number, number, number, number, number, number];
+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;
 
-/**
- * ( interface Matrix<T> )
- */
-export interface Matrix {
     /**
      * Array with matrix values.
+     * @default [1, 0, 0, 0, 1, 0, 0, 0, 1]
      */
-    elements: number[];
-
-    /**
-     * identity():T;
-     */
-    identity(): Matrix;
-
-    /**
-     * copy(m:T):T;
-     */
-    copy(m: this): this;
-
-    /**
-     * multiplyScalar(s:number):T;
-     */
-    multiplyScalar(s: number): Matrix;
-
-    determinant(): number;
-
-    /**
-     * transpose():T;
-     */
-    transpose(): Matrix;
-
-    /**
-     * invert():T;
-     */
-    invert(): Matrix;
-
-    /**
-     * clone():T;
-     */
-    clone(): Matrix;
-}
-
-/**
- * ( class Matrix3 implements Matrix<Matrix3> )
- */
-export class Matrix3 implements Matrix {
-    readonly isMatrix3: true;
+    elements: Matrix3Tuple;
 
     /**
      * Creates an identity matrix.
@@ -73,12 +44,6 @@ export class Matrix3 implements Matrix {
         n33: number,
     );
 
-    /**
-     * Array with matrix values.
-     * @default [1, 0, 0, 0, 1, 0, 0, 0, 1]
-     */
-    elements: number[];
-
     set(
         n11: number,
         n12: number,
@@ -90,34 +55,68 @@ export class Matrix3 implements Matrix {
         n32: number,
         n33: number,
     ): Matrix3;
-    identity(): Matrix3;
-    clone(): this;
+
+    identity(): this;
+
     copy(m: Matrix3): this;
-    extractBasis(xAxis: Vector3, yAxis: Vector3, zAxis: Vector3): Matrix3;
+
+    extractBasis(xAxis: Vector3, yAxis: Vector3, zAxis: Vector3): this;
+
     setFromMatrix4(m: Matrix4): Matrix3;
-    multiplyScalar(s: number): 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(): Matrix3;
+    invert(): this;
 
     /**
      * Transposes this matrix in place.
      */
-    transpose(): Matrix3;
-    getNormalMatrix(matrix4: Matrix4): Matrix3;
+    transpose(): this;
+
+    getNormalMatrix(matrix4: Matrix4): this;
 
     /**
      * Transposes this matrix into the supplied array r, and returns itself.
      */
-    transposeIntoArray(r: number[]): Matrix3;
+    transposeIntoArray(r: number[]): this;
 
-    setUvTransform(tx: number, ty: number, sx: number, sy: number, rotation: number, cx: number, cy: number): Matrix3;
+    setUvTransform(tx: number, ty: number, sx: number, sy: number, rotation: number, cx: number, cy: number): this;
 
-    scale(sx: number, sy: number): Matrix3;
+    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:
      *
@@ -130,7 +129,6 @@ export class Matrix3 implements Matrix {
      * @param x the amount to translate in the X axis.
      * @param y the amount to translate in the Y axis.
      */
-    makeTranslation(v: Vector2): this;
     makeTranslation(x: number, y: number): this;
 
     /**
@@ -145,7 +143,6 @@ export class Matrix3 implements Matrix {
      * @param theta Rotation angle in radians. Positive values rotate counterclockwise.
      */
     makeRotation(theta: number): this;
-    makeRotation(theta: number): Matrix3;
 
     /**
      * Sets this matrix as a 2D scale transform:
@@ -160,11 +157,6 @@ export class Matrix3 implements Matrix {
      * @param y the amount to scale in the Y axis.
      */
     makeScale(x: number, y: number): this;
-    makeScale(x: number, y: number): Matrix3;
-
-    rotate(theta: number): Matrix3;
-
-    translate(tx: number, ty: number): Matrix3;
 
     equals(matrix: Matrix3): boolean;
 
@@ -173,55 +165,15 @@ export class Matrix3 implements Matrix {
      * @param array the source array or array-like.
      * @param offset (optional) offset into the array-like. Default is 0.
      */
-    fromArray(array: number[] | ArrayLike<number>, offset?: number): Matrix3;
-
-    /**
-     * Returns an array with the values of this matrix, or copies them into the provided array.
-     * @param array (optional) array to store the matrix to. If this is not provided, a new array will be created.
-     * @param offset (optional) optional offset into the array.
-     * @return The created or provided array.
-     */
-    toArray(array?: number[], offset?: number): number[];
-    toArray(array?: Matrix3Tuple, offset?: 0): Matrix3Tuple;
+    fromArray(array: ArrayLike<number>, offset?: number): this;
 
     /**
-     * Copies he values of this matrix into the provided array-like.
-     * @param array array-like to store the matrix to.
-     * @param offset (optional) optional offset into the array-like.
-     * @return The provided array-like.
+     * 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 (optional) 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(array?: ArrayLike<number>, offset?: number): ArrayLike<number>;
+    toArray<TArray extends ArrayLike<number> = number[]>(array?: TArray, offset?: number): TArray;
 
-    /**
-     * Multiplies this matrix by m.
-     */
-    multiply(m: Matrix3): Matrix3;
-
-    premultiply(m: Matrix3): Matrix3;
-
-    /**
-     * Sets this matrix to a x b.
-     */
-    multiplyMatrices(a: Matrix3, b: Matrix3): Matrix3;
-
-    /**
-     * @deprecated Use {@link Vector3.applyMatrix3 vector.applyMatrix3( matrix )} instead.
-     */
-    multiplyVector3(vector: Vector3): any;
-
-    /**
-     * @deprecated This method has been removed completely.
-     */
-    multiplyVector3Array(a: any): any;
-
-    /**
-     * @deprecated Use {@link Matrix3#invert .invert()} instead.
-     */
-    getInverse(matrix: Matrix4, throwOnDegenerate?: boolean): Matrix3;
-    getInverse(matrix: Matrix): Matrix;
-
-    /**
-     * @deprecated Use {@link Matrix3#toArray .toArray()} instead.
-     */
-    flattenToArrayOffset(array: number[], offset: number): number[];
+    clone(): this;
 }

three/src/math/Matrix4.d.ts

@@ -1,26 +1,26 @@
 import { CoordinateSystem } from "../constants.js";
 import { Euler } from "./Euler.js";
-import { Matrix, Matrix3 } from "./Matrix3.js";
+import { Matrix3 } from "./Matrix3.js";
 import { Quaternion } from "./Quaternion.js";
 import { Vector3 } from "./Vector3.js";
 
 export type Matrix4Tuple = [
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
+    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,
 ];
 
 /**
@@ -41,9 +41,15 @@ export type Matrix4Tuple = [
  * m.multiplyMatrices( m1, m2 );
  * m.multiply( m3 );
  */
-export class Matrix4 implements Matrix {
+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.
      */
@@ -70,12 +76,6 @@ export class Matrix4 implements Matrix {
         n44: number,
     );
 
-    /**
-     * Array with matrix values.
-     * @default [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
-     */
-    elements: number[];
-
     /**
      * Sets all fields of this matrix.
      */
@@ -102,18 +102,31 @@ export class Matrix4 implements Matrix {
      * 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.
      */
@@ -131,14 +144,6 @@ export class Matrix4 implements Matrix {
      */
     multiplyMatrices(a: Matrix4, b: Matrix4): this;
 
-    /**
-     * Sets this matrix to a x b and stores the result into the flat array r.
-     * r can be either a regular Array or a TypedArray.
-     *
-     * @deprecated This method has been removed completely.
-     */
-    multiplyToArray(a: Matrix4, b: Matrix4, r: number[]): Matrix4;
-
     /**
      * Multiplies this matrix by s.
      */
@@ -172,6 +177,7 @@ export class Matrix4 implements Matrix {
     scale(v: Vector3): this;
 
     getMaxScaleOnAxis(): number;
+
     /**
      * Sets this matrix as translation transform.
      */
@@ -204,7 +210,7 @@ export class Matrix4 implements Matrix {
      * Based on http://www.gamedev.net/reference/articles/article1199.asp.
      *
      * @param axis Rotation axis.
-     * @param theta Rotation angle in radians.
+     * @param angle Rotation angle in radians.
      */
     makeRotationAxis(axis: Vector3, angle: number): this;
 
@@ -221,12 +227,12 @@ export class Matrix4 implements Matrix {
     /**
      * Sets this matrix to the transformation composed of translation, rotation and scale.
      */
-    compose(translation: Vector3, rotation: Quaternion, scale: Vector3): this;
+    compose(position: Vector3, quaternion: Quaternion, scale: Vector3): this;
 
     /**
      * Decomposes this matrix into it's position, quaternion and scale components.
      */
-    decompose(translation: Vector3, rotation: Quaternion, scale: Vector3): this;
+    decompose(position: Vector3, quaternion: Quaternion, scale: Vector3): this;
 
     /**
      * Creates a perspective projection matrix.
@@ -253,6 +259,7 @@ export class Matrix4 implements Matrix {
         far: number,
         coordinateSystem?: CoordinateSystem,
     ): this;
+
     equals(matrix: Matrix4): boolean;
 
     /**
@@ -260,72 +267,13 @@ export class Matrix4 implements Matrix {
      * @param array the source array or array-like.
      * @param offset (optional) offset into the array-like. Default is 0.
      */
-    fromArray(array: number[] | ArrayLike<number>, offset?: number): this;
-
-    /**
-     * Returns an array with the values of this matrix, or copies them into the provided array.
-     * @param array (optional) array to store the matrix to. If this is not provided, a new array will be created.
-     * @param offset (optional) optional offset into the array.
-     * @return The created or provided array.
-     */
-    toArray(array?: number[], offset?: number): number[];
-    toArray(array?: Matrix4Tuple, offset?: 0): Matrix4Tuple;
-
-    /**
-     * Copies he values of this matrix into the provided array-like.
-     * @param array array-like to store the matrix to.
-     * @param offset (optional) optional offset into the array-like.
-     * @return The provided array-like.
-     */
-    toArray(array?: ArrayLike<number>, offset?: number): ArrayLike<number>;
-
-    /**
-     * Set the upper 3x3 elements of this matrix to the values of the Matrix3 m.
-     */
-    setFromMatrix3(m: Matrix3): this;
-
-    /**
-     * @deprecated Use {@link Matrix4#copyPosition .copyPosition()} instead.
-     */
-    extractPosition(m: Matrix4): Matrix4;
-
-    /**
-     * @deprecated Use {@link Matrix4#makeRotationFromQuaternion .makeRotationFromQuaternion()} instead.
-     */
-    setRotationFromQuaternion(q: Quaternion): Matrix4;
-
-    /**
-     * @deprecated Use {@link Vector3#applyMatrix4 vector.applyMatrix4( matrix )} instead.
-     */
-    multiplyVector3(v: any): any;
-
-    /**
-     * @deprecated Use {@link Vector4#applyMatrix4 vector.applyMatrix4( matrix )} instead.
-     */
-    multiplyVector4(v: any): any;
-
-    /**
-     * @deprecated This method has been removed completely.
-     */
-    multiplyVector3Array(array: number[]): number[];
-
-    /**
-     * @deprecated Use {@link Vector3#transformDirection Vector3.transformDirection( matrix )} instead.
-     */
-    rotateAxis(v: any): void;
-
-    /**
-     * @deprecated Use {@link Vector3#applyMatrix4 vector.applyMatrix4( matrix )} instead.
-     */
-    crossVector(v: any): void;
-
-    /**
-     * @deprecated Use {@link Matrix4#toArray .toArray()} instead.
-     */
-    flattenToArrayOffset(array: number[], offset: number): number[];
+    fromArray(array: ArrayLike<number>, offset?: number): this;
 
     /**
-     * @deprecated Use {@link Matrix4#invert .invert()} instead.
+     * 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 (optional) array to store the resulting vector in.
+     * @param offset (optional) offset in the array at which to put the result.
      */
-    getInverse(matrix: Matrix): Matrix;
+    toArray<TArray extends ArrayLike<number> = number[]>(array?: TArray, offset?: number): TArray;
 }

three/src/math/Quaternion.d.ts

@@ -11,6 +11,8 @@ export interface QuaternionLike {
     readonly w: number;
 }
 
+export type QuaternionTuple = [x: number, y: number, z: number, w: number];
+
 /**
  * Implementation of a quaternion. This is used for rotating things without incurring in the dreaded gimbal lock issue, amongst other advantages.
  *
@@ -127,7 +129,7 @@ export class Quaternion {
      * @param array the source array or array-like.
      * @param offset (optional) offset into the array. Default is 0.
      */
-    fromArray(array: number[] | ArrayLike<number>, offset?: number): this;
+    fromArray(array: QuaternionTuple, offset?: number): this;
 
     /**
      * Returns an array [x, y, z, w], or copies x, y, z and w into the provided array.
@@ -135,7 +137,7 @@ export class Quaternion {
      * @param offset (optional) optional offset into the array.
      * @return The created or provided array.
      */
-    toArray(array?: number[], offset?: number): number[];
+    toArray(array?: number[], offset?: number): QuaternionTuple;
 
     /**
      * Copies x, y, z and w into the provided array-like.
@@ -143,7 +145,7 @@ export class Quaternion {
      * @param offset (optional) optional offset into the array.
      * @return The provided array-like.
      */
-    toArray(array: ArrayLike<number>, offset?: number): ArrayLike<number>;
+    toArray(array: ArrayLike<number>, offset?: number): QuaternionTuple;
 
     /**
      * This method defines the serialization result of Quaternion.

three/src/math/Vector2.d.ts

@@ -1,7 +1,7 @@
 import { BufferAttribute } from "../core/BufferAttribute.js";
 import { Matrix3 } from "./Matrix3.js";
 
-export type Vector2Tuple = [number, number];
+export type Vector2Tuple = [x: number, y: number];
 
 export interface Vector2Like {
     readonly x: number;

three/src/math/Vector4.d.ts

@@ -137,6 +137,12 @@ export class Vector4 {
      */
     setAxisAngleFromRotationMatrix(m: Matrix4): this;
 
+    /**
+     * Sets this vector to the position elements of the
+     * [transformation matrix]{@link https://en.wikipedia.org/wiki/Transformation_matrix} m.
+     */
+    setFromMatrixPosition(m: Matrix4): this;
+
     min(v: Vector4Like): this;
     max(v: Vector4Like): this;
     clamp(min: Vector4Like, max: Vector4Like): this;