@math.gl/culling 3.5.3 → 3.6.0-alpha.1

package/dist/lib/plane.js

@@ -0,0 +1,63 @@
+// This file is derived from the Cesium math library under Apache 2 license
+// See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
+/* eslint-disable */
+import { Vector3, equals, assert } from '@math.gl/core';
+const scratchPosition = new Vector3();
+const scratchNormal = new Vector3();
+// A plane in Hessian Normal Form
+export default class Plane {
+    constructor(normal = [0, 0, 1], distance = 0) {
+        this.normal = new Vector3();
+        this.distance = -0;
+        this.fromNormalDistance(normal, distance);
+    }
+    /** Creates a plane from a normal and a distance from the origin. */
+    fromNormalDistance(normal, distance) {
+        assert(Number.isFinite(distance));
+        this.normal.from(normal).normalize();
+        this.distance = distance;
+        return this;
+    }
+    /** Creates a plane from a normal and a point on the plane. */
+    fromPointNormal(point, normal) {
+        point = scratchPosition.from(point);
+        this.normal.from(normal).normalize();
+        const distance = -this.normal.dot(point);
+        this.distance = distance;
+        return this;
+    }
+    /** Creates a plane from the general equation */
+    fromCoefficients(a, b, c, d) {
+        this.normal.set(a, b, c);
+        assert(equals(this.normal.len(), 1));
+        this.distance = d;
+        return this;
+    }
+    /** Duplicates a Plane instance. */
+    clone() {
+        return new Plane(this.normal, this.distance);
+    }
+    /** Compares the provided Planes by normal and distance */
+    equals(right) {
+        return equals(this.distance, right.distance) && equals(this.normal, right.normal);
+    }
+    /** Computes the signed shortest distance of a point to a plane.
+     * The sign of the distance determines which side of the plane the point is on.
+     */
+    getPointDistance(point) {
+        return this.normal.dot(point) + this.distance;
+    }
+    /** Transforms the plane by the given transformation matrix. */
+    transform(matrix4) {
+        const normal = scratchNormal.copy(this.normal).transformAsVector(matrix4).normalize();
+        const point = this.normal.scale(-this.distance).transform(matrix4);
+        return this.fromPointNormal(point, normal);
+    }
+    projectPointOntoPlane(point, result = [0, 0, 0]) {
+        point = scratchPosition.from(point);
+        // projectedPoint = point - (normal.point + scale) * normal
+        const pointDistance = this.getPointDistance(point);
+        const scaledNormal = scratchNormal.copy(this.normal).scale(pointDistance);
+        return point.subtract(scaledNormal).to(result);
+    }
+}

package/package.json

@@ -5,7 +5,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "3.5.3",
+  "version": "3.6.0-alpha.1",
   "keywords": [
     "webgl",
     "javascript",
@@ -26,7 +26,7 @@
     "type": "git",
     "url": "https://github.com/uber-web/math.gl.git"
   },
-  "types": "src/index.d.ts",
+  "types": "dist/index.d.ts",
   "main": "dist/es5/index.js",
   "module": "dist/esm/index.js",
   "files": [
@@ -35,8 +35,8 @@
   ],
   "dependencies": {
     "@babel/runtime": "^7.12.0",
-    "@math.gl/core": "3.5.3",
-    "gl-matrix": "^3.0.0"
+    "@math.gl/core": "3.6.0-alpha.1",
+    "gl-matrix": "~3.3.0"
   },
-  "gitHead": "b9183c9ec46dd309a601e1de7beb90a18a3e0fea"
+  "gitHead": "45386981340895bf201c2ebb76257c9bbffd8ff6"
 }

package/src/constants.ts

@@ -0,0 +1,8 @@
+// This file is derived from the Cesium math library under Apache 2 license
+// See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
+
+export enum INTERSECTION {
+  OUTSIDE = -1, // Represents that an object is not contained within the frustum.
+  INTERSECTING = 0, // Represents that an object intersects one of the frustum's planes.
+  INSIDE = 1 // Represents that an object is fully within the frustum.
+}

package/src/{index.js → index.ts}

@@ -18,7 +18,3 @@ export {
   makeOrientedBoundingBoxFromPoints
 } from './lib/algorithms/bounding-box-from-points';
 export {default as computeEigenDecomposition} from './lib/algorithms/compute-eigen-decomposition';
-
-// Deprecated
-export {INTERSECTION as Intersect} from './constants';
-export {INTERSECTION as INTERSECT} from './constants';

package/src/lib/algorithms/{bounding-box-from-points.js → bounding-box-from-points.ts}

