@math.gl/geometry 5.0.0-alpha.18 → 5.0.0-alpha.19

package/src/culling/index.ts

@@ -0,0 +1,40 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export type {CullingResult} from './constants';
+
+export {AxisAlignedBoundingBox} from './lib/bounding-volumes/axis-aligned-bounding-box';
+export {BoundingSphere} from './lib/bounding-volumes/bounding-sphere';
+export {OrientedBoundingBox} from './lib/bounding-volumes/oriented-bounding-box';
+export {CullingVolume} from './lib/culling-volume';
+export {Plane} from './lib/plane';
+export {Ray} from './lib/ray';
+
+export type {ImplicitShape, RayIntersection} from './lib/shapes/implicit-shape';
+export {BoxShape} from './lib/shapes/box-shape';
+export type {BoxShapeProps} from './lib/shapes/box-shape';
+export {CapsuleShape} from './lib/shapes/capsule-shape';
+export type {CapsuleShapeProps} from './lib/shapes/capsule-shape';
+export {CylinderShape} from './lib/shapes/cylinder-shape';
+export type {CylinderShapeProps} from './lib/shapes/cylinder-shape';
+export {PlaneShape} from './lib/shapes/plane-shape';
+export type {PlaneShapeProps} from './lib/shapes/plane-shape';
+export {SphereShape} from './lib/shapes/sphere-shape';
+export type {SphereShapeProps} from './lib/shapes/sphere-shape';
+
+export {PerspectiveOffCenterFrustum as _PerspectiveOffCenterFrustum} from './lib/perspective-off-center-frustum';
+export {PerspectiveFrustum as _PerspectiveFrustum} from './lib/perspective-frustum';
+
+export {makeBoundingSphereFromPoints} from './lib/algorithms/bounding-sphere-from-points';
+export {
+  makeAxisAlignedBoundingBoxFromPoints,
+  makeOrientedBoundingBoxFromPoints
+} from './lib/algorithms/bounding-box-from-points';
+export {computeEigenDecomposition} from './lib/algorithms/compute-eigen-decomposition';
+
+export {intersectRayBounds, intersectRayTriangle, getClosestPointOnTriangle} from './queries';
+export type {QueryPoint, TriangleRayHit} from './queries';
+
+export {intersectOrientedBoxes2D} from './oriented-box-2d';
+export type {OrientedBox2D} from './oriented-box-2d';

package/src/culling/lib/algorithms/bounding-box-from-points.ts

