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

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

@@ -0,0 +1,209 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Matrix4, Vector3} from '@math.gl/core';
+import {INTERSECTION} from '../../constants';
+import {AxisAlignedBoundingBox} from '../bounding-volumes/axis-aligned-bounding-box';
+import {BoundingSphere} from '../bounding-volumes/bounding-sphere';
+import type {BoundingVolume} from '../bounding-volumes/bounding-volume';
+import type {Plane} from '../plane';
+import type {Ray} from '../ray';
+
+export type RayIntersection = {
+  distance: number;
+  point: Vector3;
+  normal: Vector3;
+  entering: boolean;
+};
+
+export interface ImplicitShape extends BoundingVolume {
+  readonly type: 'box' | 'capsule' | 'cylinder' | 'plane' | 'sphere';
+  readonly matrix: Matrix4;
+  clone(): ImplicitShape;
+  equals(shape: ImplicitShape): boolean;
+  containsPoint(point: readonly number[]): boolean;
+  intersectRay(ray: Ray): RayIntersection | undefined;
+  getAxisAlignedBoundingBox(): AxisAlignedBoundingBox | undefined;
+  getBoundingSphere(): BoundingSphere | undefined;
+}
+
+export type LocalRayIntersection = {distance: number; normal: readonly number[]};
+
+/** Shared affine transform, support mapping and query implementation for finite convex shapes. */
+export abstract class ImplicitShapeBase implements ImplicitShape {
+  abstract readonly type: ImplicitShape['type'];
+  readonly matrix: Matrix4;
+  protected inverseMatrix: Matrix4;
+
+  constructor(matrix?: readonly number[]) {
+    this.matrix = new Matrix4();
+    if (matrix) this.matrix.copy(matrix);
+    validateAffineMatrix(this.matrix);
+    this.inverseMatrix = this.matrix.clone().invert();
+  }
+
+  abstract clone(): ImplicitShapeBase;
+  abstract containsLocalPoint(point: readonly number[]): boolean;
+  abstract distanceToLocalPoint(point: readonly number[]): number;
+  abstract supportLocal(direction: readonly number[]): readonly number[];
+  abstract intersectLocalRay(
+    origin: readonly number[],
+    direction: readonly number[]
+  ): LocalRayIntersection | undefined;
+
+  equals(shape: ImplicitShape): boolean {
+    if (this.type !== shape.type) return false;
+    for (let i = 0; i < 16; i++) if (this.matrix[i] !== shape.matrix[i]) return false;
+    return true;
+  }
+
+  transform(transform: readonly number[]): this {
+    const next = new Matrix4().copy(transform);
+    validateAffineMatrix(next);
+    this.matrix.multiplyLeft(next);
+    validateAffineMatrix(this.matrix);
+    this.inverseMatrix.copy(this.matrix).invert();
+    return this;
+  }
+
+  containsPoint(point: readonly number[]): boolean {
+    return this.containsLocalPoint(this.inverseMatrix.transformAsPoint(point) as readonly number[]);
+  }
+
+  distanceSquaredTo(point: readonly number[]): number {
+    const distance = this.distanceTo(point);
+    return distance * distance;
+  }
+
+  /** Exact for rigid/uniform transforms; conservative estimate for non-uniform scale or shear. */
+  distanceTo(point: readonly number[]): number {
+    const localPoint = this.inverseMatrix.transformAsPoint(point);
+    const localDistance = this.distanceToLocalPoint(localPoint as readonly number[]);
+    const scales = this.matrix.getScale();
+    return localDistance * Math.min(scales[0], scales[1], scales[2]);
+  }
+
+  intersectPlane(plane: Plane): number {
+    const maximum = this.getSupportPoint(plane.normal);
+    const minimum = this.getSupportPoint([-plane.normal[0], -plane.normal[1], -plane.normal[2]]);
+    const maxDistance = plane.getPointDistance(maximum);
+    const minDistance = plane.getPointDistance(minimum);
+    if (minDistance > 0) return INTERSECTION.INSIDE;
+    if (maxDistance < 0) return INTERSECTION.OUTSIDE;
+    return INTERSECTION.INTERSECTING;
+  }
+
+  intersectRay(ray: Ray): RayIntersection | undefined {
+    const localOrigin = this.inverseMatrix.transformAsPoint(ray.origin);
+    const localDirection = this.inverseMatrix.transformAsVector(ray.direction);
+    const hit = this.intersectLocalRay(
+      localOrigin as readonly number[],
+      localDirection as readonly number[]
+    );
+    if (!hit || hit.distance < 0) return undefined;
+    const point = new Vector3(ray.direction).scale(hit.distance).add(ray.origin);
+    const inverse = this.inverseMatrix;
+    const normal = new Vector3(
+      inverse[0] * hit.normal[0] + inverse[1] * hit.normal[1] + inverse[2] * hit.normal[2],
+      inverse[4] * hit.normal[0] + inverse[5] * hit.normal[1] + inverse[6] * hit.normal[2],
+      inverse[8] * hit.normal[0] + inverse[9] * hit.normal[1] + inverse[10] * hit.normal[2]
+    ).normalize();
+    return {distance: hit.distance, point, normal, entering: ray.direction.dot(normal) < 0};
+  }
+
+  getAxisAlignedBoundingBox(): AxisAlignedBoundingBox | undefined {
+    const minimum = new Vector3();
+    const maximum = new Vector3();
+    for (let axis = 0; axis < 3; axis++) {
+      const direction = [0, 0, 0];
+      direction[axis] = 1;
+      maximum[axis] = this.getSupportPoint(direction)[axis];
+      direction[axis] = -1;
+      minimum[axis] = this.getSupportPoint(direction)[axis];
+    }
+    return new AxisAlignedBoundingBox(minimum, maximum);
+  }
+
+  getBoundingSphere(): BoundingSphere | undefined {
+    const box = this.getAxisAlignedBoundingBox();
+    if (!box) return undefined;
+    return new BoundingSphere().fromCornerPoints(box.minimum, box.maximum);
+  }
+
+  protected getSupportPoint(worldDirection: readonly number[]): Vector3 {
+    const matrix = this.matrix;
+    const localDirection = [
+      matrix[0] * worldDirection[0] + matrix[1] * worldDirection[1] + matrix[2] * worldDirection[2],
+      matrix[4] * worldDirection[0] + matrix[5] * worldDirection[1] + matrix[6] * worldDirection[2],
+      matrix[8] * worldDirection[0] + matrix[9] * worldDirection[1] + matrix[10] * worldDirection[2]
+    ];
+    return new Vector3(this.supportLocal(localDirection)).transform(this.matrix);
+  }
+}
+
+export function validateAffineMatrix(matrix: readonly number[]): void {
+  if (matrix.length !== 16 || matrix.some(value => !Number.isFinite(value))) {
+    throw new Error('Shape matrix must contain 16 finite values');
+  }
+  if (
+    Math.abs(matrix[3]) > 1e-12 ||
+    Math.abs(matrix[7]) > 1e-12 ||
+    Math.abs(matrix[11]) > 1e-12 ||
+    Math.abs(matrix[15] - 1) > 1e-12
+  ) {
+    throw new Error('Shape matrix must be affine');
+  }
+  if (Math.abs(new Matrix4().copy(matrix).determinant()) < 1e-15)
+    throw new Error('Shape matrix must be invertible');
+}
+
+export function solveQuadratic(a: number, b: number, c: number): number[] {
+  if (Math.abs(a) < 1e-15) return Math.abs(b) < 1e-15 ? [] : [-c / b];
+  const discriminant = b * b - 4 * a * c;
+  if (discriminant < 0) return [];
+  const root = Math.sqrt(Math.max(0, discriminant));
+  return [(-b - root) / (2 * a), (-b + root) / (2 * a)].sort((left, right) => left - right);
+}
+
+export function closestDistanceToSegment2D(
+  px: number,
+  py: number,
+  ax: number,
+  ay: number,
+  bx: number,
+  by: number
+): number {
+  const dx = bx - ax;
+  const dy = by - ay;
+  const denominator = dx * dx + dy * dy;
+  const t = denominator
+    ? Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / denominator))
+    : 0;
+  return Math.hypot(px - (ax + t * dx), py - (ay + t * dy));
+}
+
+/** Distance in the radial/Y half-plane to a spherical profile arc selected by normal Y range. */
+export function closestDistanceToCircleArc2D(
+  px: number,
+  py: number,
+  centerY: number,
+  radius: number,
+  minimumNormalY: number,
+  maximumNormalY: number
+): number {
+  if (radius === 0) return Math.hypot(px, py - centerY);
+  const dx = px;
+  const dy = py - centerY;
+  const length = Math.hypot(dx, dy);
+  const normalY = length ? dy / length : 0;
+  if (normalY >= minimumNormalY && normalY <= maximumNormalY) {
+    return Math.abs(length - radius);
+  }
+  const minimumRadius = radius * Math.sqrt(Math.max(0, 1 - minimumNormalY ** 2));
+  const maximumRadius = radius * Math.sqrt(Math.max(0, 1 - maximumNormalY ** 2));
+  return Math.min(
+    Math.hypot(px - minimumRadius, py - (centerY + radius * minimumNormalY)),
+    Math.hypot(px - maximumRadius, py - (centerY + radius * maximumNormalY))
+  );
+}

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

