@math.gl/core 3.6.0-alpha.1 → 3.6.0-alpha.4

package/src/classes/base/math-array.ts

@@ -0,0 +1,265 @@
+// math.gl, MIT License
+import {NumericArray} from '@math.gl/types';
+import {ConfigurationOptions, config, formatValue, equals, isArray} from '../../lib/common';
+
+/** Base class for vectors and matrices */
+export default abstract class MathArray extends Array<number> {
+  /** Number of elements (values) in this array */
+  abstract get ELEMENTS(): number;
+
+  abstract copy(vector: Readonly<NumericArray>): this;
+
+  abstract fromObject(object: object): this;
+
+  // Common methods
+
+  /**
+   * Clone the current object
+   * @returns a new copy of this object
+   */
+  clone(): this {
+    // @ts-expect-error TS2351: Cannot use 'new' with an expression whose type lacks a call or construct signature.
+    return new this.constructor().copy(this); // eslint-disable-line
+  }
+
+  fromArray(array: Readonly<NumericArray>, offset: number = 0): this {
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      this[i] = array[i + offset];
+    }
+    return this.check();
+  }
+
+  toArray<TypedArray>(targetArray: TypedArray, offset?: number): TypedArray;
+  toArray(targetArray?: number[], offset?: number): NumericArray;
+
+  toArray(targetArray: NumericArray = [], offset: number = 0): NumericArray {
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      targetArray[offset + i] = this[i];
+    }
+    return targetArray;
+  }
+
+  from(arrayOrObject: Readonly<NumericArray> | object): this {
+    return Array.isArray(arrayOrObject) ? this.copy(arrayOrObject) : this.fromObject(arrayOrObject);
+  }
+
+  to<T extends NumericArray | object>(arrayOrObject: T): T {
+    // @ts-ignore
+    if (arrayOrObject === this) {
+      return this;
+    }
+    // @ts-expect-error TS2339: Property 'toObject' does not exist on type 'MathArray'.
+    return isArray(arrayOrObject) ? this.toArray(arrayOrObject) : this.toObject(arrayOrObject);
+  }
+
+  toTarget(target: any): any {
+    return target ? this.to(target) : this;
+  }
+
+  /** @deprecated */
+  toFloat32Array(): Float32Array {
+    return new Float32Array(this);
+  }
+
+  toString(): string {
+    return this.formatString(config);
+  }
+
+  /** Formats string according to options */
+  formatString(opts: ConfigurationOptions): string {
+    let string = '';
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      string += (i > 0 ? ', ' : '') + formatValue(this[i], opts);
+    }
+    return `${opts.printTypes ? this.constructor.name : ''}[${string}]`;
+  }
+
+  equals(array: Readonly<NumericArray>): boolean {
+    if (!array || this.length !== array.length) {
+      return false;
+    }
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      if (!equals(this[i], array[i])) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  exactEquals(array: Readonly<NumericArray>): boolean {
+    if (!array || this.length !== array.length) {
+      return false;
+    }
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      if (this[i] !== array[i]) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  // Modifiers
+
+  /** Negates all values in this object */
+  negate(): this {
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      this[i] = -this[i];
+    }
+    return this.check();
+  }
+
+  /** Linearly interpolates between two values */
+  lerp(a: Readonly<NumericArray>, t: number): this;
+  lerp(a: Readonly<NumericArray>, b: Readonly<NumericArray>, t: number): this;
+
+  lerp(a: Readonly<NumericArray>, b: Readonly<NumericArray> | number, t?: number): this {
+    if (t === undefined) {
+      return this.lerp(this, a, b as number);
+    }
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      const ai = a[i];
+      this[i] = ai + t * (b[i] - ai);
+    }
+    return this.check();
+  }
+
+  /** Minimal */
+  min(vector: Readonly<NumericArray>): this {
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      this[i] = Math.min(vector[i], this[i]);
+    }
+    return this.check();
+  }
+
+  /** Maximal */
+  max(vector: Readonly<NumericArray>): this {
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      this[i] = Math.max(vector[i], this[i]);
+    }
+    return this.check();
+  }
+
+  clamp(minVector: Readonly<NumericArray>, maxVector: Readonly<NumericArray>): this {
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      this[i] = Math.min(Math.max(this[i], minVector[i]), maxVector[i]);
+    }
+    return this.check();
+  }
+
+  add(...vectors: Readonly<NumericArray>[]): this {
+    for (const vector of vectors) {
+      for (let i = 0; i < this.ELEMENTS; ++i) {
+        this[i] += vector[i];
+      }
+    }
+    return this.check();
+  }
+
+  subtract(...vectors: Readonly<NumericArray>[]): this {
+    for (const vector of vectors) {
+      for (let i = 0; i < this.ELEMENTS; ++i) {
+        this[i] -= vector[i];
+      }
+    }
+    return this.check();
+  }
+
+  scale(scale: number | Readonly<NumericArray>): this {
+    if (typeof scale === 'number') {
+      for (let i = 0; i < this.ELEMENTS; ++i) {
+        this[i] *= scale;
+      }
+    } else {
+      for (let i = 0; i < this.ELEMENTS && i < scale.length; ++i) {
+        this[i] *= scale[i];
+      }
+    }
+    return this.check();
+  }
+
+  /**
+   * Multiplies all elements by `scale`
+   * Note: `Matrix4.multiplyByScalar` only scales its 3x3 "minor"
+   */
+  multiplyByScalar(scalar: number): this {
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      this[i] *= scalar;
+    }
+    return this.check();
+  }
+
+  // Debug checks
+
+  /** Throws an error if array length is incorrect or contains illegal values */
+  check(): this {
+    if (config.debug && !this.validate()) {
+      throw new Error(`math.gl: ${this.constructor.name} some fields set to invalid numbers'`);
+    }
+    return this;
+  }
+
+  /** Returns false if the array length is incorrect or contains illegal values */
+  validate(): boolean {
+    let valid = this.length === this.ELEMENTS;
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      valid = valid && Number.isFinite(this[i]);
+    }
+    return valid;
+  }
+
+  // three.js compatibility
+
+  /** @deprecated */
+  sub(a: Readonly<NumericArray>): this {
+    return this.subtract(a);
+  }
+
+  /** @deprecated */
+  setScalar(a: number): this {
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      this[i] = a;
+    }
+    return this.check();
+  }
+
+  /** @deprecated */
+  addScalar(a: number): this {
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      this[i] += a;
+    }
+    return this.check();
+  }
+
+  /** @deprecated */
+  subScalar(a: number): this {
+    return this.addScalar(-a);
+  }
+
+  /** @deprecated */
+  multiplyScalar(scalar: number): this {
+    // Multiplies all elements
+    // `Matrix4.scale` only scales its 3x3 "minor"
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      this[i] *= scalar;
+    }
+    return this.check();
+  }
+
+  /** @deprecated */
+  divideScalar(a: number): this {
+    return this.multiplyByScalar(1 / a);
+  }
+
+  /** @deprecated */
+  clampScalar(min: number, max: number): this {
+    for (let i = 0; i < this.ELEMENTS; ++i) {
+      this[i] = Math.min(Math.max(this[i], min), max);
+    }
+    return this.check();
+  }
+
+  /** @deprecated */
+  get elements(): NumericArray {
+    return this;
+  }
+}

