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

package/src/curves/curve.ts

@@ -0,0 +1,96 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {NumericArray} from '@math.gl/core/types';
+
+export type CurvePoint = Readonly<ArrayLike<number>>;
+
+/** Parameterized Euclidean curve, with t in [0, 1]. */
+export abstract class Curve {
+  readonly dimension: number;
+
+  protected constructor(dimension: number) {
+    if (dimension !== 2 && dimension !== 3) {
+      throw new RangeError('Curve points must have two or three coordinates');
+    }
+    this.dimension = dimension;
+  }
+
+  getPoint(t: number): number[];
+  getPoint<T extends NumericArray>(t: number, result: T): T;
+  getPoint(t: number, result: NumericArray = new Array(this.dimension)): NumericArray {
+    validateParameter(t);
+    validateResult(result, this.dimension);
+    this.evaluate(t, result, false);
+    return result;
+  }
+
+  /** Derivative with respect to the normalized curve parameter t. */
+  getDerivative(t: number): number[];
+  getDerivative<T extends NumericArray>(t: number, result: T): T;
+  getDerivative(t: number, result: NumericArray = new Array(this.dimension)): NumericArray {
+    validateParameter(t);
+    validateResult(result, this.dimension);
+    this.evaluate(t, result, true);
+    return result;
+  }
+
+  /** Unit tangent; returns a zero vector at stationary points. */
+  getTangent(t: number): number[];
+  getTangent<T extends NumericArray>(t: number, result: T): T;
+  getTangent(t: number, result: NumericArray = new Array(this.dimension)): NumericArray {
+    this.getDerivative(t, result);
+    const length = Math.hypot(result[0], result[1], this.dimension === 3 ? result[2] : 0);
+    if (length > 0) {
+      for (let i = 0; i < this.dimension; i++) result[i] /= length;
+    }
+    return result;
+  }
+
+  /** Flat coordinates for divisions + 1 evenly spaced parameter samples. */
+  getPoints(divisions = 64): Float64Array {
+    validateDivisions(divisions);
+    const points = new Float64Array((divisions + 1) * this.dimension);
+    const point = new Array<number>(this.dimension);
+    for (let i = 0; i <= divisions; i++) {
+      this.getPoint(i / divisions, point);
+      points.set(point, i * this.dimension);
+    }
+    return points;
+  }
+
+  protected abstract evaluate(t: number, result: NumericArray, derivative: boolean): void;
+}
+
+/** Copy caller-owned control data so curves and their length tables stay stable. */
+export function copyPoints(points: readonly CurvePoint[]): number[][] {
+  if (!points.length) throw new RangeError('Invalid number of curve control points');
+  const dimension = points[0].length;
+  if (dimension !== 2 && dimension !== 3) {
+    throw new RangeError('Curve points must have two or three coordinates');
+  }
+  return points.map(point => {
+    if (point.length !== dimension) throw new RangeError('Control point dimensions must match');
+    return Array.from(point, value => {
+      if (!Number.isFinite(value)) throw new RangeError('Control coordinates must be finite');
+      return value;
+    });
+  });
+}
+
+export function validateParameter(t: number): void {
+  if (!Number.isFinite(t) || t < 0 || t > 1) {
+    throw new RangeError('Curve parameter must be finite and in [0, 1]');
+  }
+}
+
+export function validateDivisions(divisions: number): void {
+  if (!Number.isSafeInteger(divisions) || divisions < 1) {
+    throw new RangeError('divisions must be a positive safe integer');
+  }
+}
+
+function validateResult(result: NumericArray, dimension: number): void {
+  if (result.length < dimension) throw new RangeError('Result buffer is too short');
+}

package/src/curves/hermite-curve.ts

