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

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];
+  }
+}

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;
+  }
+}