@math.gl/geometry 5.0.0-alpha.2 → 5.0.0-alpha.20

package/src/culling/lib/perspective-off-center-frustum.ts

@@ -0,0 +1,381 @@
+// 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 for the retained Cesium notice and Apache-2.0 terms.
+
+// Note: This class is still an experimental export, mainly used by other test cases
+// - It has not been fully adapted to math.gl conventions
+// - Documentation has not been ported
+
+import {Vector3, Vector2, Matrix4, assert, NumericArray} from '@math.gl/core';
+import {CullingVolume} from './culling-volume';
+import {Plane} from './plane';
+
+const scratchPlaneUpVector = new Vector3();
+const scratchPlaneRightVector = new Vector3();
+const scratchPlaneNearCenter = new Vector3();
+const scratchPlaneFarCenter = new Vector3();
+const scratchPlaneNormal = new Vector3();
+
+type PerspectiveOffCenterFrustumOptions = {
+  left?: number;
+  right?: number;
+  top?: number;
+  bottom?: number;
+  near?: number;
+  far?: number;
+};
+
+export class PerspectiveOffCenterFrustum {
+  /**
+   * Defines the left clipping plane.
+   * @type {Number}
+   * @default undefined
+   */
+  left?: number;
+  private _left?: number;
+  /**
+   * Defines the right clipping plane.
+   * @type {Number}
+   * @default undefined
+   */
+  right?: number;
+  private _right?: number;
+  /**
+   * Defines the top clipping plane.
+   * @type {Number}
+   * @default undefined
+   */
+  top?: number;
+  private _top?: number;
+  /**
+   * Defines the bottom clipping plane.
+   * @type {Number}
+   * @default undefined
+   */
+  bottom?: number;
+  private _bottom?: number;
+  /**
+   * The distance of the near plane.
+   * @type {Number}
+   * @default 1.0
+   */
+  near: number;
+  private _near: number;
+  /**
+   * The distance of the far plane.
+   * @type {Number}
+   * @default 500000000.0
+   */
+  far: number;
+  private _far: number;
+
+  private _cullingVolume = new CullingVolume([
+    new Plane(),
+    new Plane(),
+    new Plane(),
+    new Plane(),
+    new Plane(),
+    new Plane()
+  ]);
+  private _perspectiveMatrix = new Matrix4();
+  private _infinitePerspective = new Matrix4();
+
+  /**
+   * The viewing frustum is defined by 6 planes.
+   * Each plane is represented by a {@link Vector4} object, where the x, y, and z components
+   * define the unit vector normal to the plane, and the w component is the distance of the
+   * plane from the origin/camera position.
+   *
+   * @alias PerspectiveOffCenterFrustum
+   *
+   * @example
+   * const frustum = new PerspectiveOffCenterFrustum({
+   *     left : -1.0,
+   *     right : 1.0,
+   *     top : 1.0,
+   *     bottom : -1.0,
+   *     near : 1.0,
+   *     far : 100.0
+   * });
+   *
+   * @see PerspectiveFrustum
+   */
+  constructor(options: PerspectiveOffCenterFrustumOptions = {}) {
+    const {near = 1.0, far = 500000000.0} = options;
+
+    this.left = options.left;
+    this._left = undefined;
+
+    this.right = options.right;
+    this._right = undefined;
+
+    this.top = options.top;
+    this._top = undefined;
+
+    this.bottom = options.bottom;
+    this._bottom = undefined;
+
+    this.near = near;
+    this._near = near;
+
+    this.far = far;
+    this._far = far;
+  }
+
+  /**
+   * Returns a duplicate of a PerspectiveOffCenterFrustum instance.
+   * @returns {PerspectiveOffCenterFrustum} A new PerspectiveFrustum instance.
+   * */
+  clone(): PerspectiveOffCenterFrustum {
+    return new PerspectiveOffCenterFrustum({
+      right: this.right,
+      left: this.left,
+      top: this.top,
+      bottom: this.bottom,
+      near: this.near,
+      far: this.far
+    });
+  }
+
+  /**
+   * Compares the provided PerspectiveOffCenterFrustum componentwise and returns
+   * <code>true</code> if they are equal, <code>false</code> otherwise.
+   *
+   * @returns {Boolean} <code>true</code> if they are equal, <code>false</code> otherwise.
+   */
+  equals(other: PerspectiveOffCenterFrustum): boolean {
+    return (
+      other &&
+      other instanceof PerspectiveOffCenterFrustum &&
+      this.right === other.right &&
+      this.left === other.left &&
+      this.top === other.top &&
+      this.bottom === other.bottom &&
+      this.near === other.near &&
+      this.far === other.far
+    );
+  }
+
+  /**
+   * Gets the perspective projection matrix computed from the view frustum.
+   * @memberof PerspectiveOffCenterFrustum.prototype
+   * @type {Matrix4}
+   *
+   * @see PerspectiveOffCenterFrustum#infiniteProjectionMatrix
+   */
+  get projectionMatrix(): Matrix4 {
+    this._update();
+    return this._perspectiveMatrix;
+  }
+
+  /**
+   * Gets the perspective projection matrix computed from the view frustum with an infinite far plane.
+   * @memberof PerspectiveOffCenterFrustum.prototype
+   * @type {Matrix4}
+   *
+   * @see PerspectiveOffCenterFrustum#projectionMatrix
+   */
+  get infiniteProjectionMatrix(): Matrix4 {
+    this._update();
+    return this._infinitePerspective;
+  }
+
+  /**
+   * Creates a culling volume for this frustum.
+   * @returns {CullingVolume} A culling volume at the given position and orientation.
+   *
+   * @example
+   * // Check if a bounding volume intersects the frustum.
+   * const cullingVolume = frustum.computeCullingVolume(cameraPosition, cameraDirection, cameraUp);
+   * const intersect = cullingVolume.computeVisibility(boundingVolume);
+   */
+  // eslint-disable-next-line complexity, max-statements
+  computeCullingVolume(
+    /** A Vector3 defines the eye position. */
+    position: Readonly<NumericArray>,
+    /** A Vector3 defines the view direction. */
+    direction: Readonly<NumericArray>,
+    /** A Vector3 defines the up direction. */
+    up: Readonly<NumericArray>
+  ): CullingVolume {
+    assert(position, 'position is required.');
+    assert(direction, 'direction is required.');
+    assert(up, 'up is required.');
+
+    const planes = this._cullingVolume.planes;
+
+    up = scratchPlaneUpVector.copy(up).normalize();
+    const right = scratchPlaneRightVector.copy(direction).cross(up).normalize();
+
+    const nearCenter = scratchPlaneNearCenter
+      .copy(direction)
+      .multiplyByScalar(this.near)
+      .add(position);
+
+    const farCenter = scratchPlaneFarCenter
+      .copy(direction)
+      .multiplyByScalar(this.far)
+      .add(position);
+
+    let normal = scratchPlaneNormal;
+
+    // Left plane computation
+    normal.copy(right).multiplyByScalar(this.left).add(nearCenter).subtract(position).cross(up);
+
+    planes[0].fromPointNormal(position, normal);
+
+    // Right plane computation
+    normal
+      .copy(right)
+      .multiplyByScalar(this.right)
+      .add(nearCenter)
+      .subtract(position)
+      .cross(up)
+      .negate();
+
+    planes[1].fromPointNormal(position, normal);
+
+    // Bottom plane computation
+    normal
+      .copy(up)
+      .multiplyByScalar(this.bottom)
+      .add(nearCenter)
+      .subtract(position)
+      .cross(right)
+      .negate();
+
+    planes[2].fromPointNormal(position, normal);
+
+    // Top plane computation
+    normal.copy(up).multiplyByScalar(this.top).add(nearCenter).subtract(position).cross(right);
+
+    planes[3].fromPointNormal(position, normal);
+
+    normal = new Vector3().copy(direction);
+
+    // Near plane computation
+    planes[4].fromPointNormal(nearCenter, normal);
+
+    // Far plane computation
+    normal.negate();
+
+    planes[5].fromPointNormal(farCenter, normal);
+
+    return this._cullingVolume;
+  }
+
+  /**
+   * Returns the pixel's width and height in meters.
+   *
+   * @returns {Vector2} The modified result parameter or a new instance of {@link Vector2} with the pixel's width and height in the x and y properties, respectively.
+   *
+   * @exception {DeveloperError} drawingBufferWidth must be greater than zero.
+   * @exception {DeveloperError} drawingBufferHeight must be greater than zero.
+   *
+   * @example
+   * // Example 1
+   * // Get the width and height of a pixel.
+   * const pixelSize = camera.frustum.getPixelDimensions(scene.drawingBufferWidth, scene.drawingBufferHeight, 1.0, new Vector2());
+   *
+   * @example
+   * // Example 2
+   * // Get the width and height of a pixel if the near plane was set to 'distance'.
+   * // For example, get the size of a pixel of an image on a billboard.
+   * const position = camera.position;
+   * const direction = camera.direction;
+   * const toCenter = Vector3.subtract(primitive.boundingVolume.center, position, new Vector3());      // vector from camera to a primitive
+   * const toCenterProj = Vector3.multiplyByScalar(direction, Vector3.dot(direction, toCenter), new Vector3()); // project vector onto camera direction vector
+   * const distance = Vector3.magnitude(toCenterProj);
+   * const pixelSize = camera.frustum.getPixelDimensions(scene.drawingBufferWidth, scene.drawingBufferHeight, distance, new Vector2());
+   */
+  getPixelDimensions(
+    /** The width of the drawing buffer. */
+    drawingBufferWidth: number,
+    /** The height of the drawing buffer. */
+    drawingBufferHeight: number,
+    /** The distance to the near plane in meters. */
+    distance: number,
+    /** The object onto which to store the result. */
+    result: Vector2
+  ): Vector2 {
+    this._update();
+
+    assert(Number.isFinite(drawingBufferWidth) && Number.isFinite(drawingBufferHeight));
+    // 'Both drawingBufferWidth and drawingBufferHeight are required.'
+    assert(drawingBufferWidth > 0);
+    // 'drawingBufferWidth must be greater than zero.'
+    assert(drawingBufferHeight > 0);
+    // 'drawingBufferHeight must be greater than zero.'
+    assert(distance > 0);
+    // 'distance is required.');
+    assert(result);
+    // 'A result object is required.');
+
+    const inverseNear = 1.0 / this.near;
+    let tanTheta = this.top * inverseNear;
+    const pixelHeight = (2.0 * distance * tanTheta) / drawingBufferHeight;
+    tanTheta = this.right * inverseNear;
+    const pixelWidth = (2.0 * distance * tanTheta) / drawingBufferWidth;
+
+    result.x = pixelWidth;
+    result.y = pixelHeight;
+    return result;
+  }
+
+  // eslint-disable-next-line complexity, max-statements
+  private _update() {
+    assert(
+      Number.isFinite(this.right) &&
+        Number.isFinite(this.left) &&
+        Number.isFinite(this.top) &&
+        Number.isFinite(this.bottom) &&
+        Number.isFinite(this.near) &&
+        Number.isFinite(this.far)
+    );
+    // throw new DeveloperError('right, left, top, bottom, near, or far parameters are not set.');
+
+    const {top, bottom, right, left, near, far} = this;
+
+    if (
+      top !== this._top ||
+      bottom !== this._bottom ||
+      left !== this._left ||
+      right !== this._right ||
+      near !== this._near ||
+      far !== this._far
+    ) {
+      assert(
+        this.near > 0 && this.near < this.far,
+        'near must be greater than zero and less than far.'
+      );
+
+      this._left = left;
+      this._right = right;
+      this._top = top;
+      this._bottom = bottom;
+      this._near = near;
+      this._far = far;
+      this._perspectiveMatrix = new Matrix4().frustum({
+        left,
+        right,
+        bottom,
+        top,
+        near,
+        far
+      });
+      this._infinitePerspective = new Matrix4().frustum({
+        left,
+        right,
+        bottom,
+        top,
+        near,
+        far: Infinity
+      });
+    }
+  }
+}