@@ -0,0 +1,34 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {NumericArray} from '@math.gl/core/types';
+import {Curve, copyPoints, type CurvePoint} from './curve';
+
+/** Cubic curve with endpoint derivatives (not unit tangent directions). */
+export class HermiteCurve extends Curve {
+  private readonly data: number[][];
+
+  constructor(
+    start: CurvePoint,
+    end: CurvePoint,
+    startTangent: CurvePoint,
+    endTangent: CurvePoint
+  ) {
+    const data = copyPoints([start, end, startTangent, endTangent]);
+    super(data[0].length);
+    this.data = data;
+  }
+
+  protected evaluate(t: number, result: NumericArray, derivative: boolean): void {
+    const t2 = t * t;
+    const h0 = derivative ? 6 * t2 - 6 * t : (1 + 2 * t) * (1 - t) ** 2;
+    const h1 = derivative ? -6 * t2 + 6 * t : t2 * (3 - 2 * t);
+    const h2 = derivative ? 3 * t2 - 4 * t + 1 : t * (1 - t) ** 2;
+    const h3 = derivative ? 3 * t2 - 2 * t : t2 * (t - 1);
+    for (let i = 0; i < this.dimension; i++) {
+      result[i] =
+        h0 * this.data[0][i] + h1 * this.data[1][i] + h2 * this.data[2][i] + h3 * this.data[3][i];
+    }
+  }
+}

package/src/curves/index.ts

@@ -0,0 +1,15 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export {Curve} from './curve';
+export type {CurvePoint} from './curve';
+export {
+  LineCurve,
+  QuadraticBezierCurve,
+  CubicBezierCurve
+} from './bezier-curves';
+export {HermiteCurve} from './hermite-curve';
+export {CatmullRomCurve} from './catmull-rom-curve';
+export type {CatmullRomCurveOptions} from './catmull-rom-curve';
+export {CurveArcLength} from './curve-arc-length';

package/src/geometries/box-geometry.ts

@@ -1,6 +1,6 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 import {Geometry, type GeometryAttributeInput} from '../lib/geometry';
 import {assertPositive, makeIndices, type PrimitiveGeometryProps} from './geometry-helpers';

package/src/geometries/capsule-geometry.ts