@@ -0,0 +1,174 @@
+// math.gl
+// SPDX-License-Identifier: MIT AND Apache-2.0
+// SPDX-FileCopyrightText: Copyright 2011-2018 CesiumJS Contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Derived from Cesium. See the repository LICENSE for upstream attribution and Apache-2.0 terms.
+
+// 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, Matrix3} from '@math.gl/core';
+import {computeEigenDecomposition} from './compute-eigen-decomposition';
+import {OrientedBoundingBox} from '../bounding-volumes/oriented-bounding-box';
+import {AxisAlignedBoundingBox} from '../bounding-volumes/axis-aligned-bounding-box';
+
+const scratchVector2 = new Vector3();
+
+const scratchVector3 = new Vector3();
+
+const scratchVector4 = new Vector3();
+
+const scratchVector5 = new Vector3();
+
+const scratchVector6 = new Vector3();
+
+const scratchCovarianceResult = new Matrix3();
+
+const scratchEigenResult = {
+  diagonal: new Matrix3(),
+  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: 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();
+    return result;
+  }
+
+  const length = positions.length;
+  const meanPoint = new Vector3(0, 0, 0);
+  for (const position of positions) {
+    meanPoint.add(position);
+  }
+  const invLength = 1.0 / length;
+  meanPoint.multiplyByScalar(invLength);
+
+  let exx = 0.0;
+  let exy = 0.0;
+  let exz = 0.0;
+  let eyy = 0.0;
+  let eyz = 0.0;
+  let ezz = 0.0;
+
+  for (const position of positions) {
+    const p = scratchVector2.copy(position).subtract(meanPoint);
+    exx += p.x * p.x;
+    exy += p.x * p.y;
+    exz += p.x * p.z;
+    eyy += p.y * p.y;
+    eyz += p.y * p.z;
+    ezz += p.z * p.z;
+  }
+
+  exx *= invLength;
+  exy *= invLength;
+  exz *= invLength;
+  eyy *= invLength;
+  eyz *= invLength;
+  ezz *= invLength;
+
+  const covarianceMatrix = scratchCovarianceResult;
+  covarianceMatrix[0] = exx;
+  covarianceMatrix[1] = exy;
+  covarianceMatrix[2] = exz;
+  covarianceMatrix[3] = exy;
+  covarianceMatrix[4] = eyy;
+  covarianceMatrix[5] = eyz;
+  covarianceMatrix[6] = exz;
+  covarianceMatrix[7] = eyz;
+  covarianceMatrix[8] = ezz;
+
+  const {unitary} = computeEigenDecomposition(covarianceMatrix, scratchEigenResult);
+  const rotation = result.halfAxes.copy(unitary);
+
+  let v1 = rotation.getColumn(0, scratchVector4);
+  let v2 = rotation.getColumn(1, scratchVector5);
+  let v3 = rotation.getColumn(2, scratchVector6);
+
+  let u1 = -Number.MAX_VALUE;
+  let u2 = -Number.MAX_VALUE;
+  let u3 = -Number.MAX_VALUE;
+  let l1 = Number.MAX_VALUE;
+  let l2 = Number.MAX_VALUE;
+  let l3 = Number.MAX_VALUE;
+
+  for (const position of positions) {
+    scratchVector2.copy(position);
+
+    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));
+  v2 = v2.multiplyByScalar(0.5 * (l2 + u2));
+  v3 = v3.multiplyByScalar(0.5 * (l3 + u3));
+
+  result.center.copy(v1).add(v2).add(v3);
+
+  const scale = scratchVector3.set(u1 - l1, u2 - l2, u3 - l3).multiplyByScalar(0.5);
+  const scaleMatrix = new Matrix3([scale[0], 0, 0, 0, scale[1], 0, 0, 0, scale[2]]);
+  result.halfAxes.multiplyRight(scaleMatrix);
+
+  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: readonly number[][],
+  result: AxisAlignedBoundingBox = new AxisAlignedBoundingBox()
+): AxisAlignedBoundingBox {
+  if (!positions || positions.length === 0) {
+    result.minimum.set(0, 0, 0);
+    result.maximum.set(0, 0, 0);
+    result.center.set(0, 0, 0);
+    result.halfDiagonal.set(0, 0, 0);
+    return result;
+  }
+
+  let minimumX = positions[0][0];
+  let minimumY = positions[0][1];
+  let minimumZ = positions[0][2];
+
+  let maximumX = positions[0][0];
+  let maximumY = positions[0][1];
+  let maximumZ = positions[0][2];
+
+  for (const p of positions) {
+    const x = p[0];
+    const y = p[1];
+    const z = p[2];
+
+    minimumX = Math.min(x, minimumX);
+    maximumX = Math.max(x, maximumX);
+    minimumY = Math.min(y, minimumY);
+    maximumY = Math.max(y, maximumY);
+    minimumZ = Math.min(z, minimumZ);
+    maximumZ = Math.max(z, maximumZ);
+  }
+
+  result.minimum.set(minimumX, minimumY, minimumZ);
+  result.maximum.set(maximumX, maximumY, maximumZ);
+  result.center.copy(result.minimum).add(result.maximum).scale(0.5);
+  result.halfDiagonal.copy(result.maximum).subtract(result.center);
+
+  return result;
+}

package/src/culling/lib/algorithms/bounding-sphere-from-points.ts