@@ -0,0 +1,78 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Vector3} from '@math.gl/core';
+import {INTERSECTION} from '../../constants';
+import {ImplicitShapeBase, type ImplicitShape, type LocalRayIntersection} from './implicit-shape';
+import type {AxisAlignedBoundingBox} from '../bounding-volumes/axis-aligned-bounding-box';
+import type {BoundingSphere} from '../bounding-volumes/bounding-sphere';
+import type {Plane} from '../plane';
+
+export type PlaneShapeProps = {sizeX?: number; sizeZ?: number; matrix?: readonly number[]};
+
+/** Analytic glTF plane. The surface faces +Y and the negative-Y half-space is inside. */
+export class PlaneShape extends ImplicitShapeBase {
+  readonly type = 'plane' as const;
+  readonly sizeX?: number;
+  readonly sizeZ?: number;
+  constructor(props: PlaneShapeProps = {}) {
+    super(props.matrix);
+    this.sizeX = props.sizeX;
+    this.sizeZ = props.sizeZ;
+    if (this.sizeX !== undefined && (!Number.isFinite(this.sizeX) || this.sizeX <= 0))
+      throw new Error('Plane sizeX must be greater than zero');
+    if (this.sizeZ !== undefined && (!Number.isFinite(this.sizeZ) || this.sizeZ <= 0))
+      throw new Error('Plane sizeZ must be greater than zero');
+  }
+  clone(): PlaneShape {
+    return new PlaneShape({sizeX: this.sizeX, sizeZ: this.sizeZ, matrix: this.matrix});
+  }
+  override equals(shape: ImplicitShape): boolean {
+    return (
+      shape instanceof PlaneShape &&
+      super.equals(shape) &&
+      this.sizeX === shape.sizeX &&
+      this.sizeZ === shape.sizeZ
+    );
+  }
+  containsLocalPoint(point: readonly number[]): boolean {
+    return point[1] <= 1e-12;
+  }
+  distanceToLocalPoint(point: readonly number[]): number {
+    return Math.max(0, point[1]);
+  }
+  supportLocal(): readonly number[] {
+    throw new Error('An unbounded plane half-space has no finite support point');
+  }
+  intersectLocalRay(
+    origin: readonly number[],
+    direction: readonly number[]
+  ): LocalRayIntersection | undefined {
+    if (Math.abs(direction[1]) < 1e-15) return undefined;
+    const distance = -origin[1] / direction[1];
+    if (distance < 0) return undefined;
+    const x = origin[0] + distance * direction[0];
+    const z = origin[2] + distance * direction[2];
+    if (this.sizeX !== undefined && Math.abs(x) > this.sizeX / 2 + 1e-12) return undefined;
+    if (this.sizeZ !== undefined && Math.abs(z) > this.sizeZ / 2 + 1e-12) return undefined;
+    return {distance, normal: [0, 1, 0]};
+  }
+  override intersectPlane(plane: Plane): number {
+    const boundaryPoint = new Vector3(0, 0, 0).transform(this.matrix);
+    const inverse = this.inverseMatrix;
+    const boundaryNormal = new Vector3(inverse[1], inverse[5], inverse[9]).normalize();
+    const alignment = boundaryNormal.dot(plane.normal);
+    if (Math.abs(Math.abs(alignment) - 1) > 1e-10) return INTERSECTION.INTERSECTING;
+    const boundaryDistance = plane.getPointDistance(boundaryPoint);
+    if (alignment < 0 && boundaryDistance > 0) return INTERSECTION.INSIDE;
+    if (alignment > 0 && boundaryDistance < 0) return INTERSECTION.OUTSIDE;
+    return INTERSECTION.INTERSECTING;
+  }
+  override getAxisAlignedBoundingBox(): AxisAlignedBoundingBox | undefined {
+    return undefined;
+  }
+  override getBoundingSphere(): BoundingSphere | undefined {
+    return undefined;
+  }
+}

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