@@ -1,6 +1,6 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 import {Geometry} from '../lib/geometry';
 import {

package/src/geometries/cylinder-geometry.ts

@@ -1,6 +1,6 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 import {TruncatedConeGeometry, type TruncatedConeGeometryProps} from './truncated-cone-geometry';
 

package/src/geometries/geometry-helpers.ts

@@ -1,6 +1,6 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 import type {GeometryAttributeInput} from '../lib/geometry';
 

package/src/geometries/ico-sphere-geometry.ts

@@ -1,6 +1,6 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 import {Geometry} from '../lib/geometry';
 import {assertPositive, assertSegments, type PrimitiveGeometryProps} from './geometry-helpers';

package/src/geometries/plane-geometry.ts

@@ -1,6 +1,6 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 import {Geometry} from '../lib/geometry';
 import {

package/src/geometries/primitive-mesh-builder.ts

@@ -0,0 +1,84 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {GeometryProps} from '../lib/geometry';
+import {assertSegments, makeIndices, type PrimitiveGeometryProps} from './geometry-helpers';
+export const FULL_CIRCLE = Math.PI * 2;
+export type Vector = [number, number, number];
+export type Vertex = {position: Vector; normal: Vector; textureCoordinates: [number, number]};
+export function radial(angle: number, direction = 1): Vector {
+  return [Math.cos(angle) * direction, 0, -Math.sin(angle) * direction];
+}
+export function vertex(
+  radius: number,
+  height: number,
+  angle: number,
+  normal: Vector,
+  textureCoordinates?: [number, number]
+): Vertex {
+  return {
+    position: [radius * Math.cos(angle), height, -radius * Math.sin(angle)],
+    normal,
+    textureCoordinates: textureCoordinates ?? [(Math.cos(angle) + 1) / 2, (Math.sin(angle) + 1) / 2]
+  };
+}
+export function validateArc(segments: number, startAngle: number, sweepAngle: number): void {
+  assertSegments(segments, 'segments', 3);
+  if (!Number.isFinite(startAngle)) throw new Error('startAngle must be finite');
+  if (!Number.isFinite(sweepAngle) || sweepAngle <= 0 || sweepAngle > FULL_CIRCLE)
+    throw new Error('sweepAngle must be positive and at most 2π');
+}
+export class PrimitiveMeshBuilder {
+  private positions: number[] = [];
+  private normals: number[] = [];
+  private textureCoordinates: number[] = [];
+  private indices: number[] = [];
+  private addVertex(current: Vertex): number {
+    const index = this.positions.length / 3;
+    this.positions.push(...current.position);
+    this.normals.push(...current.normal);
+    this.textureCoordinates.push(...current.textureCoordinates);
+    return index;
+  }
+  private addTriangle(first: Vertex, second: Vertex, third: Vertex, indices: number[]): void {
+    const firstEdge = second.position.map((value, index) => value - first.position[index]);
+    const secondEdge = third.position.map((value, index) => value - first.position[index]);
+    const cross = [
+      firstEdge[1] * secondEdge[2] - firstEdge[2] * secondEdge[1],
+      firstEdge[2] * secondEdge[0] - firstEdge[0] * secondEdge[2],
+      firstEdge[0] * secondEdge[1] - firstEdge[1] * secondEdge[0]
+    ];
+    const orientation = cross.reduce(
+      (sum, value, index) =>
+        sum + value * (first.normal[index] + second.normal[index] + third.normal[index]),
+      0
+    );
+    this.indices.push(...(orientation < 0 ? [indices[0], indices[2], indices[1]] : indices));
+  }
+  triangle(first: Vertex, second: Vertex, third: Vertex): void {
+    this.addTriangle(first, second, third, [
+      this.addVertex(first),
+      this.addVertex(second),
+      this.addVertex(third)
+    ]);
+  }
+  quad(first: Vertex, second: Vertex, third: Vertex, fourth: Vertex): void {
+    const indices = [first, second, third, fourth].map(current => this.addVertex(current));
+    this.addTriangle(first, second, third, indices.slice(0, 3));
+    this.addTriangle(first, third, fourth, [indices[0], indices[2], indices[3]]);
+  }
+  getProps(props: PrimitiveGeometryProps): GeometryProps {
+    return {
+      id: props.id,
+      topology: 'triangle-list',
+      indices: makeIndices(this.positions.length / 3, this.indices),
+      attributes: {
+        POSITION: {size: 3, value: new Float32Array(this.positions)},
+        NORMAL: {size: 3, value: new Float32Array(this.normals)},
+        TEXCOORD_0: {size: 2, value: new Float32Array(this.textureCoordinates)},
+        ...props.attributes
+      }
+    };
+  }
+}

package/src/geometries/prism-geometry.ts

@@ -0,0 +1,57 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {Geometry} from '../lib/geometry';
+import {assertPositive, type PrimitiveGeometryProps} from './geometry-helpers';
+import {
+  PrimitiveMeshBuilder,
+  FULL_CIRCLE,
+  radial,
+  validateArc,
+  vertex,
+  type Vector,
+  type Vertex
+} from './primitive-mesh-builder';
+export type PrismGeometryProps = PrimitiveGeometryProps & {
+  radius?: number;
+  height?: number;
+  sides?: number;
+  startAngle?: number;
+};
+/** Closed regular prism, centered at the origin with Y vertical and flat side normals. */
+export class PrismGeometry extends Geometry {
+  constructor(props: PrismGeometryProps = {}) {
+    const {radius = 1, height = 1, sides = 6, startAngle = 0} = props;
+    assertPositive(radius, 'radius');
+    assertPositive(height, 'height');
+    validateArc(sides, startAngle, FULL_CIRCLE);
+    const mesh = new PrimitiveMeshBuilder();
+    for (let segment = 0; segment < sides; segment++) {
+      const firstAngle = startAngle + (segment * FULL_CIRCLE) / sides;
+      const secondAngle = startAngle + ((segment + 1) * FULL_CIRCLE) / sides;
+      const normal = radial((firstAngle + secondAngle) / 2);
+      const secondCornerAngle = segment === sides - 1 ? startAngle : secondAngle;
+      mesh.quad(
+        vertex(radius, -height / 2, firstAngle, normal, [segment / sides, 0]),
+        vertex(radius, height / 2, firstAngle, normal, [segment / sides, 1]),
+        vertex(radius, height / 2, secondCornerAngle, normal, [(segment + 1) / sides, 1]),
+        vertex(radius, -height / 2, secondCornerAngle, normal, [(segment + 1) / sides, 0])
+      );
+      for (const direction of [-1, 1]) {
+        const capNormal: Vector = [0, direction, 0];
+        const center: Vertex = {
+          position: [0, (direction * height) / 2, 0],
+          normal: capNormal,
+          textureCoordinates: [0.5, 0.5]
+        };
+        mesh.triangle(
+          center,
+          vertex(radius, (direction * height) / 2, firstAngle, capNormal),
+          vertex(radius, (direction * height) / 2, secondCornerAngle, capNormal)
+        );
+      }
+    }
+    super(mesh.getProps(props));
+  }
+}

package/src/geometries/ring-geometry.ts

@@ -0,0 +1,102 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {Geometry} from '../lib/geometry';
+import {assertPositive, type PrimitiveGeometryProps} from './geometry-helpers';
+import {
+  PrimitiveMeshBuilder,
+  FULL_CIRCLE,
+  radial,
+  validateArc,
+  vertex,
+  type Vector
+} from './primitive-mesh-builder';
+export type RingGeometryProps = PrimitiveGeometryProps & {
+  innerRadius?: number;
+  outerRadius?: number;
+  height?: number;
+  segments?: number;
+  startAngle?: number;
+  sweepAngle?: number;
+};
+/** Closed annular sector in XZ, centered vertically with hard top, bottom and end caps. */
+export class RingGeometry extends Geometry {
+  constructor(props: RingGeometryProps = {}) {
+    const {
+      innerRadius = 0.5,
+      outerRadius = 1,
+      height = 0.1,
+      segments = 48,
+      startAngle = 0,
+      sweepAngle = FULL_CIRCLE
+    } = props;
+    assertPositive(innerRadius, 'innerRadius');
+    assertPositive(outerRadius, 'outerRadius');
+    assertPositive(height, 'height');
+    if (innerRadius >= outerRadius) throw new Error('innerRadius must be smaller than outerRadius');
+    validateArc(segments, startAngle, sweepAngle);
+    const mesh = new PrimitiveMeshBuilder();
+    for (let segment = 0; segment < segments; segment++) {
+      const firstAngle = startAngle + (segment * sweepAngle) / segments;
+      const secondAngle =
+        segment === segments - 1
+          ? sweepAngle === FULL_CIRCLE
+            ? startAngle
+            : startAngle + sweepAngle
+          : startAngle + ((segment + 1) * sweepAngle) / segments;
+      const makeCapVertex = (radius: number, height: number, angle: number, normal: Vector) =>
+        vertex(radius, height, angle, normal, [
+          ((radius * Math.cos(angle)) / outerRadius + 1) / 2,
+          ((radius * Math.sin(angle)) / outerRadius + 1) / 2
+        ]);
+      for (const direction of [-1, 1]) {
+        const normal: Vector = [0, direction, 0];
+        mesh.quad(
+          makeCapVertex(innerRadius, (direction * height) / 2, firstAngle, normal),
+          makeCapVertex(outerRadius, (direction * height) / 2, firstAngle, normal),
+          makeCapVertex(outerRadius, (direction * height) / 2, secondAngle, normal),
+          makeCapVertex(innerRadius, (direction * height) / 2, secondAngle, normal)
+        );
+      }
+      for (const [radius, direction] of [
+        [innerRadius, -1],
+        [outerRadius, 1]
+      ]) {
+        mesh.quad(
+          vertex(radius, -height / 2, firstAngle, radial(firstAngle, direction), [
+            segment / segments,
+            0
+          ]),
+          vertex(radius, height / 2, firstAngle, radial(firstAngle, direction), [
+            segment / segments,
+            1
+          ]),
+          vertex(radius, height / 2, secondAngle, radial(secondAngle, direction), [
+            (segment + 1) / segments,
+            1
+          ]),
+          vertex(radius, -height / 2, secondAngle, radial(secondAngle, direction), [
+            (segment + 1) / segments,
+            0
+          ])
+        );
+      }
+    }
+    if (sweepAngle < FULL_CIRCLE) {
+      for (const [angle, direction] of [
+        [startAngle, -1],
+        [startAngle + sweepAngle, 1]
+      ]) {
+        const normal: Vector = [-Math.sin(angle) * direction, 0, -Math.cos(angle) * direction];
+        mesh.quad(
+          vertex(innerRadius, -height / 2, angle, normal, [0, 0]),
+          vertex(outerRadius, -height / 2, angle, normal, [1, 0]),
+          vertex(outerRadius, height / 2, angle, normal, [1, 1]),
+          vertex(innerRadius, height / 2, angle, normal, [0, 1])
+        );
+      }
+    }
+    super(mesh.getProps(props));
+  }
+}

package/src/geometries/sphere-geometry.ts

@@ -1,6 +1,6 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 import {Geometry} from '../lib/geometry';
 import {assertPositive, assertSegments, type PrimitiveGeometryProps} from './geometry-helpers';

package/src/geometries/surface-of-revolution.ts

@@ -1,6 +1,6 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 import {makeIndices, type MeshData} from './geometry-helpers';
 

package/src/geometries/truncated-cone-geometry.ts

@@ -1,6 +1,6 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 import {Geometry} from '../lib/geometry';
 import {

package/src/index.ts

@@ -1,6 +1,6 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
 export {Geometry} from './lib/geometry';
 export type {
@@ -10,6 +10,9 @@ export type {
   GeometryAttributes,
   PrimitiveTopology
 } from './lib/geometry';
+export {HingeTree} from './lib/hinge-tree';
+export type {HingePanel} from './lib/hinge-tree';
+
 export {unpackIndexedGeometry} from './lib/geometry-utils';
 
 export {BoxGeometry, CubeGeometry} from './geometries/box-geometry';
@@ -26,3 +29,9 @@ export {TruncatedConeGeometry} from './geometries/truncated-cone-geometry';
 export type {TruncatedConeGeometryProps} from './geometries/truncated-cone-geometry';
 export {IcoSphereGeometry} from './geometries/ico-sphere-geometry';
 export type {IcoSphereGeometryProps} from './geometries/ico-sphere-geometry';
+
+export {PrismGeometry} from './geometries/prism-geometry';
+export type {PrismGeometryProps} from './geometries/prism-geometry';
+
+export {RingGeometry} from './geometries/ring-geometry';
+export type {RingGeometryProps} from './geometries/ring-geometry';

package/src/lib/geometry-utils.ts

@@ -1,8 +1,8 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
-import type {TypedArray, TypedArrayConstructor} from '@math.gl/types';
+import type {TypedArray, TypedArrayConstructor} from '@math.gl/core/types';
 import type {GeometryAttribute} from './geometry';
 
 type GeometryLike = {

package/src/lib/geometry.ts

@@ -1,8 +1,8 @@
 // math.gl
 // SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
-import type {TypedArray} from '@math.gl/types';
+import type {TypedArray} from '@math.gl/core/types';
 
 export type PrimitiveTopology =
   | 'point-list'