@math.gl/core 3.5.6 → 3.6.0-alpha.2

package/src/classes/{vector4.js → vector4.ts}

@@ -1,44 +1,36 @@
 // Copyright (c) 2017 Uber Technologies, Inc.
-//
-// Permission is hereby granted, free of charge, to any person obtaining a copy
-// of this software and associated documentation files (the "Software"), to deal
-// in the Software without restriction, including without limitation the rights
-// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-// copies of the Software, and to permit persons to whom the Software is
-// furnished to do so, subject to the following conditions:
-//
-// The above copyright notice and this permission notice shall be included in
-// all copies or substantial portions of the Software.
-//
-// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-// THE SOFTWARE.
+// MIT License
 
 import Vector from './base/vector';
 import {config, isArray} from '../lib/common';
 import {checkNumber} from '../lib/validators';
-
-// @ts-ignore: error TS2307: Cannot find module 'gl-matrix/...'.
 import * as vec4 from 'gl-matrix/vec3';
-// eslint-disable-next-line camelcase
+/* eslint-disable camelcase */
 import {vec4_transformMat2, vec4_transformMat3} from '../lib/gl-matrix-extras';
+import {NumericArray} from '@math.gl/types';
+
+import type Matrix4 from './matrix4';
 
-const constants = {};
+let ZERO: Vector4;
 