@@ -0,0 +1,60 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  ImplicitShapeBase,
+  solveQuadratic,
+  type ImplicitShape,
+  type LocalRayIntersection
+} from './implicit-shape';
+
+const EPSILON = 1e-6;
+
+export type SphereShapeProps = {radius?: number; matrix?: readonly number[]};
+
+/** Analytic glTF sphere shape. */
+export class SphereShape extends ImplicitShapeBase {
+  readonly type = 'sphere' as const;
+  readonly radius: number;
+  constructor(props: SphereShapeProps = {}) {
+    super(props.matrix);
+    this.radius = props.radius ?? 0.5;
+    if (!Number.isFinite(this.radius) || this.radius <= 0)
+      throw new Error('Sphere radius must be greater than zero');
+  }
+  clone(): SphereShape {
+    return new SphereShape({radius: this.radius, matrix: this.matrix});
+  }
+  override equals(shape: ImplicitShape): boolean {
+    return shape instanceof SphereShape && super.equals(shape) && this.radius === shape.radius;
+  }
+  containsLocalPoint(point: readonly number[]): boolean {
+    return Math.hypot(...point) <= this.radius + EPSILON;
+  }
+  distanceToLocalPoint(point: readonly number[]): number {
+    return Math.max(0, Math.hypot(...point) - this.radius);
+  }
+  supportLocal(direction: readonly number[]): readonly number[] {
+    const length = Math.hypot(...direction);
+    return length ? direction.map(value => (value / length) * this.radius) : [this.radius, 0, 0];
+  }
+  intersectLocalRay(
+    origin: readonly number[],
+    direction: readonly number[]
+  ): LocalRayIntersection | undefined {
+    const roots = solveQuadratic(
+      dot(direction, direction),
+      2 * dot(origin, direction),
+      dot(origin, origin) - this.radius * this.radius
+    );
+    const distance = roots.find(value => value >= 0);
+    if (distance === undefined) return undefined;
+    const point = origin.map((value, i) => value + distance * direction[i]);
+    return {distance, normal: point.map(value => value / this.radius)};
+  }
+}
+
+function dot(a: readonly number[], b: readonly number[]): number {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}