@@ -23,8 +23,17 @@ const scratchEigenResult = {
   unitary: new Matrix3()
 };
 
+/**
+ * Computes an instance of an OrientedBoundingBox of the given positions.
+ *
+ * This is an implementation of Stefan Gottschalk's Collision Queries using Oriented Bounding Boxes solution (PHD thesis).
+ * Reference: http://gamma.cs.unc.edu/users/gottschalk/main.pdf
+ */
 /* eslint-disable max-statements */
-export function makeOrientedBoundingBoxFromPoints(positions, result = new OrientedBoundingBox()) {
+export function makeOrientedBoundingBoxFromPoints(
+  positions: number[][],
+  result: OrientedBoundingBox = new OrientedBoundingBox()
+): OrientedBoundingBox {
   if (!positions || positions.length === 0) {
     result.halfAxes = new Matrix3([0, 0, 0, 0, 0, 0, 0, 0, 0]);
     result.center = new Vector3();
@@ -89,13 +98,15 @@ export function makeOrientedBoundingBoxFromPoints(positions, result = new Orient
   let l3 = Number.MAX_VALUE;
 
   for (const position of positions) {
-    u1 = Math.max(position.dot(v1), u1);
-    u2 = Math.max(position.dot(v2), u2);
-    u3 = Math.max(position.dot(v3), u3);
+    scratchVector2.copy(position);
 
-    l1 = Math.min(position.dot(v1), l1);
-    l2 = Math.min(position.dot(v2), l2);
-    l3 = Math.min(position.dot(v3), l3);
+    u1 = Math.max(scratchVector2.dot(v1), u1);
+    u2 = Math.max(scratchVector2.dot(v2), u2);
+    u3 = Math.max(scratchVector2.dot(v3), u3);
+
+    l1 = Math.min(scratchVector2.dot(v1), l1);
+    l2 = Math.min(scratchVector2.dot(v2), l2);
+    l3 = Math.min(scratchVector2.dot(v3), l3);
   }
 
   v1 = v1.multiplyByScalar(0.5 * (l1 + u1));
@@ -111,10 +122,14 @@ export function makeOrientedBoundingBoxFromPoints(positions, result = new Orient
   return result;
 }
 
+/**
+ * Computes an instance of an AxisAlignedBoundingBox. The box is determined by
+ * finding the points spaced the farthest apart on the x, y, and z axes.
+ */
 export function makeAxisAlignedBoundingBoxFromPoints(
-  positions,
-  result = new AxisAlignedBoundingBox()
-) {
+  positions: readonly number[][],
+  result: AxisAlignedBoundingBox = new AxisAlignedBoundingBox()
+): AxisAlignedBoundingBox {
   if (!positions || positions.length === 0) {
     result.minimum.set(0, 0, 0);
     result.maximum.set(0, 0, 0);

package/src/lib/algorithms/{bounding-sphere-from-points.js → bounding-sphere-from-points.ts}

@@ -19,7 +19,21 @@ const fromPointsMaxBoxPt = new Vector3();
 const fromPointsNaiveCenterScratch = new Vector3();
 const volumeConstant = (4.0 / 3.0) * Math.PI;
 
-export default function makeBoundingSphereFromPoints(positions, result = new BoundingSphere()) {
+/**
+ * Computes a tight-fitting bounding sphere enclosing a list of 3D Cartesian points.
+ *
+ * The bounding sphere is computed by running two algorithms, a naive algorithm and
+ * Ritter's algorithm. The smaller of the two spheres is used to ensure a tight fit.
+ * Bounding sphere computation article http://blogs.agi.com/insight3d/index.php/2008/02/04/a-bounding
+ *
+ * @param positions An array of points that the bounding sphere will enclose.
+ * @param result Optional object onto which to store the result.
+ * @returns The modified result parameter or a new `BoundingSphere` instance if not provided.
+ */
+export default function makeBoundingSphereFromPoints(
+  positions: number[][],
+  result: BoundingSphere = new BoundingSphere()
+): BoundingSphere {
   if (!positions || positions.length === 0) {
     return result.fromCenterRadius([0, 0, 0], 0);
   }
@@ -43,27 +57,27 @@ export default function makeBoundingSphereFromPoints(positions, result = new Bou
 
     // Store points containing the the smallest and largest components
     if (x < xMin.x) {
-      currentPos.copy(xMin);
+      xMin.copy(currentPos);
     }
 
     if (x > xMax.x) {
-      currentPos.copy(xMax);
+      xMax.copy(currentPos);
     }
 
     if (y < yMin.y) {
-      currentPos.copy(yMin);
+      yMin.copy(currentPos);
     }
 
     if (y > yMax.y) {
-      currentPos.copy(yMax);
+      yMax.copy(currentPos);
     }
 
     if (z < zMin.z) {
-      currentPos.copy(zMin);
+      zMin.copy(currentPos);
     }
 
     if (z > zMax.z) {
-      currentPos.copy(zMax);
+      zMax.copy(currentPos);
     }
   }
 

package/src/lib/algorithms/{compute-eigen-decomposition.js → compute-eigen-decomposition.ts}

@@ -10,7 +10,46 @@ const scratchDiagonal = new Matrix3();
 const jMatrix = new Matrix3();
 const jMatrixTranspose = new Matrix3();
 
-export default function computeEigenDecomposition(matrix, result = {}) {
+export type EigenDecomposition = {
+  unitary: Matrix3;
+  diagonal: Matrix3;
+};
+
+/**
+ * Computes the eigenvectors and eigenvalues of a symmetric matrix.
+ *
+ * - Returns a diagonal matrix and unitary matrix such that:
+ * `matrix = unitary matrix * diagonal matrix * transpose(unitary matrix)`
+ * - The values along the diagonal of the diagonal matrix are the eigenvalues. The columns
+ * of the unitary matrix are the corresponding eigenvectors.
+ * - This routine was created based upon Matrix Computations, 3rd ed., by Golub and Van Loan,
+ * section 8.4.3 The Classical Jacobi Algorithm
+ *
+ * @param matrix The 3x3 matrix to decompose into diagonal and unitary matrix. Expected to be symmetric.
+ * @param result Optional object with unitary and diagonal properties which are matrices onto which to store the result.
+ * @returns An object with unitary and diagonal properties which are the unitary and diagonal matrices, respectively.
+ *
+ * @example
+ * const a = //... symmetric matrix
+ * const result = {
+ *   unitary : new Matrix3(),
+ *   diagonal : new Matrix3()
+ * };
+ * computeEigenDecomposition(a, result);
+ *
+ * const unitaryTranspose = Matrix3.transpose(result.unitary, new Matrix3());
+ * const b = Matrix3.multiply(result.unitary, result.diagonal, new Matrix3());
+ * Matrix3.multiply(b, unitaryTranspose, b); // b is now equal to a
+ *
+ * const lambda = result.diagonal.getColumn(0, new Vector3()).x;  // first eigenvalue
+ * const v = result.unitary.getColumn(0, new Vector3());          // first eigenvector
+ * const c = v.multiplyByScalar(lambda);                          // equal to v.transformByMatrix3(a)
+ */
+export default function computeEigenDecomposition(
+  matrix: number[],
+  // @ts-expect-error accept empty object type
+  result: EigenDecomposition = {}
+): EigenDecomposition {
   const EIGEN_TOLERANCE = _MathUtils.EPSILON20;
   const EIGEN_MAX_SWEEPS = 10;
 

package/src/lib/bounding-volumes/{axis-aligned-bounding-box.js → axis-aligned-bounding-box.ts}

@@ -1,11 +1,38 @@
+import {BoundingVolume} from './bounding-volume';
 import {Vector3} from '@math.gl/core';
+import Plane from '../plane';
 import {INTERSECTION} from '../../constants';
 
 const scratchVector = new Vector3();
 const scratchNormal = new Vector3();
 
-export default class AxisAlignedBoundingBox {
-  constructor(minimum = [0, 0, 0], maximum = [0, 0, 0], center = null) {
+/**
+ * An axis aligned bounding box - aligned with coordinate axes
+ * @see BoundingVolume
+ * @see BoundingRectangle
+ * @see OrientedBoundingBox
+ */
+export default class AxisAlignedBoundingBox implements BoundingVolume {
+  /** The center point of the bounding box. */
+  readonly center: Vector3;
+  /** The positive half diagonal of the bounding box. */
+  readonly halfDiagonal: Vector3;
+  /** The minimum point defining the bounding box. [0, 0, 0] for empty box */
+  readonly minimum: Vector3;
+  /** The maximum point defining the bounding box. [0, 0, 0] for empty box */
+  readonly maximum: Vector3;
+
+  /**
+   * Creates an instance of an AxisAlignedBoundingBox from the minimum and maximum points along the x, y, and z axes.
+   * @param minimum=[0, 0, 0] The minimum point along the x, y, and z axes.
+   * @param maximum=[0, 0, 0] The maximum point along the x, y, and z axes.
+   * @param center The center of the box; automatically computed if not supplied.
+   */
+  constructor(
+    minimum: readonly number[] = [0, 0, 0],
+    maximum: readonly number[] = [0, 0, 0],
+    center?: readonly number[]
+  ) {
     // If center was not defined, compute it.
     center = center || scratchVector.copy(minimum).add(maximum).scale(0.5);
     this.center = new Vector3(center);
@@ -49,19 +76,24 @@ export default class AxisAlignedBoundingBox {
     );
   }
 
-  transform(transformation) {
-    this.center.transformAsPoint(transformation);
-    // TODO - this.halfDiagonal.transformAsVector(transformation);
-    this.halfDiagonal.transform(transformation);
-    this.minimum.transform(transformation);
-    this.maximum.transform(transformation);
+  /**
+   * Applies a 4x4 affine transformation matrix to a bounding sphere.
+   * @param transform The transformation matrix to apply to the bounding sphere.
+   * @returns itself, i.e. the modified BoundingVolume.
+   */
+  transform(transform: readonly number[]): this {
+    this.center.transformAsPoint(transform);
+    // TODO - this.halfDiagonal.transformAsVector(transform);
+    this.halfDiagonal.transform(transform);
+    this.minimum.transform(transform);
+    this.maximum.transform(transform);
     return this;
   }
 
   /**
    * Determines which side of a plane a box is located.
    */
-  intersectPlane(plane) {
+  intersectPlane(plane: Plane): INTERSECTION {
     const {halfDiagonal} = this;
     const normal = scratchNormal.from(plane.normal);
     const e =
@@ -82,14 +114,13 @@ export default class AxisAlignedBoundingBox {
     return INTERSECTION.INTERSECTING;
   }
 
-  // Computes the estimated distance from the closest point on a bounding box to a point.
-  distanceTo(point) {
+  /** Computes the estimated distance from the closest point on a bounding box to a point. */
+  distanceTo(point: readonly number[]): number {
     return Math.sqrt(this.distanceSquaredTo(point));
   }
 
-  // Computes the estimated distance squared from the closest point on a bounding box to a point.
-  // A simplified version of OrientedBoundingBox.distanceSquaredTo
-  distanceSquaredTo(point) {
+  /** Computes the estimated distance squared from the closest point on a bounding box to a point. */
+  distanceSquaredTo(point: readonly number[]): number {
     const offset = scratchVector.from(point).subtract(this.center);
     const {halfDiagonal} = this;
 

package/src/lib/bounding-volumes/{bounding-sphere.js → bounding-sphere.ts}

@@ -1,55 +1,60 @@
 // This file is derived from the Cesium math library under Apache 2 license
 // See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
 
-import {Vector3} from '@math.gl/core';
+import {NumericArray, Vector3} from '@math.gl/core';
 import * as mat4 from 'gl-matrix/mat4';
 import {INTERSECTION} from '../../constants';
-
-// import Rectangle from './rectangle';
-
-// const defaultProjection = new GeographicProjection();
-// const fromRectangle2DLowerLeft = new Vector3();
-// const fromRectangle2DUpperRight = new Vector3();
-// const fromRectangle2DSouthwest = new Cartographic();
-// const fromRectangle2DNortheast = new Cartographic();
-
-// const fromRectangle3DScratch = [];
+import {BoundingVolume} from './bounding-volume';
+import Plane from '../plane';
 
 const scratchVector = new Vector3();
 const scratchVector2 = new Vector3();
 
-export default class BoundingSphere {
-  constructor(center = [0, 0, 0], radius = 0.0) {
+/** A BoundingSphere */
+export default class BoundingSphere implements BoundingVolume {
+  center: Vector3;
+  radius: number;
+
+  /** Creates a bounding sphere */
+  constructor(center: readonly number[] = [0, 0, 0], radius: number = 0.0) {
     this.radius = -0;
     this.center = new Vector3();
     this.fromCenterRadius(center, radius);
   }
 
-  fromCenterRadius(center, radius) {
+  /** Sets the bounding sphere from `center` and `radius`. */
+  fromCenterRadius(center: readonly number[], radius: number): this {
     this.center.from(center);
     this.radius = radius;
     return this;
   }
 
-  fromCornerPoints(corner, oppositeCorner) {
+  /**
+   * Computes a bounding sphere from the corner points of an axis-aligned bounding box.  The sphere
+   * tightly and fully encompasses the box.
+   */
+  fromCornerPoints(corner: readonly number[], oppositeCorner: readonly number[]): this {
     oppositeCorner = scratchVector.from(oppositeCorner);
     this.center = new Vector3().from(corner).add(oppositeCorner).scale(0.5);
     this.radius = this.center.distance(oppositeCorner);
     return this;
   }
 
-  equals(right) {
+  /** Compares the provided BoundingSphere component wise */
+  equals(right: BoundingSphere): boolean {
     return (
       this === right ||
       (Boolean(right) && this.center.equals(right.center) && this.radius === right.radius)
     );
   }
 
-  clone() {
+  /** Duplicates a BoundingSphere instance. */
+  clone(): BoundingSphere {
     return new BoundingSphere(this.center, this.radius);
   }
 
-  union(boundingSphere) {
+  /** Computes a bounding sphere that contains both the left and right bounding spheres. */
+  union(boundingSphere: BoundingSphere): BoundingSphere {
     const leftCenter = this.center;
     const leftRadius = this.radius;
     const rightCenter = boundingSphere.center;
@@ -83,35 +88,46 @@ export default class BoundingSphere {
     return this;
   }
 
-  expand(point) {
-    point = scratchVector.from(point);
-    const radius = point.subtract(this.center).magnitude();
+  /** Computes a bounding sphere by enlarging the provided sphere to contain the provided point. */
+  expand(point: readonly number[]): this {
+    const scratchPoint = scratchVector.from(point);
+    const radius = scratchPoint.subtract(this.center).magnitude();
     if (radius > this.radius) {
       this.radius = radius;
     }
     return this;
   }
 
-  transform(transform) {
+  // BoundingVolume interface
+
+  /**
+   * Applies a 4x4 affine transformation matrix to a bounding sphere.
+   * @param sphere The bounding sphere to apply the transformation to.
+   * @param transform The transformation matrix to apply to the bounding sphere.
+   * @returns self.
+   */
+  transform(transform: readonly number[]): this {
     this.center.transform(transform);
     const scale = mat4.getScaling(scratchVector, transform);
     this.radius = Math.max(scale[0], Math.max(scale[1], scale[2])) * this.radius;
     return this;
   }
 
-  // Computes the estimated distance squared from the closest point on a bounding sphere to a point.
-  distanceSquaredTo(point) {
-    point = scratchVector.from(point);
-    const delta = point.subtract(this.center);
-    return delta.lengthSquared() - this.radius * this.radius;
+  /** Computes the estimated distance squared from the closest point on a bounding sphere to a point. */
+  distanceSquaredTo(point: Readonly<NumericArray>): number {
+    const d = this.distanceTo(point);
+    return d * d;
   }
 
-  distanceTo(point) {
-    return Math.sqrt(this.distanceSquaredTo(point));
+  /** Computes the estimated distance from the closest point on a bounding sphere to a point. */
+  distanceTo(point: Readonly<NumericArray>): number {
+    const scratchPoint = scratchVector.from(point);
+    const delta = scratchPoint.subtract(this.center);
+    return Math.max(0, delta.len() - this.radius);
   }
 
-  // Determines which side of a plane a sphere is located.
-  intersectPlane(plane) {
+  /** Determines which side of a plane a sphere is located. */
+  intersectPlane(plane: Plane): INTERSECTION {
     const center = this.center;
     const radius = this.radius;
     const normal = plane.normal;

package/src/lib/bounding-volumes/{bounding-volume.d.ts → bounding-volume.ts}

@@ -1,4 +1,4 @@
-import {INTERSECTION_ENUM} from '../../constants';
+import {INTERSECTION} from '../../constants';
 import Plane from '../plane';
 
 /**
@@ -12,12 +12,12 @@ export interface BoundingVolume {
    * @param transform The transformation matrix to apply to the bounding sphere.
    * @returns itself, i.e. the modified BoundingVolume.
    */
-   transform(transform: readonly number[]): this;
+  transform(transform: readonly number[]): this;
 
-   /** Computes the estimated distance squared from the closest point on a bounding sphere to a point. */
-   distanceSquaredTo(point: readonly number[]): number;
-   /** Computes the estimated distance from the closest point on a bounding sphere to a point. */
-   distanceTo(point: readonly number[]): number;
+  /** Computes the estimated distance squared from the closest point on a bounding sphere to a point. */
+  distanceSquaredTo(point: readonly number[]): number;
+  /** Computes the estimated distance from the closest point on a bounding sphere to a point. */
+  distanceTo(point: readonly number[]): number;
 
   /**
    * Determines which side of a plane the oriented bounding box is located.
@@ -28,5 +28,5 @@ export interface BoundingVolume {
    *  - `INTERSECTION.OUTSIDE` if the entire box is on the opposite side.
    *  - `INTERSECTION.INTERSECTING` if the box intersects the plane.
    */
-  intersectPlane(plane: Plane): INTERSECTION_ENUM;
+  intersectPlane(plane: Plane): INTERSECTION;
 }