@math.gl/culling 4.2.0-alpha.3 → 4.2.0-alpha.6

package/src/lib/bounding-volumes/bounding-sphere.ts

@@ -7,7 +7,7 @@
 
 import {NumericArray, Vector3, mat4} from '@math.gl/core';
 
-import {INTERSECTION} from '../../constants';
+import type {CullingResult} from '../../constants';
 import {BoundingVolume} from './bounding-volume';
 import {Plane} from '../plane';
 
@@ -131,7 +131,7 @@ export class BoundingSphere implements BoundingVolume {
   }
 
   /** Determines which side of a plane a sphere is located. */
-  intersectPlane(plane: Plane): number {
+  intersectPlane(plane: Plane): CullingResult {
     const center = this.center;
     const radius = this.radius;
     const normal = plane.normal;
@@ -139,13 +139,13 @@ export class BoundingSphere implements BoundingVolume {
 
     // The center point is negative side of the plane normal
     if (distanceToPlane < -radius) {
-      return INTERSECTION.OUTSIDE;
+      return 'outside';
     }
     // The center point is positive side of the plane, but radius extends beyond it; partial overlap
     if (distanceToPlane < radius) {
-      return INTERSECTION.INTERSECTING;
+      return 'intersecting';
     }
     // The center point and radius is positive side of the plane
-    return INTERSECTION.INSIDE;
+    return 'inside';
   }
 }

package/src/lib/bounding-volumes/bounding-volume.ts

@@ -4,6 +4,7 @@
 
 // import {INTERSECTION} from '../../constants';
 import {Plane} from '../plane';
+import type {CullingResult} from '../../constants';
 
 /**
  * Common interface for BoundingVolumes
@@ -28,9 +29,9 @@ export interface BoundingVolume {
    *
    * @param plane The plane to test against.
    * @returns
-   *  - `INTERSECTION.INSIDE` if the entire box is on the side of the plane the normal is pointing.
-   *  - `INTERSECTION.OUTSIDE` if the entire box is on the opposite side.
-   *  - `INTERSECTION.INTERSECTING` if the box intersects the plane.
+   *  - `'inside'` if the entire box is on the side of the plane the normal is pointing.
+   *  - `'outside'` if the entire box is on the opposite side.
+   *  - `'intersecting'` if the box intersects the plane.
    */
-  intersectPlane(plane: Plane): number;
+  intersectPlane(plane: Plane): CullingResult;
 }

package/src/lib/bounding-volumes/oriented-bounding-box.ts

@@ -11,7 +11,7 @@ import {Vector3, Matrix3, Matrix4, Quaternion} from '@math.gl/core';
 import type {BoundingVolume} from './bounding-volume';
 import {BoundingSphere} from './bounding-sphere';
 import {Plane} from '../plane';
-import {INTERSECTION} from '../../constants';
+import type {CullingResult} from '../../constants';
 
 const scratchVector3 = new Vector3();
 const scratchOffset = new Vector3();
@@ -129,7 +129,7 @@ export class OrientedBoundingBox implements BoundingVolume {
   }
 
   /** Determines which side of a plane the oriented bounding box is located. */