+/**
+ * Four-element vector class.
+ * Subclass of Array<number>
+ */
 export default class Vector4 extends Vector {
-  static get ZERO() {
-    return (constants.ZERO = constants.ZERO || Object.freeze(new Vector4(0, 0, 0, 0)));
+  static get ZERO(): Vector4 {
+    if (!ZERO) {
+      ZERO = new Vector4(0, 0, 0, 0);
+      Object.freeze(ZERO);
+    }
+    return ZERO;
   }
 
-  constructor(x = 0, y = 0, z = 0, w = 0) {
+  constructor(x: number | Readonly<NumericArray> = 0, y: number = 0, z: number = 0, w: number = 0) {
     // PERF NOTE: initialize elements as double precision numbers
     super(-0, -0, -0, -0);
     if (isArray(x) && arguments.length === 1) {
-      this.copy(x);
+      this.copy(x as Readonly<NumericArray>);
     } else {
       // this.set(x, y, z, w);
       if (config.debug) {
@@ -47,14 +39,14 @@ export default class Vector4 extends Vector {
         checkNumber(z);
         checkNumber(w);
       }
-      this[0] = x;
+      this[0] = x as number;
       this[1] = y;
       this[2] = z;
       this[3] = w;
     }
   }
 
-  set(x, y, z, w) {
+  set(x: number, y: number, z: number, w: number): this {
     this[0] = x;
     this[1] = y;
     this[2] = z;
@@ -62,7 +54,7 @@ export default class Vector4 extends Vector {
     return this.check();
   }
 
-  copy(array) {
+  copy(array: Readonly<NumericArray>): this {
     this[0] = array[0];
     this[1] = array[1];
     this[2] = array[2];
@@ -70,7 +62,7 @@ export default class Vector4 extends Vector {
     return this.check();
   }
 
-  fromObject(object) {
+  fromObject(object: {x: number; y: number; z: number; w: number}): this {
     if (config.debug) {
       checkNumber(object.x);
       checkNumber(object.y);
@@ -84,61 +76,65 @@ export default class Vector4 extends Vector {
     return this;
   }
 
-  toObject(object) {
+  toObject(object: {x?: number; y?: number; z?: number; w?: number}): {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+  } {
     object.x = this[0];
     object.y = this[1];
     object.z = this[2];
     object.w = this[3];
-    return object;
+    return object as {
+      x: number;
+      y: number;
+      z: number;
+      w: number;
+    };
   }
 
   // Getters/setters
   /* eslint-disable no-multi-spaces, brace-style, no-return-assign */
-  get ELEMENTS() {
+  get ELEMENTS(): number {
     return 4;
   }
 
-  // x,y inherited from Vector
-
-  get z() {
+  get z(): number {
     return this[2];
   }
-
-  set z(value) {
+  set z(value: number) {
     this[2] = checkNumber(value);
   }
-
-  get w() {
+  get w(): number {
     return this[3];
   }
-
-  set w(value) {
+  set w(value: number) {
     this[3] = checkNumber(value);
   }
-  /* eslint-enable no-multi-spaces, brace-style, no-return-assign */
 
-  transform(matrix4) {
+  transform(matrix4: Readonly<NumericArray>): this {
     vec4.transformMat4(this, this, matrix4);
     return this.check();
   }
 
-  transformByMatrix3(matrix3) {
+  transformByMatrix3(matrix3: Readonly<NumericArray>): this {
     vec4_transformMat3(this, this, matrix3);
     return this.check();
   }
 
-  transformByMatrix2(matrix2) {
+  transformByMatrix2(matrix2: Readonly<NumericArray>): this {
     vec4_transformMat2(this, this, matrix2);
     return this.check();
   }
 
-  transformByQuaternion(quaternion) {
+  transformByQuaternion(quaternion: Readonly<NumericArray>): this {
     vec4.transformQuat(this, this, quaternion);
     return this.check();
   }
 
   // three.js compatibility
-  applyMatrix4(m) {
+  applyMatrix4(m: Matrix4): this {
     m.transform(this, this);
     return this;
   }

package/{dist/esm/index.d.ts → src/index.ts}

@@ -1,5 +1,7 @@
-// lib
-export * from './lib/common';
+// luma.gl, MIT license
+
+// types
+export type {TypedArray, NumericArray} from '@math.gl/types';
 
 // classes
 export {default as Vector2} from './classes/vector2';
@@ -9,44 +11,40 @@ export {default as Matrix3} from './classes/matrix3';
 export {default as Matrix4} from './classes/matrix4';
 export {default as Quaternion} from './classes/quaternion';
 
-// extras
-
-// export {checkNumber} from './lib/validators';
-export function assert(condition: boolean, message?: string): void;
-
 // experimental
 export {default as SphericalCoordinates} from './classes/spherical-coordinates';
 export {default as Pose} from './classes/pose';
 export {default as Euler} from './classes/euler';
 
-export const _MathUtils: {
-  EPSILON1: number;
-  EPSILON2: number;
-  EPSILON3: number;
-  EPSILON4: number;
-  EPSILON5: number;
-  EPSILON6: number;
-  EPSILON7: number;
-  EPSILON8: number;
-  EPSILON9: number;
-  EPSILON10: number;
-  EPSILON11: number;
-  EPSILON12: number;
-  EPSILON13: number;
-  EPSILON14: number;
-  EPSILON15: number;
-  EPSILON16: number;
-  EPSILON17: number;
-  EPSILON18: number;
-  EPSILON19: number;
-  EPSILON20: number;
-
-  PI_OVER_TWO: number;
-  PI_OVER_FOUR: number;
-  PI_OVER_SIX: number;
+export {default as _MathUtils} from './lib/math-utils';
 
-  TWO_PI: number;
-};
+// lib
+export {default as assert} from './lib/assert';
+
+export {
+  // math.gl global utility methods
+  config,
+  configure,
+  formatValue,
+  isArray,
+  clone,
+  equals,
+  exactEquals,
+  toRadians,
+  toDegrees,
+  // math.gl "GLSL"-style functions
+  radians,
+  degrees,
+  sin,
+  cos,
+  tan,
+  asin,
+  acos,
+  atan,
+  clamp,
+  lerp,
+  withEpsilon
+} from './lib/common';
 
 // DEPRECATED
 export {default as _SphericalCoordinates} from './classes/spherical-coordinates';

package/src/lib/{assert.js → assert.ts}

@@ -1,4 +1,4 @@
-export default function assert(condition, message) {
+export default function assert(condition: unknown, message?: string): void {
   if (!condition) {
     throw new Error(`math.gl assertion ${message}`);
   }

package/src/lib/common.ts

@@ -0,0 +1,304 @@
+// Copyright (c) 2017 Uber Technologies, Inc.
+// MIT License
+import {NumericArray} from '@math.gl/types';
+import assert from './assert';
+
+import type MathArray from '../classes/base/math-array';
+
+export type ConfigurationOptions = {
+  EPSILON?: number;
+  debug?: boolean;
+  precision?: number;
+  printTypes?: boolean;
+  printDegrees?: boolean;
+  printRowMajor?: boolean;
+  _cartographicRadians?: boolean;
+};
+
+const RADIANS_TO_DEGREES = (1 / Math.PI) * 180;
+const DEGREES_TO_RADIANS = (1 / 180) * Math.PI;
+
+// TODO - remove
+/* eslint-disable no-shadow */
+export const config: ConfigurationOptions = {};
+
+config.EPSILON = 1e-12;
+config.debug = false;
+config.precision = 4;
+config.printTypes = false;
+config.printDegrees = false;
+config.printRowMajor = true;
+
+export function configure(options: ConfigurationOptions = {}): ConfigurationOptions {
+  // Only copy existing keys
+  for (const key in options) {
+    assert(key in config);
+    config[key] = options[key];
+  }
+  return config;
+}
+
+/**
+ * Formats a value into a string
+ * @param value
+ * @param param1
+ * @returns
+ */
+export function formatValue(
+  value: number,
+  {precision = config.precision || 4}: ConfigurationOptions = {}
+): string {
+  value = round(value);
+  // get rid of trailing zeros
+  return `${parseFloat(value.toPrecision(precision))}`;
+}
+
+/**
+ * Check if value is an "array"
+ * Returns `true` if value is either an array or a typed array
+ *
+ * Note: returns `false` for `ArrayBuffer` and `DataView` instances
+ */
+export function isArray(value: unknown): boolean {
+  return Array.isArray(value) || (ArrayBuffer.isView(value) && !(value instanceof DataView));
+}
+
+export function clone(array: NumericArray | MathArray): NumericArray {
+  return 'clone' in array ? array.clone() : array.slice();
+}
+
+export function toRadians(degrees: number): number;
+export function toRadians(degrees: NumericArray): NumericArray;
+
+export function toRadians(degrees: number | NumericArray): number | NumericArray {
+  return radians(degrees as NumericArray);
+}
+
+export function toDegrees(degrees: number): number;
+export function toDegrees(degrees: NumericArray): NumericArray;
+
+export function toDegrees(radians: number | NumericArray): number | NumericArray {
+  return degrees(radians as NumericArray);
+}
+
+// GLSL math function equivalents - Works on both single values and vectors
+
+/**
+ * "GLSL equivalent" radians: Works on single values and vectors
+ */
+export function radians(degrees: number): number;
+export function radians(degrees: NumericArray, result?: NumericArray): NumericArray;
+
+export function radians(
+  degrees: number | NumericArray,
+  result?: NumericArray
+): number | NumericArray {
+  return map(degrees, (degrees) => degrees * DEGREES_TO_RADIANS, result);
+}
+
+/**
+ * "GLSL equivalent" degrees: Works on single values and vectors
+ */
+export function degrees(radians: number): number;
+export function degrees(radians: NumericArray, result?: NumericArray): NumericArray;
+
+export function degrees(
+  radians: number | NumericArray,
+  result?: NumericArray
+): number | NumericArray {
+  return map(radians, (radians) => radians * RADIANS_TO_DEGREES, result);
+}
+
+/**
+ * "GLSL equivalent" of `Math.sin`: Works on single values and vectors
+ * @deprecated
+ */
+export function sin(radians: number | NumericArray, result?: NumericArray): number | NumericArray {
+  return map(radians, (angle) => Math.sin(angle), result);
+}
+
+/**
+ * "GLSL equivalent" of `Math.cos`: Works on single values and vectors
+ * @deprecated
+ */
+export function cos(radians: number | NumericArray, result?: NumericArray): number | NumericArray {
+  return map(radians, (angle) => Math.cos(angle), result);
+}
+
+/**
+ * "GLSL equivalent" of `Math.tan`: Works on single values and vectors
+ * @deprecated
+ */
+export function tan(radians: number | NumericArray, result?: NumericArray): number | NumericArray {
+  return map(radians, (angle) => Math.tan(angle), result);
+}
+
+/**
+ * "GLSL equivalent" of `Math.asin`: Works on single values and vectors
+ * @deprecated
+ */
+export function asin(radians: number | NumericArray, result?: NumericArray): number | NumericArray {
+  return map(radians, (angle) => Math.asin(angle), result);
+}
+
+/**
+ * "GLSL equivalent" of `Math.acos`: Works on single values and vectors
+ * @deprecated
+ */
+export function acos(radians: number | NumericArray, result?: NumericArray): number | NumericArray {
+  return map(radians, (angle) => Math.acos(angle), result);
+}
+
+/**
+ * "GLSL equivalent" of `Math.atan`: Works on single values and vectors
+ * @deprecated
+ */
+export function atan(radians: number | NumericArray, result?: NumericArray): number | NumericArray {
+  return map(radians, (angle) => Math.atan(angle), result);
+}
+
+/**
+ * GLSL style value clamping: Works on single values and vectors
+ */
+export function clamp(value: number, min: number, max: number): number;
+export function clamp(value: NumericArray, min: number, max: number): NumericArray;
+
+export function clamp(
+  value: number | NumericArray,
+  min: number,
+  max: number
+): number | NumericArray {
+  return map(value, (value) => Math.max(min, Math.min(max, value)));
+}
+
+/**
+ * Interpolate between two numbers or two arrays
+ */
+export function lerp(a: number, b: number, t: number): number;
+export function lerp(a: NumericArray, b: NumericArray, t: number): NumericArray;
+
+export function lerp(
+  a: number | NumericArray,
+  b: number | NumericArray,
+  t: number
+): number | NumericArray {
+  if (isArray(a)) {
+    return (a as NumericArray).map((ai: number, i: number) => lerp(ai, (b as NumericArray)[i], t));
+  }
+  return t * (b as number) + (1 - t) * (a as number);
+}
+
+/* eslint-disable */
+
+/**
+ * Compares any two math objects, using `equals` method if available.
+ * @param a
+ * @param b
+ * @param epsilon
+ * @returns
+ */
+export function equals(a: any, b: any, epsilon?: number): boolean {
+  const oldEpsilon = config.EPSILON;
+  if (epsilon) {
+    config.EPSILON = epsilon;
+  }
+  try {
+    if (a === b) {
+      return true;
+    }
+    if (isArray(a) && isArray(b)) {
+      if (a.length !== b.length) {
+        return false;
+      }
+      for (let i = 0; i < a.length; ++i) {
+        // eslint-disable-next-line max-depth
+        if (!equals(a[i], b[i])) {
+          return false;
+        }
+      }
+      return true;
+    }
+    if (a && a.equals) {
+      return a.equals(b);
+    }
+    if (b && b.equals) {
+      return b.equals(a);
+    }
+    if (typeof a === 'number' && typeof b === 'number') {
+      return Math.abs(a - b) <= config.EPSILON * Math.max(1, Math.abs(a), Math.abs(b));
+    }
+    return false;
+  } finally {
+    config.EPSILON = oldEpsilon;
+  }
+}
+
+export function exactEquals(a: any, b: any): boolean {
+  if (a === b) {
+    return true;
+  }
+  if (a && typeof a === 'object' && b && typeof b === 'object') {
+    if (a.constructor !== b.constructor) {
+      return false;
+    }
+    if (a.exactEquals) {
+      return a.exactEquals(b);
+    }
+  }
+  if (isArray(a) && isArray(b)) {
+    if (a.length !== b.length) {
+      return false;
+    }
+    for (let i = 0; i < a.length; ++i) {
+      if (!exactEquals(a[i], b[i])) {
+        return false;
+      }
+    }
+    return true;
+  }
+  return false;
+}
+
+/* eslint-enable */
+
+export function withEpsilon(epsilon: number, func: () => any): any {
+  const oldPrecision = config.EPSILON;
+  config.EPSILON = epsilon;
+  let value;
+  try {
+    value = func();
+  } finally {
+    config.EPSILON = oldPrecision;
+  }
+  return value;
+}
+
+// HELPERS
+
+function round(value: number): number {
+  return Math.round(value / config.EPSILON) * config.EPSILON;
+}
+
+// If the array has a clone function, calls it, otherwise returns a copy
+function duplicateArray(array: NumericArray): NumericArray {
+  // @ts-expect-error We check for math.gl class methods
+  return array.clone ? array.clone() : (new Array(array.length) as number[]);
+}
+
+// If the argument value is an array, applies the func element wise,
+// otherwise applies func to the argument value
+function map(
+  value: number | NumericArray,
+  func: (x: number, index?: number, result?: NumericArray) => number,
+  result?: NumericArray
+): number | NumericArray {
+  if (isArray(value)) {
+    const array = value as NumericArray;
+    result = result || duplicateArray(array);
+    for (let i = 0; i < result.length && i < array.length; ++i) {
+      result[i] = func(value[i], i, result);
+    }
+    return result;
+  }
+  return func(value as number);
+}

package/src/lib/{gl-matrix-extras.js → gl-matrix-extras.ts}

@@ -1,7 +1,12 @@
 /* eslint-disable camelcase */
+import {NumericArray} from '@math.gl/types';
 // vec2 additions
 
-export function vec2_transformMat4AsVector(out, a, m) {
+export function vec2_transformMat4AsVector<T extends NumericArray>(
+  out: T,
+  a: Readonly<NumericArray>,
+  m: Readonly<NumericArray>
+): T {
   const x = a[0];
   const y = a[1];
   const w = m[3] * x + m[7] * y || 1.0;
@@ -13,7 +18,11 @@ export function vec2_transformMat4AsVector(out, a, m) {
 // vec3 additions
 
 // Transform as vector, only uses 3x3 minor matrix
-export function vec3_transformMat4AsVector(out, a, m) {
+export function vec3_transformMat4AsVector<T extends NumericArray>(
+  out: T,
+  a: Readonly<NumericArray>,
+  m: Readonly<NumericArray>
+): T {
   const x = a[0];
   const y = a[1];
   const z = a[2];
@@ -24,7 +33,11 @@ export function vec3_transformMat4AsVector(out, a, m) {
   return out;
 }
 
-export function vec3_transformMat2(out, a, m) {
+export function vec3_transformMat2<T extends NumericArray>(
+  out: T,
+  a: Readonly<NumericArray>,
+  m: Readonly<NumericArray>
+): T {
   const x = a[0];
   const y = a[1];
   out[0] = m[0] * x + m[2] * y;
@@ -35,7 +48,11 @@ export function vec3_transformMat2(out, a, m) {
 
 // vec4 additions
 
-export function vec4_transformMat2(out, a, m) {
+export function vec4_transformMat2<T extends NumericArray>(
+  out: T,
+  a: Readonly<NumericArray>,
+  m: Readonly<NumericArray>
+): T {
   const x = a[0];
   const y = a[1];
   out[0] = m[0] * x + m[2] * y;
@@ -45,7 +62,11 @@ export function vec4_transformMat2(out, a, m) {
   return out;
 }
 
-export function vec4_transformMat3(out, a, m) {
+export function vec4_transformMat3<T extends NumericArray>(
+  out: T,
+  a: Readonly<NumericArray>,
+  m: Readonly<NumericArray>
+): T {
   const x = a[0];
   const y = a[1];
   const z = a[2];