package/src/classes/base/{matrix.js → matrix.ts}

@@ -1,32 +1,26 @@
+// Copyright (c) 2017 Uber Technologies, Inc.
+// MIT License
+import {NumericArray} from '@math.gl/types';
 import MathArray from './math-array';
 import {checkNumber} from '../../lib/validators';
 import {config} from '../../lib/common';
-import assert from '../../lib/assert';
 
-export default class Matrix extends MathArray {
-  // Defined by derived class
-  get ELEMENTS() {
-    assert(false);
-    return 0;
-  }
-
-  get RANK() {
-    assert(false);
-    return 0;
-  }
+/** Base class for matrices */
+export default abstract class Matrix extends MathArray {
+  abstract get RANK(): number;
 
   // fromObject(object) {
   //   const array = object.elements;
   //   return this.fromRowMajor(array);
   // }
-
   // toObject(object) {
   //   const array = object.elements;
   //   this.toRowMajor(array);
   //   return object;
   // }
 
-  toString() {
+  // TODO better override formatString?
+  toString(): string {
     let string = '[';
     if (config.printRowMajor) {
       string += 'row-major:';
@@ -45,22 +39,24 @@ export default class Matrix extends MathArray {
     return string;
   }
 
-  getElementIndex(row, col) {
+  getElementIndex(row: number, col: number): number {
     return col * this.RANK + row;
   }
 
   // By default assumes row major indices
-  getElement(row, col) {
+  getElement(row: number, col: number): number {
     return this[col * this.RANK + row];
   }
 
   // By default assumes row major indices
-  setElement(row, col, value) {
+  setElement(row: number, col: number, value: number): this {
     this[col * this.RANK + row] = checkNumber(value);
     return this;
   }
+  getColumn<NumArrayT>(columnIndex: number, result: NumArrayT): NumArrayT;
+  getColumn(columnIndex: number): number[];
 
-  getColumn(columnIndex, result = new Array(this.RANK).fill(-0)) {
+  getColumn(columnIndex: number, result: number[] = new Array(this.RANK).fill(-0)): number[] {
     const firstIndex = columnIndex * this.RANK;
     for (let i = 0; i < this.RANK; ++i) {
       result[i] = this[firstIndex + i];
@@ -68,7 +64,7 @@ export default class Matrix extends MathArray {
     return result;
   }
 
-  setColumn(columnIndex, columnVector) {
+  setColumn(columnIndex: number, columnVector: Readonly<NumericArray>): this {
     const firstIndex = columnIndex * this.RANK;
     for (let i = 0; i < this.RANK; ++i) {
       this[firstIndex + i] = columnVector[i];

package/src/classes/base/{vector.js → vector.ts}

@@ -1,46 +1,51 @@
+// Copyright (c) 2017 Uber Technologies, Inc.
+// MIT License
+import {NumericArray} from '@math.gl/types';
 import MathArray from './math-array';
 import {checkNumber} from '../../lib/validators';
 import assert from '../../lib/assert';
 
-export default class Vector extends MathArray {
-  get ELEMENTS() {
-    assert(false);
-    return 0;
-  }
-
-  // VIRTUAL METHODS
-  copy(vector) {
-    assert(false);
-    return this;
-  }
-
+/** Base class for vectors with at least 2 elements */
+export default abstract class Vector extends MathArray {
   // ACCESSORS
 
-  get x() {
+  get x(): number {
     return this[0];
   }
-  set x(value) {
+
+  set x(value: number) {
     this[0] = checkNumber(value);
   }
 
-  get y() {
+  get y(): number {
     return this[1];
   }
-  set y(value) {
+
+  set y(value: number) {
     this[1] = checkNumber(value);
   }
 
-  // NOTE: `length` is a reserved word for Arrays, so we can't use `v.length()`
-  // Offer `len` and `magnitude`
-  len() {
+  /**
+   * Returns the length of the vector from the origin to the point described by this vector
+   *
+   * @note `length` is a reserved word for Arrays, so `v.length()` will return number of elements
+   * Instead we provide `len` and `magnitude`
+   */
+  len(): number {
     return Math.sqrt(this.lengthSquared());
   }
 
-  magnitude() {
+  /**
+   * Returns the length of the vector from the origin to the point described by this vector
+   */
+  magnitude(): number {
     return this.len();
   }
 
-  lengthSquared() {
+  /**
+   * Returns the squared length of the vector from the origin to the point described by this vector
+   */
+  lengthSquared(): number {
     let length = 0;
     for (let i = 0; i < this.ELEMENTS; ++i) {
       length += this[i] * this[i];
@@ -48,15 +53,18 @@ export default class Vector extends MathArray {
     return length;
   }
 
-  magnitudeSquared() {
+  /**
+   * Returns the squared length of the vector from the origin to the point described by this vector
+   */
+  magnitudeSquared(): number {
     return this.lengthSquared();
   }
 
-  distance(mathArray) {
+  distance(mathArray: Readonly<NumericArray>): number {
     return Math.sqrt(this.distanceSquared(mathArray));
   }
 
-  distanceSquared(mathArray) {
+  distanceSquared(mathArray: Readonly<NumericArray>): number {
     let length = 0;
     for (let i = 0; i < this.ELEMENTS; ++i) {
       const dist = this[i] - mathArray[i];
@@ -65,7 +73,7 @@ export default class Vector extends MathArray {
     return checkNumber(length);
   }
 
-  dot(mathArray) {
+  dot(mathArray: Readonly<NumericArray>): number {
     let product = 0;
     for (let i = 0; i < this.ELEMENTS; ++i) {
       product += this[i] * mathArray[i];
@@ -75,7 +83,7 @@ export default class Vector extends MathArray {
 
   // MODIFIERS
 
-  normalize() {
+  normalize(): this {
     const length = this.magnitude();
     if (length !== 0) {
       for (let i = 0; i < this.ELEMENTS; ++i) {
@@ -85,21 +93,7 @@ export default class Vector extends MathArray {
     return this.check();
   }
 
-  // negate() {
-  //   for (let i = 0; i < this.ELEMENTS; ++i) {
-  //     this[i] = -this[i];
-  //   }
-  //   return this.check();
-  // }
-
-  // inverse() {
-  //   for (let i = 0; i < this.ELEMENTS; ++i) {
-  //     this[i] = 1 / this[i];
-  //   }
-  //   return this.check();
-  // }
-
-  multiply(...vectors) {
+  multiply(...vectors: Readonly<NumericArray>[]): this {
     for (const vector of vectors) {
       for (let i = 0; i < this.ELEMENTS; ++i) {
         this[i] *= vector[i];
@@ -108,7 +102,7 @@ export default class Vector extends MathArray {
     return this.check();
   }
 
-  divide(...vectors) {
+  divide(...vectors: Readonly<NumericArray>[]): this {
     for (const vector of vectors) {
       for (let i = 0; i < this.ELEMENTS; ++i) {
         this[i] /= vector[i];
@@ -118,43 +112,42 @@ export default class Vector extends MathArray {
   }
 
   // THREE.js compatibility
-  lengthSq() {
+
+  lengthSq(): number {
     return this.lengthSquared();
   }
-
-  distanceTo(vector) {
+  distanceTo(vector: Readonly<NumericArray>): number {
     return this.distance(vector);
   }
-
-  distanceToSquared(vector) {
+  distanceToSquared(vector: Readonly<NumericArray>): number {
     return this.distanceSquared(vector);
   }
 
-  getComponent(i) {
+  getComponent(i: number): number {
     assert(i >= 0 && i < this.ELEMENTS, 'index is out of range');
     return checkNumber(this[i]);
   }
 
-  setComponent(i, value) {
+  setComponent(i: number, value: number): this {
     assert(i >= 0 && i < this.ELEMENTS, 'index is out of range');
     this[i] = value;
     return this.check();
   }
 
-  addVectors(a, b) {
+  addVectors(a: Readonly<NumericArray>, b: Readonly<NumericArray>): this {
     return this.copy(a).add(b);
   }
 
-  subVectors(a, b) {
+  subVectors(a: Readonly<NumericArray>, b: Readonly<NumericArray>): this {
     return this.copy(a).subtract(b);
   }
 
-  multiplyVectors(a, b) {
+  multiplyVectors(a: Readonly<NumericArray>, b: Readonly<NumericArray>): this {
     return this.copy(a).multiply(b);
   }
 
-  addScaledVector(a, b) {
-    // @ts-ignore error TS2351: Cannot use 'new' with an expression whose type lacks a call or construct signature.
+  addScaledVector(a: Readonly<NumericArray>, b: number): this {
+    // @ts-expect-error error TS2351: Cannot use 'new' with an expression whose type lacks a call or construct signature.
     return this.add(new this.constructor(a).multiplyScalar(b));
   }
 }