package/src/culling/lib/plane.ts

@@ -0,0 +1,118 @@
+// 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 for the retained Cesium notice and Apache-2.0 terms.
+
+/* eslint-disable */
+import {Vector3, equals, assert, NumericArray, _MathUtils} from '@math.gl/core';
+import {Ray} from './ray';
+
+const scratchPosition = new Vector3();
+const scratchNormal = new Vector3();
+
+// A plane in Hessian Normal Form
+export class Plane {
+  readonly normal: Vector3;
+  distance: number;
+
+  constructor(normal: Readonly<NumericArray> = [0, 0, 1], distance: number = 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: Readonly<NumericArray>, distance: number): this {
+    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: Readonly<NumericArray>, normal: Readonly<NumericArray>): this {
+    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: number, b: number, c: number, d: number): this {
+    this.normal.set(a, b, c);
+    assert(equals(this.normal.len(), 1));
+    this.distance = d;
+    return this;
+  }
+
+  /** Duplicates a Plane instance. */
+  clone(): Plane {
+    return new Plane(this.normal, this.distance);
+  }
+
+  /** Compares the provided Planes by normal and distance */
+  equals(right: Plane): boolean {
+    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: Readonly<NumericArray>): number {
+    return this.normal.dot(point) + this.distance;
+  }
+
+  /** Transforms the plane by the given transformation matrix. */
+  transform(matrix4: Readonly<NumericArray>): this {
+    const normal = scratchNormal.copy(this.normal).transformAsVector(matrix4).normalize();
+    const point = this.normal.scale(-this.distance).transform(matrix4);
+    return this.fromPointNormal(point, normal);
+  }
+
+  /** Projects a point onto the plane. */
+  projectPointOntoPlane(point: Readonly<NumericArray>, result: Vector3): Vector3;
+  projectPointOntoPlane(
+    point: Readonly<NumericArray>,
+    result?: readonly number[]
+  ): readonly number[];
+
+  projectPointOntoPlane(point: Readonly<NumericArray>, result = [0, 0, 0]) {
+    const scratchPoint = scratchPosition.from(point);
+    // projectedPoint = point - (normal.point + scale) * normal
+    const pointDistance = this.getPointDistance(scratchPoint);
+    const scaledNormal = scratchNormal.copy(this.normal).scale(pointDistance);
+
+    return scratchPoint.subtract(scaledNormal).to(result);
+  }
+
+  /**
+   * Computes the intersection of a ray and this plane.
+   *
+   * @param {Ray} ray The ray.
+   * @param {Vector3} [result] The object onto which to store the result.
+   * @returns {Vector3} The intersection point or undefined if there is no intersection.
+   */
+  intersectWithRay(ray: Ray, result: Vector3 = new Vector3()): Vector3 | undefined {
+    const origin = ray.origin;
+    const direction = ray.direction;
+    const normal = this.normal;
+    const denominator = normal.dot(direction);
+
+    if (Math.abs(denominator) < _MathUtils.EPSILON15) {
+      return undefined;
+    }
+
+    const t = (-this.distance - normal.dot(origin)) / denominator;
+
+    if (t < 0) {
+      return undefined;
+    }
+
+    return result.copy(direction).multiplyByScalar(t).add(origin);
+  }
+}