@@ -0,0 +1,175 @@
+// math.gl
+// SPDX-License-Identifier: MIT AND Apache-2.0
+// SPDX-FileCopyrightText: Copyright 2011-2018 CesiumJS Contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Derived from Cesium. See the repository LICENSE for upstream attribution and Apache-2.0 terms.
+
+// 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 {BoundingSphere} from '../bounding-volumes/bounding-sphere';
+
+/* eslint-disable */
+const fromPointsXMin = new Vector3();
+const fromPointsYMin = new Vector3();
+const fromPointsZMin = new Vector3();
+const fromPointsXMax = new Vector3();
+const fromPointsYMax = new Vector3();
+const fromPointsZMax = new Vector3();
+const fromPointsCurrentPos = new Vector3();
+const fromPointsScratch = new Vector3();
+const fromPointsRitterCenter = new Vector3();
+const fromPointsMinBoxPt = new Vector3();
+const fromPointsMaxBoxPt = new Vector3();
+const fromPointsNaiveCenterScratch = new Vector3();
+// const volumeConstant = (4.0 / 3.0) * Math.PI;
+
+/**
+ * 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 function makeBoundingSphereFromPoints(
+  positions: number[][],
+  result: BoundingSphere = new BoundingSphere()
+): BoundingSphere {
+  if (!positions || positions.length === 0) {
+    return result.fromCenterRadius([0, 0, 0], 0);
+  }
+
+  const currentPos = fromPointsCurrentPos.copy(positions[0]);
+
+  const xMin = fromPointsXMin.copy(currentPos);
+  const yMin = fromPointsYMin.copy(currentPos);
+  const zMin = fromPointsZMin.copy(currentPos);
+
+  const xMax = fromPointsXMax.copy(currentPos);
+  const yMax = fromPointsYMax.copy(currentPos);
+  const zMax = fromPointsZMax.copy(currentPos);
+
+  for (const position of positions) {
+    currentPos.copy(position);
+
+    const x = currentPos.x;
+    const y = currentPos.y;
+    const z = currentPos.z;
+
+    // Store points containing the the smallest and largest components
+    if (x < xMin.x) {
+      xMin.copy(currentPos);
+    }
+
+    if (x > xMax.x) {
+      xMax.copy(currentPos);
+    }
+
+    if (y < yMin.y) {
+      yMin.copy(currentPos);
+    }
+
+    if (y > yMax.y) {
+      yMax.copy(currentPos);
+    }
+
+    if (z < zMin.z) {
+      zMin.copy(currentPos);
+    }
+
+    if (z > zMax.z) {
+      zMax.copy(currentPos);
+    }
+  }
+
+  // Compute x-, y-, and z-spans (Squared distances b/n each component's min. and max.).
+  const xSpan = fromPointsScratch.copy(xMax).subtract(xMin).magnitudeSquared();
+  const ySpan = fromPointsScratch.copy(yMax).subtract(yMin).magnitudeSquared();
+  const zSpan = fromPointsScratch.copy(zMax).subtract(zMin).magnitudeSquared();
+
+  // Set the diameter endpoints to the largest span.
+  let diameter1 = xMin;
+  let diameter2 = xMax;
+  let maxSpan = xSpan;
+  if (ySpan > maxSpan) {
+    maxSpan = ySpan;
+    diameter1 = yMin;
+    diameter2 = yMax;
+  }
+  if (zSpan > maxSpan) {
+    maxSpan = zSpan;
+    diameter1 = zMin;
+    diameter2 = zMax;
+  }
+
+  // Calculate the center of the initial sphere found by Ritter's algorithm
+  const ritterCenter = fromPointsRitterCenter;
+  ritterCenter.x = (diameter1.x + diameter2.x) * 0.5;
+  ritterCenter.y = (diameter1.y + diameter2.y) * 0.5;
+  ritterCenter.z = (diameter1.z + diameter2.z) * 0.5;
+
+  // Calculate the radius of the initial sphere found by Ritter's algorithm
+  let radiusSquared = fromPointsScratch.copy(diameter2).subtract(ritterCenter).magnitudeSquared();
+  let ritterRadius = Math.sqrt(radiusSquared);
+
+  // Find the center of the sphere found using the Naive method.
+  const minBoxPt = fromPointsMinBoxPt;
+  minBoxPt.x = xMin.x;
+  minBoxPt.y = yMin.y;
+  minBoxPt.z = zMin.z;
+
+  const maxBoxPt = fromPointsMaxBoxPt;
+  maxBoxPt.x = xMax.x;
+  maxBoxPt.y = yMax.y;
+  maxBoxPt.z = zMax.z;
+
+  const naiveCenter = fromPointsNaiveCenterScratch
+    .copy(minBoxPt)
+    .add(maxBoxPt)
+    .multiplyByScalar(0.5);
+
+  // Begin 2nd pass to find naive radius and modify the ritter sphere.
+  let naiveRadius = 0;
+  for (const position of positions) {
+    currentPos.copy(position);
+
+    // Find the furthest point from the naive center to calculate the naive radius.
+    const r = fromPointsScratch.copy(currentPos).subtract(naiveCenter).magnitude();
+    if (r > naiveRadius) {
+      naiveRadius = r;
+    }
+
+    // Make adjustments to the Ritter Sphere to include all points.
+    const oldCenterToPointSquared = fromPointsScratch
+      .copy(currentPos)
+      .subtract(ritterCenter)
+      .magnitudeSquared();
+
+    if (oldCenterToPointSquared > radiusSquared) {
+      const oldCenterToPoint = Math.sqrt(oldCenterToPointSquared);
+      // Calculate new radius to include the point that lies outside
+      ritterRadius = (ritterRadius + oldCenterToPoint) * 0.5;
+      radiusSquared = ritterRadius * ritterRadius;
+      // Calculate center of new Ritter sphere
+      const oldToNew = oldCenterToPoint - ritterRadius;
+      ritterCenter.x = (ritterRadius * ritterCenter.x + oldToNew * currentPos.x) / oldCenterToPoint;
+      ritterCenter.y = (ritterRadius * ritterCenter.y + oldToNew * currentPos.y) / oldCenterToPoint;
+      ritterCenter.z = (ritterRadius * ritterCenter.z + oldToNew * currentPos.z) / oldCenterToPoint;
+    }
+  }
+
+  if (ritterRadius < naiveRadius) {
+    ritterCenter.to(result.center);
+    result.radius = ritterRadius;
+  } else {
+    naiveCenter.to(result.center);
+    result.radius = naiveRadius;
+  }
+
+  return result;
+}

package/src/culling/lib/algorithms/compute-eigen-decomposition.ts

@@ -0,0 +1,171 @@
+// math.gl
+// SPDX-License-Identifier: MIT AND Apache-2.0
+// SPDX-FileCopyrightText: Copyright 2011-2018 CesiumJS Contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Derived from Cesium. See the repository LICENSE for upstream attribution and Apache-2.0 terms.
+
+// 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 {Matrix3, _MathUtils} from '@math.gl/core';
+
+const scratchMatrix = new Matrix3();
+const scratchUnitary = new Matrix3();
+const scratchDiagonal = new Matrix3();
+
+const jMatrix = new Matrix3();
+const jMatrixTranspose = new Matrix3();
+
+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 function computeEigenDecomposition(
+  matrix: number[],
+  // @ts-expect-error accept empty object type
+  result: EigenDecomposition = {}
+): EigenDecomposition {
+  const EIGEN_TOLERANCE = _MathUtils.EPSILON20;
+  const EIGEN_MAX_SWEEPS = 10;
+
+  let count = 0;
+  let sweep = 0;
+
+  const unitaryMatrix = scratchUnitary;
+  const diagonalMatrix = scratchDiagonal;
+
+  unitaryMatrix.identity();
+  diagonalMatrix.copy(matrix);
+
+  const epsilon = EIGEN_TOLERANCE * computeFrobeniusNorm(diagonalMatrix);
+
+  while (sweep < EIGEN_MAX_SWEEPS && offDiagonalFrobeniusNorm(diagonalMatrix) > epsilon) {
+    shurDecomposition(diagonalMatrix, jMatrix);
+
+    jMatrixTranspose.copy(jMatrix).transpose();
+
+    diagonalMatrix.multiplyRight(jMatrix);
+    diagonalMatrix.multiplyLeft(jMatrixTranspose);
+    unitaryMatrix.multiplyRight(jMatrix);
+
+    if (++count > 2) {
+      ++sweep;
+      count = 0;
+    }
+  }
+
+  result.unitary = unitaryMatrix.toTarget(result.unitary);
+  result.diagonal = diagonalMatrix.toTarget(result.diagonal);
+
+  return result;
+}
+
+function computeFrobeniusNorm(matrix: Matrix3): number {
+  let norm = 0.0;
+  for (let i = 0; i < 9; ++i) {
+    const temp = matrix[i];
+    norm += temp * temp;
+  }
+  return Math.sqrt(norm);
+}
+
+const rowVal = [1, 0, 0];
+const colVal = [2, 2, 1];
+
+// Computes the "off-diagonal" Frobenius norm.
+// Assumes matrix is symmetric.
+function offDiagonalFrobeniusNorm(matrix: Matrix3): number {
+  let norm = 0.0;
+  for (let i = 0; i < 3; ++i) {
+    const temp = matrix[scratchMatrix.getElementIndex(colVal[i], rowVal[i])];
+    norm += 2.0 * temp * temp;
+  }
+  return Math.sqrt(norm);
+}
+
+// The routine takes a matrix, which is assumed to be symmetric, and
+// finds the largest off-diagonal term, and then creates
+// a matrix (result) which can be used to help reduce it
+//
+// This routine was created based upon Matrix Computations, 3rd ed., by Golub and Van Loan,
+// section 8.4.2 The 2by2 Symmetric Schur Decomposition.
+//
+// eslint-disable-next-line max-statements
+function shurDecomposition(matrix: Matrix3, result: Matrix3): Matrix3 {
+  const tolerance = _MathUtils.EPSILON15;
+
+  let maxDiagonal = 0.0;
+  let rotAxis = 1;
+
+  // find pivot (rotAxis) based on max diagonal of matrix
+  for (let i = 0; i < 3; ++i) {
+    const temp = Math.abs(matrix[scratchMatrix.getElementIndex(colVal[i], rowVal[i])]);
+    if (temp > maxDiagonal) {
+      rotAxis = i;
+      maxDiagonal = temp;
+    }
+  }
+
+  const p = rowVal[rotAxis];
+  const q = colVal[rotAxis];
+
+  let c = 1.0;
+  let s = 0.0;
+
+  if (Math.abs(matrix[scratchMatrix.getElementIndex(q, p)]) > tolerance) {
+    const qq = matrix[scratchMatrix.getElementIndex(q, q)];
+    const pp = matrix[scratchMatrix.getElementIndex(p, p)];
+    const qp = matrix[scratchMatrix.getElementIndex(q, p)];
+
+    const tau = (qq - pp) / 2.0 / qp;
+    let t;
+
+    if (tau < 0.0) {
+      t = -1.0 / (-tau + Math.sqrt(1.0 + tau * tau));
+    } else {
+      t = 1.0 / (tau + Math.sqrt(1.0 + tau * tau));
+    }
+
+    c = 1.0 / Math.sqrt(1.0 + t * t);
+    s = t * c;
+  }
+
+  // Copy into result
+  Matrix3.IDENTITY.to(result);
+  result[scratchMatrix.getElementIndex(p, p)] = result[scratchMatrix.getElementIndex(q, q)] = c;
+  result[scratchMatrix.getElementIndex(q, p)] = s;
+  result[scratchMatrix.getElementIndex(p, q)] = -s;
+
+  return result;
+}