-  intersectPlane(plane: Plane): number {
+  intersectPlane(plane: Plane): CullingResult {
     const center = this.center;
     const normal = plane.normal;
     const halfAxes = this.halfAxes;
@@ -159,12 +159,12 @@ export class OrientedBoundingBox implements BoundingVolume {
 
     if (distanceToPlane <= -radEffective) {
       // The entire box is on the negative side of the plane normal
-      return INTERSECTION.OUTSIDE;
+      return 'outside';
     } else if (distanceToPlane >= radEffective) {
       // The entire box is on the positive side of the plane normal
-      return INTERSECTION.INSIDE;
+      return 'inside';
     }
-    return INTERSECTION.INTERSECTING;
+    return 'intersecting';
   }
 
   /** Computes the estimated distance from the closest point on a bounding box to a point. */

package/src/lib/culling-volume.ts

@@ -7,7 +7,7 @@
 
 /* eslint-disable */
 import {Vector3, assert} from '@math.gl/core';
-import {INTERSECTION} from '../constants';
+import type {CullingResult} from '../constants';
 import {Plane} from './plane';
 import type {BoundingVolume} from './bounding-volumes/bounding-volume';
 import type {BoundingSphere} from './bounding-volumes/bounding-sphere';
@@ -93,19 +93,19 @@ export class CullingVolume {
   }
 
   /** Determines whether a bounding volume intersects the culling volume. */
-  computeVisibility(boundingVolume: BoundingVolume): number {
+  computeVisibility(boundingVolume: BoundingVolume): CullingResult {
     // const planes = this.planes;
-    let intersect: number = INTERSECTION.INSIDE;
+    let intersect: CullingResult = 'inside';
     for (const plane of this.planes) {
       const result = boundingVolume.intersectPlane(plane);
       switch (result) {
-        case INTERSECTION.OUTSIDE:
+        case 'outside':
           // We are done
-          return INTERSECTION.OUTSIDE;
+          return 'outside';
 
-        case INTERSECTION.INTERSECTING:
+        case 'intersecting':
           // If no other intersection is outside, return INTERSECTING
-          intersect = INTERSECTION.INTERSECTING;
+          intersect = 'intersecting';
           break;
 
         default:
@@ -149,9 +149,9 @@ export class CullingVolume {
 
       const plane = planes[k];
       const result = boundingVolume.intersectPlane(plane);
-      if (result === INTERSECTION.OUTSIDE) {
+      if (result === 'outside') {
         return CullingVolume.MASK_OUTSIDE;
-      } else if (result === INTERSECTION.INTERSECTING) {
+      } else if (result === 'intersecting') {
         mask |= flag;
       }
     }

package/src/lib/plane.ts

@@ -93,11 +93,9 @@ export class 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 intersections.
+   * @returns {Vector3} The intersection point or undefined if there is no intersection.
    */
-  intersectWithRay(ray: Ray, result?: Vector3): Vector3 {
-    if (!result) result = new Vector3();
-
+  intersectWithRay(ray: Ray, result: Vector3 = new Vector3()): Vector3 | undefined {
     const origin = ray.origin;
     const direction = ray.direction;
     const normal = this.normal;
@@ -113,7 +111,6 @@ export class Plane {
       return undefined;
     }
 
-    result = result.copy(direction).multiplyByScalar(t);
-    return origin.add(result);
+    return result.copy(direction).multiplyByScalar(t).add(origin);
   }
 }

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

@@ -0,0 +1,78 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// 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};
+  }
+}

package/src/lib/shapes/capsule-shape.ts

@@ -0,0 +1,232 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  closestDistanceToCircleArc2D,
+  closestDistanceToSegment2D,
+  ImplicitShapeBase,
+  solveQuadratic,
+  type ImplicitShape,
+  type LocalRayIntersection
+} from './implicit-shape';
+
+const EPSILON = 1e-6;
+
+export type CapsuleShapeProps = {
+  height?: number;
+  radiusBottom?: number;
+  radiusTop?: number;
+  matrix?: readonly number[];
+};
+
+/** Analytic glTF capsule: the convex hull of two spheres on the Y axis. */
+export class CapsuleShape extends ImplicitShapeBase {
+  readonly type = 'capsule' as const;
+  readonly height: number;
+  readonly radiusBottom: number;
+  readonly radiusTop: number;
+
+  constructor(props: CapsuleShapeProps = {}) {
+    super(props.matrix);
+    this.height = props.height ?? 1;
+    this.radiusBottom = props.radiusBottom ?? 0.5;
+    this.radiusTop = props.radiusTop ?? 0.5;
+    if (!Number.isFinite(this.height) || this.height <= 0)
+      throw new Error('Capsule height must be greater than zero');
+    if (![this.radiusBottom, this.radiusTop].every(value => Number.isFinite(value) && value >= 0))
+      throw new Error('Capsule radii must be non-negative');
+    if (this.radiusBottom === 0 && this.radiusTop === 0)
+      throw new Error('At least one capsule radius must be greater than zero');
+  }
+
+  clone(): CapsuleShape {
+    return new CapsuleShape({
+      height: this.height,
+      radiusBottom: this.radiusBottom,
+      radiusTop: this.radiusTop,
+      matrix: this.matrix
+    });
+  }
+  override equals(shape: ImplicitShape): boolean {
+    return (
+      shape instanceof CapsuleShape &&
+      super.equals(shape) &&
+      this.height === shape.height &&
+      this.radiusBottom === shape.radiusBottom &&
+      this.radiusTop === shape.radiusTop
+    );
+  }
+  containsLocalPoint(point: readonly number[]): boolean {
+    const profile = this.getProfile();
+    const radial = Math.hypot(point[0], point[2]);
+    if (profile.sphere)
+      return (
+        Math.hypot(radial, point[1] - profile.sphere.center) <= profile.sphere.radius + EPSILON
+      );
+    if (point[1] < profile.bottom.y)
+      return Math.hypot(radial, point[1] + this.height / 2) <= this.radiusBottom + EPSILON;
+    if (point[1] > profile.top.y)
+      return Math.hypot(radial, point[1] - this.height / 2) <= this.radiusTop + EPSILON;
+    const t = (point[1] - profile.bottom.y) / (profile.top.y - profile.bottom.y);
+    return (
+      radial <= profile.bottom.radius + (profile.top.radius - profile.bottom.radius) * t + EPSILON
+    );
+  }
+  distanceToLocalPoint(point: readonly number[]): number {
+    if (this.containsLocalPoint(point)) return 0;
+    const profile = this.getProfile();
+    const radial = Math.hypot(point[0], point[2]);
+    if (profile.sphere)
+      return Math.max(
+        0,
+        Math.hypot(radial, point[1] - profile.sphere.center) - profile.sphere.radius
+      );
+    const delta = this.radiusTop - this.radiusBottom;
+    const sideNormalY = -delta / this.height;
+    const bottomArc = closestDistanceToCircleArc2D(
+      radial,
+      point[1],
+      -this.height / 2,
+      this.radiusBottom,
+      -1,
+      sideNormalY
+    );
+    const topArc = closestDistanceToCircleArc2D(
+      radial,
+      point[1],
+      this.height / 2,
+      this.radiusTop,
+      sideNormalY,
+      1
+    );
+    const side = closestDistanceToSegment2D(
+      radial,
+      point[1],
+      profile.bottom.radius,
+      profile.bottom.y,
+      profile.top.radius,
+      profile.top.y
+    );
+    return Math.min(bottomArc, topArc, side);
+  }
+  supportLocal(direction: readonly number[]): readonly number[] {
+    const length = Math.hypot(...direction);
+    const unit = length ? direction.map(value => value / length) : [1, 0, 0];
+    const bottom = [
+      unit[0] * this.radiusBottom,
+      -this.height / 2 + unit[1] * this.radiusBottom,
+      unit[2] * this.radiusBottom
+    ];
+    const top = [
+      unit[0] * this.radiusTop,
+      this.height / 2 + unit[1] * this.radiusTop,
+      unit[2] * this.radiusTop
+    ];
+    return dot(top, direction) >= dot(bottom, direction) ? top : bottom;
+  }
+  intersectLocalRay(
+    origin: readonly number[],
+    direction: readonly number[]
+  ): LocalRayIntersection | undefined {
+    const profile = this.getProfile();
+    if (profile.sphere)
+      return intersectSphere(origin, direction, profile.sphere.center, profile.sphere.radius);
+    const candidates: LocalRayIntersection[] = [];
+    const slope = (profile.top.radius - profile.bottom.radius) / (profile.top.y - profile.bottom.y);
+    const intercept = profile.bottom.radius - slope * profile.bottom.y;
+    const radialAtOrigin = intercept + slope * origin[1];
+    const radialAlongRay = slope * direction[1];
+    for (const distance of solveQuadratic(
+      direction[0] ** 2 + direction[2] ** 2 - radialAlongRay ** 2,
+      2 * (origin[0] * direction[0] + origin[2] * direction[2] - radialAtOrigin * radialAlongRay),
+      origin[0] ** 2 + origin[2] ** 2 - radialAtOrigin ** 2
+    )) {
+      const y = origin[1] + distance * direction[1];
+      if (distance >= 0 && y >= profile.bottom.y - EPSILON && y <= profile.top.y + EPSILON) {
+        const x = origin[0] + distance * direction[0];
+        const z = origin[2] + distance * direction[2];
+        const radial = Math.hypot(x, z) || 1;
+        const normal = [x / radial, -slope, z / radial];
+        const length = Math.hypot(...normal);
+        candidates.push({distance, normal: normal.map(value => value / length)});
+      }
+    }
+    for (const bottomHit of intersectSphereRoots(
+      origin,
+      direction,
+      -this.height / 2,
+      this.radiusBottom
+    )) {
+      const y = origin[1] + bottomHit.distance * direction[1];
+      if (y <= profile.bottom.y + EPSILON) candidates.push(bottomHit);
+    }
+    for (const topHit of intersectSphereRoots(origin, direction, this.height / 2, this.radiusTop)) {
+      const y = origin[1] + topHit.distance * direction[1];
+      if (y >= profile.top.y - EPSILON) candidates.push(topHit);
+    }
+    return candidates.sort((a, b) => a.distance - b.distance)[0];
+  }
+
+  private getProfile(): {
+    sphere?: {center: number; radius: number};
+    bottom: {radius: number; y: number};
+    top: {radius: number; y: number};
+  } {
+    const delta = this.radiusTop - this.radiusBottom;
+    if (Math.abs(delta) >= this.height) {
+      const topWins = this.radiusTop >= this.radiusBottom;
+      return {
+        sphere: {
+          center: topWins ? this.height / 2 : -this.height / 2,
+          radius: topWins ? this.radiusTop : this.radiusBottom
+        },
+        bottom: {radius: 0, y: 0},
+        top: {radius: 0, y: 0}
+      };
+    }
+    const sinSlope = delta / this.height;
+    const radialNormal = Math.sqrt(1 - sinSlope * sinSlope);
+    const normalY = -sinSlope;
+    return {
+      bottom: {
+        radius: this.radiusBottom * radialNormal,
+        y: -this.height / 2 + this.radiusBottom * normalY
+      },
+      top: {radius: this.radiusTop * radialNormal, y: this.height / 2 + this.radiusTop * normalY}
+    };
+  }
+}
+
+function intersectSphere(
+  origin: readonly number[],
+  direction: readonly number[],
+  centerY: number,
+  radius: number
+): LocalRayIntersection | undefined {
+  return intersectSphereRoots(origin, direction, centerY, radius)[0];
+}
+
+function intersectSphereRoots(
+  origin: readonly number[],
+  direction: readonly number[],
+  centerY: number,
+  radius: number
+): LocalRayIntersection[] {
+  if (radius === 0) return [];
+  const relative = [origin[0], origin[1] - centerY, origin[2]];
+  return solveQuadratic(
+    dot(direction, direction),
+    2 * dot(relative, direction),
+    dot(relative, relative) - radius * radius
+  )
+    .filter(distance => distance >= 0)
+    .map(distance => ({
+      distance,
+      normal: relative.map((value, i) => (value + distance * direction[i]) / radius)
+    }));
+}
+
+function dot(a: readonly number[], b: readonly number[]): number {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}

package/src/lib/shapes/cylinder-shape.ts

@@ -0,0 +1,133 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  closestDistanceToSegment2D,
+  ImplicitShapeBase,
+  solveQuadratic,
+  type ImplicitShape,
+  type LocalRayIntersection
+} from './implicit-shape';
+
+const EPSILON = 1e-6;
+
+export type CylinderShapeProps = {
+  height?: number;
+  radiusBottom?: number;
+  radiusTop?: number;
+  matrix?: readonly number[];
+};
+
+/** Analytic closed, Y-aligned glTF cylinder shape, including tapered cylinders. */
+export class CylinderShape extends ImplicitShapeBase {
+  readonly type = 'cylinder' as const;
+  readonly height: number;
+  readonly radiusBottom: number;
+  readonly radiusTop: number;
+
+  constructor(props: CylinderShapeProps = {}) {
+    super(props.matrix);
+    this.height = props.height ?? 2;
+    this.radiusBottom = props.radiusBottom ?? 0.5;
+    this.radiusTop = props.radiusTop ?? 0.5;
+    if (!Number.isFinite(this.height) || this.height <= 0)
+      throw new Error('Cylinder height must be greater than zero');
+    if (![this.radiusBottom, this.radiusTop].every(value => Number.isFinite(value) && value >= 0))
+      throw new Error('Cylinder radii must be non-negative');
+    if (this.radiusBottom === 0 && this.radiusTop === 0)
+      throw new Error('At least one cylinder radius must be greater than zero');
+  }
+
+  clone(): CylinderShape {
+    return new CylinderShape({
+      height: this.height,
+      radiusBottom: this.radiusBottom,
+      radiusTop: this.radiusTop,
+      matrix: this.matrix
+    });
+  }
+  override equals(shape: ImplicitShape): boolean {
+    return (
+      shape instanceof CylinderShape &&
+      super.equals(shape) &&
+      this.height === shape.height &&
+      this.radiusBottom === shape.radiusBottom &&
+      this.radiusTop === shape.radiusTop
+    );
+  }
+  containsLocalPoint(point: readonly number[]): boolean {
+    const half = this.height / 2;
+    if (point[1] < -half - EPSILON || point[1] > half + EPSILON) return false;
+    const t = (point[1] + half) / this.height;
+    const radius = this.radiusBottom + (this.radiusTop - this.radiusBottom) * t;
+    return Math.hypot(point[0], point[2]) <= radius + EPSILON;
+  }
+  distanceToLocalPoint(point: readonly number[]): number {
+    if (this.containsLocalPoint(point)) return 0;
+    const radial = Math.hypot(point[0], point[2]);
+    const half = this.height / 2;
+    const side = closestDistanceToSegment2D(
+      radial,
+      point[1],
+      this.radiusBottom,
+      -half,
+      this.radiusTop,
+      half
+    );
+    const bottom = closestDistanceToSegment2D(radial, point[1], 0, -half, this.radiusBottom, -half);
+    const top = closestDistanceToSegment2D(radial, point[1], 0, half, this.radiusTop, half);
+    return Math.min(side, bottom, top);
+  }
+  supportLocal(direction: readonly number[]): readonly number[] {
+    const radialLength = Math.hypot(direction[0], direction[2]);
+    const x = radialLength ? direction[0] / radialLength : 1;
+    const z = radialLength ? direction[2] / radialLength : 0;
+    const half = this.height / 2;
+    const bottomValue = radialLength * this.radiusBottom - direction[1] * half;
+    const topValue = radialLength * this.radiusTop + direction[1] * half;
+    return topValue >= bottomValue
+      ? [x * this.radiusTop, half, z * this.radiusTop]
+      : [x * this.radiusBottom, -half, z * this.radiusBottom];
+  }
+  intersectLocalRay(
+    origin: readonly number[],
+    direction: readonly number[]
+  ): LocalRayIntersection | undefined {
+    const half = this.height / 2;
+    const slope = (this.radiusTop - this.radiusBottom) / this.height;
+    const intercept = (this.radiusTop + this.radiusBottom) / 2;
+    const radialAtOrigin = intercept + slope * origin[1];
+    const radialAlongRay = slope * direction[1];
+    const candidates: LocalRayIntersection[] = [];
+    const roots = solveQuadratic(
+      direction[0] ** 2 + direction[2] ** 2 - radialAlongRay ** 2,
+      2 * (origin[0] * direction[0] + origin[2] * direction[2] - radialAtOrigin * radialAlongRay),
+      origin[0] ** 2 + origin[2] ** 2 - radialAtOrigin ** 2
+    );
+    for (const distance of roots) {
+      const y = origin[1] + distance * direction[1];
+      if (distance >= 0 && y >= -half - EPSILON && y <= half + EPSILON) {
+        const x = origin[0] + distance * direction[0];
+        const z = origin[2] + distance * direction[2];
+        const radial = Math.hypot(x, z) || 1;
+        const normal = [x / radial, -slope, z / radial];
+        const length = Math.hypot(...normal);
+        candidates.push({distance, normal: normal.map(value => value / length)});
+      }
+    }
+    if (Math.abs(direction[1]) > 1e-15) {
+      for (const [y, radius, normalY] of [
+        [-half, this.radiusBottom, -1],
+        [half, this.radiusTop, 1]
+      ]) {
+        const distance = (y - origin[1]) / direction[1];
+        const x = origin[0] + distance * direction[0];
+        const z = origin[2] + distance * direction[2];
+        if (distance >= 0 && Math.hypot(x, z) <= radius + EPSILON)
+          candidates.push({distance, normal: [0, normalY, 0]});
+      }
+    }
+    return candidates.sort((a, b) => a.distance - b.distance)[0];
+  }
+}