package/src/culling/lib/ray.ts

@@ -0,0 +1,33 @@
+// 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 library under Apache 2 license
+// See ../../../LICENSE for the retained Cesium notice and Apache-2.0 terms.
+
+import {Vector3} from '@math.gl/core';
+
+/* Represents a ray that extends infinitely from the provided origin in the provided direction. */
+export class Ray {
+  origin: Vector3;
+  direction: Vector3;
+
+  /**
+   * Creates a new ray that extends infinitely from the provided origin in the provided direction.
+   *
+   * @param [origin=Vector3] The origin of the ray.
+   * @param [direction=Vector3] The direction of the ray.
+   */
+  constructor(origin?: Vector3, direction?: Vector3) {
+    if (origin) origin = origin.clone();
+    else origin = new Vector3();
+
+    if (direction) direction = direction.clone().normalize();
+    else direction = new Vector3();
+
+    this.origin = origin;
+    this.direction = direction;
+  }
+}

package/src/culling/lib/shapes/box-shape.ts

@@ -0,0 +1,78 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {ImplicitShapeBase, type ImplicitShape, type LocalRayIntersection} from './implicit-shape';
+
+const EPSILON = 1e-6;
+
+export type BoxShapeProps = {size?: readonly [number, number, number]; matrix?: readonly number[]};
+
+/** Analytic glTF box shape. */
+export class BoxShape extends ImplicitShapeBase {
+  readonly type = 'box' as const;
+  readonly size: readonly [number, number, number];
+  private readonly halfSize: readonly [number, number, number];
+
+  constructor(props: BoxShapeProps = {}) {
+    super(props.matrix);
+    this.size = props.size ? [...props.size] : [1, 1, 1];
+    if (this.size.some(value => !Number.isFinite(value) || value <= 0))
+      throw new Error('Box size values must be greater than zero');
+    this.halfSize = [this.size[0] / 2, this.size[1] / 2, this.size[2] / 2];
+  }
+
+  clone(): BoxShape {
+    return new BoxShape({size: this.size, matrix: this.matrix});
+  }
+  override equals(shape: ImplicitShape): boolean {
+    return (
+      shape instanceof BoxShape &&
+      super.equals(shape) &&
+      this.size.every((value, i) => value === shape.size[i])
+    );
+  }
+  containsLocalPoint(point: readonly number[]): boolean {
+    return point.every((value, i) => Math.abs(value) <= this.halfSize[i] + EPSILON);
+  }
+  distanceToLocalPoint(point: readonly number[]): number {
+    return Math.hypot(...point.map((value, i) => Math.max(0, Math.abs(value) - this.halfSize[i])));
+  }
+  supportLocal(direction: readonly number[]): readonly number[] {
+    return direction.map((value, i) => (value < 0 ? -this.halfSize[i] : this.halfSize[i]));
+  }
+  intersectLocalRay(
+    origin: readonly number[],
+    direction: readonly number[]
+  ): LocalRayIntersection | undefined {
+    let near = -Infinity;
+    let far = Infinity;
+    let nearAxis = 0;
+    let farAxis = 0;
+    for (let axis = 0; axis < 3; axis++) {
+      if (Math.abs(direction[axis]) < 1e-15) {
+        if (Math.abs(origin[axis]) > this.halfSize[axis]) return undefined;
+        continue;
+      }
+      let t1 = (-this.halfSize[axis] - origin[axis]) / direction[axis];
+      let t2 = (this.halfSize[axis] - origin[axis]) / direction[axis];
+      if (t1 > t2) [t1, t2] = [t2, t1];
+      if (t1 > near) {
+        near = t1;
+        nearAxis = axis;
+      }
+      if (t2 < far) {
+        far = t2;
+        farAxis = axis;
+      }
+      if (near > far) return undefined;
+    }
+    const distance = near >= 0 ? near : far;
+    if (distance < 0 || !Number.isFinite(distance)) return undefined;
+    const axis = near >= 0 ? nearAxis : farAxis;
+    const pointCoordinate = origin[axis] + distance * direction[axis];
+    const normal = [0, 0, 0];
+    normal[axis] = pointCoordinate < 0 ? -1 : 1;
+    return {distance, normal};
+  }
+}