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

package/src/classes/{spherical-coordinates.js → spherical-coordinates.ts}

@@ -1,55 +1,77 @@
 // 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
 // Adaptation of THREE.js Spherical class, under MIT license
+import Vector3 from './vector3';
 import {formatValue, equals, config} from '../lib/common';
 import {degrees, radians, clamp} from '../lib/common';
-import Vector3 from './vector3';
-
-// @ts-ignore: error TS2307: Cannot find module 'gl-matrix/...'.
 import * as vec3 from 'gl-matrix/vec3';
+import {NumericArray} from '@math.gl/types';
+
+type SphericalCoordinatesOptions = {
+  phi?: number;
+  theta?: number;
+  radius?: number;
+  bearing?: number;
+  pitch?: number;
+  altitude?: number;
+  radiusScale?: number;
+};
+
+type FormatOptions = {
+  printTypes?: boolean;
+};
 
 // TODO - import epsilon
 const EPSILON = 0.000001;
+const EARTH_RADIUS_METERS = 6371000;
 
-const EARTH_RADIUS_METERS = 6.371e6;
-
-// Todo [rho, theta, phi] ?
+/**
+ * The poles (phi) are at the positive and negative y axis.
+ * The equator starts at positive z.
+ * @link https://en.wikipedia.org/wiki/Spherical_coordinate_system
+ */
 export default class SphericalCoordinates {
-  // @ts-ignore TS2740: Type '{}' is missing the following properties from type
+  phi: number;
+  theta: number;
+  radius: number;
+  radiusScale: number;
+  // bearing: number;
+  // pitch: number;
+  // altitude: number;
+
+  // lnglatZ coordinates
+  // longitude: number;
+  // latitude: number;
+  // lng: number;
+  // lat: number;
+  // z: number;
+
+  /**
+   * Creates a new SphericalCoordinates object
+   * @param options
+   * @param [options.phi] =0 - rotation around X (latitude)
+   * @param [options.theta] =0 - rotation around Y (longitude)
+   * @param [options.radius] =1 - Distance from center
+   * @param [options.bearing]
+   * @param [options.pitch]
+   * @param [options.altitude]
+   * @param [options.radiusScale] =1
+   */
   // eslint-disable-next-line complexity
   constructor({
     phi = 0,
     theta = 0,
     radius = 1,
-    bearing = undefined,
-    pitch = undefined,
-    altitude = undefined,
+    bearing,
+    pitch,
+    altitude,
     radiusScale = EARTH_RADIUS_METERS
-  } = {}) {
+  }: SphericalCoordinatesOptions = {}) {
     this.phi = phi;
     this.theta = theta;
     // TODO - silently accepts illegal 0
     this.radius = radius || altitude || 1; // radial distance from center
     this.radiusScale = radiusScale || 1; // Used by lngLatZ
-
     if (bearing !== undefined) {
       this.bearing = bearing; // up / down towards top and bottom pole
     }
@@ -59,17 +81,17 @@ export default class SphericalCoordinates {
     this.check();
   }
 
-  toString() {
+  toString(): string {
     return this.formatString(config);
   }
 
-  formatString({printTypes = false}) {
+  formatString({printTypes = false}: FormatOptions): string {
     const f = formatValue;
     return `${printTypes ? 'Spherical' : ''}\
 [rho:${f(this.radius)},theta:${f(this.theta)},phi:${f(this.phi)}]`;
   }
 
-  equals(other) {
+  equals(other: SphericalCoordinates): boolean {
     return (
       equals(this.radius, other.radius) &&
       equals(this.theta, other.theta) &&
@@ -77,71 +99,79 @@ export default class SphericalCoordinates {
     );
   }
 
-  exactEquals(other) {
+  exactEquals(other: SphericalCoordinates): boolean {
     return this.radius === other.radius && this.theta === other.theta && this.phi === other.phi;
   }
 
   /* eslint-disable brace-style */
   // Cartographic (bearing 0 north, pitch 0 look from above)
-  get bearing() {
+  get bearing(): number {
     return 180 - degrees(this.phi);
   }
-  set bearing(v) {
+
+  set bearing(v: number) {
     this.phi = Math.PI - radians(v);
   }
-  get pitch() {
+
+  get pitch(): number {
     return degrees(this.theta);
   }
-  set pitch(v) {
+
+  set pitch(v: number) {
     this.theta = radians(v);
   }
+
   // get pitch() { return 90 - degrees(this.phi); }
   // set pitch(v) { this.phi = radians(v) + Math.PI / 2; }
   // get altitude() { return this.radius - 1; } // relative altitude
-
   // lnglatZ coordinates
-  get longitude() {
+  get longitude(): number {
     return degrees(this.phi);
   }
-  get latitude() {
+
+  get latitude(): number {
     return degrees(this.theta);
   }
-  get lng() {
+
+  get lng(): number {
     return degrees(this.phi);
   }
-  get lat() {
+
+  get lat(): number {
     return degrees(this.theta);
   }
-  get z() {
+
+  get z(): number {
     return (this.radius - 1) * this.radiusScale;
   }
-  /* eslint-enable brace-style */
 
-  set(radius, phi, theta) {
+  /* eslint-enable brace-style */
+  set(radius: number, phi: number, theta: number): this {
     this.radius = radius;
     this.phi = phi;
     this.theta = theta;
     return this.check();
   }
 
-  clone() {
+  clone(): SphericalCoordinates {
     return new SphericalCoordinates().copy(this);
   }
 
-  copy(other) {
+  copy(other: SphericalCoordinates): this {
     this.radius = other.radius;
     this.phi = other.phi;
     this.theta = other.theta;
     return this.check();
   }
 
-  fromLngLatZ([lng, lat, z]) {
+  fromLngLatZ([lng, lat, z]: [number, number, number]): this {
     this.radius = 1 + z / this.radiusScale;
     this.phi = radians(lat);
     this.theta = radians(lng);
+    return this.check();
   }
 
-  fromVector3(v) {
+  fromVector3(v: Readonly<NumericArray>): this {
     this.radius = vec3.length(v);
     if (this.radius > 0) {
       this.theta = Math.atan2(v[0], v[1]); // equator angle around y-up axis
@@ -150,19 +180,19 @@ export default class SphericalCoordinates {
     return this.check();
   }
 
-  toVector3() {
+  toVector3(): Vector3 {
     return new Vector3(0, 0, this.radius)
       .rotateX({radians: this.theta})
       .rotateZ({radians: this.phi});
   }
 
   // restrict phi to be betwee EPS and PI-EPS
-  makeSafe() {
+  makeSafe(): this {
     this.phi = Math.max(EPSILON, Math.min(Math.PI - EPSILON, this.phi));
     return this;
   }
 
-  check() {
+  check(): this {
     // this.makeSafe();
     if (!Number.isFinite(this.phi) || !Number.isFinite(this.theta) || !(this.radius > 0)) {
       throw new Error('SphericalCoordinates: some fields set to invalid numbers');

package/src/classes/vector2.ts

@@ -0,0 +1,127 @@
+// Copyright (c) 2017 Uber Technologies, Inc.
+// MIT License
+import Vector from './base/vector';
+import {config, isArray} from '../lib/common';
+import {checkNumber} from '../lib/validators';
+import * as vec2 from 'gl-matrix/vec2';
+/* eslint-disable camelcase */
+import {vec2_transformMat4AsVector} from '../lib/gl-matrix-extras';
+import {NumericArray} from '@math.gl/types';
+
+/**
+ * Two-element vector class.
+ * Subclass of Array<number>
+ */
+export default class Vector2 extends Vector {
+  // Creates a new, empty vec2
+  constructor(x: number | Readonly<NumericArray> = 0, y: number = 0) {
+    // PERF NOTE: initialize elements as double precision numbers
+    super(2); // -0, -0);
+    if (isArray(x) && arguments.length === 1) {
+      this.copy(x as Readonly<NumericArray>);
+    } else {
+      if (config.debug) {
+        checkNumber(x);
+        checkNumber(y);
+      }
+      this[0] = x as number;
+      this[1] = y;
+    }
+  }
+
+  set(x: number, y: number): this {
+    this[0] = x;
+    this[1] = y;
+    return this.check();
+  }
+
+  copy(array: Readonly<NumericArray>): this {
+    this[0] = array[0];
+    this[1] = array[1];
+    return this.check();
+  }
+
+  fromObject(object: {x: number; y: number}): this {
+    if (config.debug) {
+      checkNumber(object.x);
+      checkNumber(object.y);
+    }
+    this[0] = object.x;
+    this[1] = object.y;
+    return this.check();
+  }
+
+  toObject(object: {x?: number; y?: number}): {x: number; y: number} {
+    object.x = this[0];
+    object.y = this[1];
+    return object as {x: number; y: number};
+  }
+
+  // Getters/setters
+
+  get ELEMENTS(): number {
+    return 2;
+  }
+
+  /**
+   * Returns angle from x axis
+   * @returns
+   */
+  horizontalAngle(): number {
+    return Math.atan2(this.y, this.x);
+  }
+
+  /**
+   * Returns angle from y axis
+   * @returns
+   */
+  verticalAngle(): number {
+    return Math.atan2(this.x, this.y);
+  }
+
+  // Transforms
+
+  /**
+   * Transforms as point
+   * @param matrix4
+   * @returns
+   */
+  transform(matrix4: Readonly<NumericArray>): this {
+    return this.transformAsPoint(matrix4);
+  }
+
+  /**
+   * transforms as point (4th component is implicitly 1)
+   * @param matrix4
+   * @returns
+   */
+  transformAsPoint(matrix4: Readonly<NumericArray>): this {
+    vec2.transformMat4(this, this, matrix4);
+    return this.check();
+  }
+
+  /**
+   * transforms as vector (4th component is implicitly 0, ignores translation. slightly faster)
+   * @param matrix4
+   * @returns
+   */
+  transformAsVector(matrix4: Readonly<NumericArray>): this {
+    vec2_transformMat4AsVector(this, this, matrix4);
+    return this.check();
+  }
+
+  transformByMatrix3(matrix3: Readonly<NumericArray>): this {
+    vec2.transformMat3(this, this, matrix3);
+    return this.check();
+  }
+
+  transformByMatrix2x3(matrix2x3: Readonly<NumericArray>): this {
+    vec2.transformMat2d(this, this, matrix2x3);
+    return this.check();
+  }
+
+  transformByMatrix2(matrix2: Readonly<NumericArray>): this {
+    vec2.transformMat2(this, this, matrix2);
+    return this.check();
+  }
+}

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

@@ -1,51 +1,41 @@
 // 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 {NumericArray} from '@math.gl/types';
 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 vec3 from 'gl-matrix/vec3';
-// eslint-disable-next-line camelcase
+/* eslint-disable camelcase */
 import {vec3_transformMat2, vec3_transformMat4AsVector} from '../lib/gl-matrix-extras';
 
 const ORIGIN = [0, 0, 0];
-const constants = {};
 
+let ZERO: Vector3;
+
+/**
+ * Three-element vector class.
+ * Subclass of Array<number>
+ */
 export default class Vector3 extends Vector {
-  static get ZERO() {
-    return (constants.ZERO = constants.ZERO || Object.freeze(new Vector3(0, 0, 0, 0)));
+  static get ZERO(): Vector3 {
+    if (!ZERO) {
+      ZERO = new Vector3(0, 0, 0);
+      Object.freeze(ZERO);
+    }
+    return ZERO;
   }
 
   /**
    * @class
-   * @param {Number | [Number, Number, Number]} x
-   * @param {Number} y - rotation around X (latitude)
-   * @param {Number} z - rotation around X (latitude)
+   * @param x
+   * @param y
+   * @param z
    */
-  constructor(x = 0, y = 0, z = 0) {
+  constructor(x: number | Readonly<NumericArray> = 0, y: number = 0, z: number = 0) {
     // PERF NOTE: initialize elements as double precision numbers
     super(-0, -0, -0);
     if (arguments.length === 1 && isArray(x)) {
-      this.copy(x);
+      this.copy(x as NumericArray);
     } else {
       // this.set(x, y, z);
       if (config.debug) {
@@ -53,28 +43,28 @@ export default class Vector3 extends Vector {
         checkNumber(y);
         checkNumber(z);
       }
-      // @ts-ignore TS2412: Property '0' of type 'number | [number, number, number]' is not assignable to numeric index type 'number'
+      // @ts-expect-error TS2412: Property '0' of type 'number | [number, number, number]' is not assignable to numeric index type 'number'
       this[0] = x;
       this[1] = y;
       this[2] = z;
     }
   }
 
-  set(x, y, z) {
+  set(x: number, y: number, z: number): this {
     this[0] = x;
     this[1] = y;
     this[2] = z;
     return this.check();
   }
 
-  copy(array) {
+  copy(array: Readonly<NumericArray>): this {
     this[0] = array[0];
     this[1] = array[1];
     this[2] = array[2];
     return this.check();
   }
 
-  fromObject(object) {
+  fromObject(object: {x: number; y: number; z: number}): this {
     if (config.debug) {
       checkNumber(object.x);
       checkNumber(object.y);
@@ -86,51 +76,49 @@ export default class Vector3 extends Vector {
     return this.check();
   }
 
-  toObject(object) {
+  toObject(object: {x?: number; y?: number; z?: number}): {x: number; y: number; z: number} {
     object.x = this[0];
     object.y = this[1];
     object.z = this[2];
-    return object;
+    return object as {x: number; y: number; z: number};
   }
 
   // Getters/setters
-  /* eslint-disable no-multi-spaces, brace-style, no-return-assign */
-  get ELEMENTS() {
+
+  get ELEMENTS(): number {
     return 3;
   }
-
-  // x,y inherited from Vector
-
-  get z() {
+  get z(): number {
     return this[2];
   }
-  set z(value) {
+  set z(value: number) {
     this[2] = checkNumber(value);
   }
-  /* eslint-enable no-multi-spaces, brace-style, no-return-assign */
 
-  angle(vector) {
+  // ACCESSORS
+
+  angle(vector: Readonly<NumericArray>): number {
     return vec3.angle(this, vector);
   }
 
   // MODIFIERS
 
-  cross(vector) {
+  cross(vector: Readonly<NumericArray>): this {
     vec3.cross(this, this, vector);
     return this.check();
   }
 
-  rotateX({radians, origin = ORIGIN}) {
+  rotateX({radians, origin = ORIGIN}: {radians: number; origin?: Readonly<NumericArray>}): this {
     vec3.rotateX(this, this, origin, radians);
     return this.check();
   }
 
-  rotateY({radians, origin = ORIGIN}) {
+  rotateY({radians, origin = ORIGIN}: {radians: number; origin?: Readonly<NumericArray>}): this {
     vec3.rotateY(this, this, origin, radians);
     return this.check();
   }
 
-  rotateZ({radians, origin = ORIGIN}) {
+  rotateZ({radians, origin = ORIGIN}: {radians: number; origin?: Readonly<NumericArray>}): this {
     vec3.rotateZ(this, this, origin, radians);
     return this.check();
   }
@@ -138,33 +126,33 @@ export default class Vector3 extends Vector {
   // Transforms
 
   // transforms as point (4th component is implicitly 1)
-  transform(matrix4) {
+  transform(matrix4: Readonly<NumericArray>): this {
     return this.transformAsPoint(matrix4);
   }
 
   // transforms as point (4th component is implicitly 1)
-  transformAsPoint(matrix4) {
+  transformAsPoint(matrix4: Readonly<NumericArray>): this {
     vec3.transformMat4(this, this, matrix4);
     return this.check();
   }
 
   // transforms as vector  (4th component is implicitly 0, ignores translation. slightly faster)
-  transformAsVector(matrix4) {
+  transformAsVector(matrix4: Readonly<NumericArray>): this {
     vec3_transformMat4AsVector(this, this, matrix4);
     return this.check();
   }
 
-  transformByMatrix3(matrix3) {
+  transformByMatrix3(matrix3: Readonly<NumericArray>): this {
     vec3.transformMat3(this, this, matrix3);
     return this.check();
   }
 
-  transformByMatrix2(matrix2) {
+  transformByMatrix2(matrix2: Readonly<NumericArray>): this {
     vec3_transformMat2(this, this, matrix2);
     return this.check();
   }
 
-  transformByQuaternion(quaternion) {
+  transformByQuaternion(quaternion: Readonly<NumericArray>): this {
     vec3.transformQuat(this, this, quaternion);
     return this.check();
   }