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

package/src/lib/hinge-tree.ts

@@ -0,0 +1,170 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {Matrix4} from '@math.gl/core';
+import type {NumericArray} from '@math.gl/core';
+
+/** A rigid panel attached to its parent by a revolute joint. */
+export type HingePanel = {
+  /** Parent index in the input array; -1 for a root. Input order is arbitrary. */
+  parent: number;
+  /** Child-local to parent-local transform at zero angle; defaults to identity. */
+  restTransform?: Readonly<NumericArray>;
+  /** Hinge pivot in parent-local coordinates. Required for nonroots. */
+  pivot?: readonly [number, number, number];
+  /** Right-handed rotation axis in parent-local coordinates; normalized internally. */
+  axis?: readonly [number, number, number];
+};
+
+type Joint = {
+  parent: number;
+  rest: Matrix4;
+  pivot: number[];
+  negativePivot: number[];
+  axis: number[];
+};
+
+/** Experimental rigid-panel kinematics, independent of mesh topology and rendering.
+ * Snapshots its inputs. Does not infer shared edges, solve closed loops or detect collisions.
+ */
+export class HingeTree {
+  readonly panelCount: number;
+  private readonly joints: Joint[];
+  private readonly order: number[];
+  private readonly angles: Float64Array;
+  private readonly local = new Matrix4();
+  private readonly world = new Matrix4();
+  private readonly root = new Matrix4();
+
+  constructor(panels: readonly HingePanel[]) {
+    this.panelCount = panels.length;
+    const children: number[][] = panels.map(() => []);
+    const order: number[] = [];
+    this.joints = panels.map((panel, index) => {
+      const {parent} = panel;
+      if (!Number.isInteger(parent) || parent < -1 || parent >= panels.length || parent === index) {
+        throw new RangeError('Invalid hinge parent index');
+      }
+      if (parent === -1) order.push(index);
+      else children[parent].push(index);
+      const rest = new Matrix4();
+      if (panel.restTransform !== undefined) {
+        validateRigidTransform(panel.restTransform);
+        rest.copy(panel.restTransform);
+      }
+      const pivot = parent === -1 ? [0, 0, 0] : copyVector(panel.pivot);
+      const axis = parent === -1 ? [1, 0, 0] : copyVector(panel.axis);
+      const length = Math.hypot(...axis);
+      if (!Number.isFinite(length) || length === 0) throw new RangeError('Invalid hinge axis');
+      for (let i = 0; i < 3; i++) axis[i] /= length;
+      return {
+        parent,
+        rest,
+        pivot,
+        negativePivot: pivot.map(value => -value),
+        axis
+      };
+    });
+    // Iterative traversal supports deep trees without consuming the call stack.
+    for (let i = 0; i < order.length; i++) {
+      for (const child of children[order[i]]) order.push(child);
+    }
+    if (order.length !== panels.length) throw new RangeError('Hinge parents contain a cycle');
+    this.order = order;
+    this.angles = new Float64Array(panels.length);
+  }
+
+  /** Evaluate one angle per panel in radians (root angles must be zero).
+   * Returns column-major matrices in input-panel order, 16 doubles per panel.
+   * rootTransform places the whole forest; omitted means identity.
+   * Output may alias the inputs: angles and root transform are snapshotted first.
+   * Finite inputs that overflow during composition throw; output may then be partial.
+   */
+  evaluate(
+    angles: Readonly<NumericArray>,
+    output = new Float64Array(this.panelCount * 16),
+    rootTransform?: Readonly<NumericArray>
+  ): Float64Array {
+    if (angles.length !== this.panelCount) throw new RangeError('Expected one angle per panel');
+    if (!(output instanceof Float64Array) || output.length !== this.panelCount * 16) {
+      throw new RangeError('Expected 16 Float64 values per panel');
+    }
+    for (let i = 0; i < angles.length; i++) {
+      if (!Number.isFinite(angles[i]) || (this.joints[i].parent === -1 && angles[i] !== 0)) {
+        throw new RangeError('Expected finite angles and zero root angles');
+      }
+      this.angles[i] = angles[i];
+    }
+    this.root.identity();
+    if (rootTransform !== undefined) {
+      validateRigidTransform(rootTransform);
+      this.root.copy(rootTransform);
+    }
+    for (const index of this.order) {
+      const joint = this.joints[index];
+      this.local.identity();
+      if (joint.parent !== -1) {
+        this.local
+          .translate(joint.pivot)
+          .rotateAxis(this.angles[index], joint.axis)
+          .translate(joint.negativePivot);
+      }
+      this.local.multiplyRight(joint.rest);
+      if (joint.parent === -1) this.world.copy(this.root);
+      else {
+        for (let i = 0; i < 16; i++) this.world[i] = output[joint.parent * 16 + i];
+      }
+      this.world.multiplyRight(this.local);
+      for (let i = 0; i < 16; i++) {
+        if (!Number.isFinite(this.world[i])) throw new RangeError('Hinge transform overflow');
+        output[index * 16 + i] = this.world[i];
+      }
+    }
+    return output;
+  }
+}
+
+function copyVector(vector?: readonly number[]): number[] {
+  if (
+    !vector ||
+    vector.length !== 3 ||
+    !Number.isFinite(vector[0]) ||
+    !Number.isFinite(vector[1]) ||
+    !Number.isFinite(vector[2])
+  ) {
+    throw new RangeError('Expected a finite hinge pivot and axis');
+  }
+  return [...vector];
+}
+
+/** Accept proper rigid affine transforms, allowing numerical roundoff. */
+function validateRigidTransform(matrix: Readonly<NumericArray>): void {
+  if (matrix.length !== 16) throw new RangeError('Expected a 4x4 rigid transform');
+  for (let i = 0; i < 16; i++) {
+    if (!Number.isFinite(matrix[i])) throw new RangeError('Expected a finite rigid transform');
+  }
+  const tolerance = 1e-6;
+  if (
+    Math.abs(matrix[3]) > tolerance ||
+    Math.abs(matrix[7]) > tolerance ||
+    Math.abs(matrix[11]) > tolerance ||
+    Math.abs(matrix[15] - 1) > tolerance
+  )
+    throw new RangeError('Expected an affine rigid transform');
+  for (let a = 0; a < 3; a++) {
+    for (let b = a; b < 3; b++) {
+      let dot = 0;
+      for (let row = 0; row < 3; row++) dot += matrix[a * 4 + row] * matrix[b * 4 + row];
+      if (Math.abs(dot - (a === b ? 1 : 0)) > tolerance) {
+        throw new RangeError('Rigid transforms cannot scale or shear');
+      }
+    }
+  }
+  const determinant =
+    matrix[0] * (matrix[5] * matrix[10] - matrix[6] * matrix[9]) -
+    matrix[4] * (matrix[1] * matrix[10] - matrix[2] * matrix[9]) +
+    matrix[8] * (matrix[1] * matrix[6] - matrix[2] * matrix[5]);
+  if (Math.abs(determinant - 1) > tolerance)
+    throw new RangeError('Rigid transforms cannot reflect');
+}

package/src/parametric/lathe-geometry.ts

@@ -0,0 +1,70 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import type {PrimitiveGeometryProps} from '../geometries/geometry-helpers';
+import {ParametricGeometry, normalized} from './parametric-geometry';
+export type LatheGeometryProps = PrimitiveGeometryProps & {
+  /** Ordered [radius, height] profile, with nonnegative radii. */
+  points: readonly (readonly [number, number])[];
+  segments?: number;
+  phiStart?: number;
+  phiLength?: number;
+};
+/** Revolves a piecewise-linear profile around Y; smooth profile normals, no end caps. */
+export class LatheGeometry extends ParametricGeometry {
+  constructor(props: LatheGeometryProps) {
+    const {points, segments = 48, phiStart = 0, phiLength = Math.PI * 2} = props;
+    if (
+      !points ||
+      points.length < 2 ||
+      points.some(p => p.length !== 2 || !p.every(Number.isFinite) || p[0] < 0)
+    )
+      throw new RangeError('Lathe needs at least two finite [nonnegative radius, height] points');
+    if (
+      !Number.isFinite(phiStart) ||
+      !Number.isFinite(phiLength) ||
+      phiLength <= 0 ||
+      phiLength > Math.PI * 2
+    )
+      throw new RangeError('Invalid lathe angular sweep');
+    if (segments < 3) throw new RangeError('Lathe requires at least three angular segments');
+    const profile = points.map(p => [...p]);
+    const edgeNormals = profile.slice(1).map((p, i) => {
+      const dr = p[0] - profile[i][0],
+        dy = p[1] - profile[i][1];
+      if (dr === 0 && dy === 0) throw new RangeError('Consecutive profile points must differ');
+      return normalized([dy, -dr, 0]);
+    });
+    const profileNormals = profile.map((_, i) => {
+      const before = edgeNormals[Math.max(0, i - 1)],
+        after = edgeNormals[Math.min(i, edgeNormals.length - 1)];
+      return normalized(before.map((value, axis) => value + after[axis]));
+    });
+    const section = (v: number) => {
+      const coordinate = v * (profile.length - 1),
+        i = Math.min(profile.length - 2, Math.floor(coordinate));
+      return {i, t: coordinate - i};
+    };
+    super({
+      ...props,
+      uSegments: segments,
+      vSegments: profile.length - 1,
+      periodicU: phiLength === Math.PI * 2,
+      sample: (u, v) => {
+        const {i, t} = section(v),
+          radius = profile[i][0] * (1 - t) + profile[i + 1][0] * t,
+          height = profile[i][1] * (1 - t) + profile[i + 1][1] * t,
+          theta = phiStart + u * phiLength;
+        return [radius * Math.cos(theta), height, -radius * Math.sin(theta)];
+      },
+      normal: (u, v) => {
+        const {i, t} = section(v),
+          n = profileNormals[i].map(
+            (value, axis) => value * (1 - t) + profileNormals[i + 1][axis] * t
+          ),
+          theta = phiStart + u * phiLength;
+        return [n[0] * Math.cos(theta), n[1], -n[0] * Math.sin(theta)];
+      }
+    });
+  }
+}

package/src/parametric/parametric-geometry.ts

@@ -0,0 +1,118 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import {Geometry} from '../lib/geometry';
+import {assertSegments, type PrimitiveGeometryProps} from '../geometries/geometry-helpers';
+
+export type SurfaceSampler = (u: number, v: number) => Readonly<ArrayLike<number>>;
+export type ParametricGeometryProps = PrimitiveGeometryProps & {
+  /** Samples the normalized [0,1]² parameter domain. */
+  sample: SurfaceSampler;
+  /** Optional analytic normals; otherwise estimated from neighboring samples. */
+  normal?: SurfaceSampler;
+  uSegments?: number;
+  vSegments?: number;
+  /** Closed axes duplicate their first position/normal at UV 1. */
+  periodicU?: boolean;
+  periodicV?: boolean;
+};
+
+/** Indexed surface grid. Front faces and normals follow ∂P/∂u × ∂P/∂v. */
+export class ParametricGeometry extends Geometry {
+  constructor(props: ParametricGeometryProps) {
+    const {
+      sample,
+      normal,
+      uSegments = 32,
+      vSegments = 32,
+      periodicU = false,
+      periodicV = false
+    } = props;
+    assertSegments(uSegments, 'uSegments');
+    assertSegments(vSegments, 'vSegments');
+    const count = (uSegments + 1) * (vSegments + 1);
+    const indexCount = uSegments * vSegments * 6;
+    if (!Number.isSafeInteger(indexCount) || indexCount > 0xffffffff)
+      throw new RangeError('Surface exceeds 32-bit index-buffer length');
+    if (!Number.isSafeInteger(count) || count > 0xffffffff)
+      throw new RangeError('Surface exceeds 32-bit indexing');
+    const positions = new Float32Array(count * 3),
+      normals = new Float32Array(count * 3),
+      uvs = new Float32Array(count * 2);
+    const canonical = (value: number, periodic: boolean) =>
+      periodic ? ((value % 1) + 1) % 1 : Math.max(0, Math.min(1, value));
+    const evaluate = (u: number, v: number) =>
+      readVector(sample(canonical(u, periodicU), canonical(v, periodicV)));
+    // A small finite-difference step estimates smooth-surface normals independently
+    // of tessellation density. Open boundaries use one-sided differences.
+    const step = 1e-5;
+    let row = 0;
+    for (let j = 0; j <= vSegments; j++)
+      for (let i = 0; i <= uSegments; i++, row++) {
+        const u = i / uSegments,
+          v = j / vSegments;
+        const sampleU = canonical(u, periodicU),
+          sampleV = canonical(v, periodicV);
+        positions.set(evaluate(sampleU, sampleV), row * 3);
+        let n: number[];
+        if (normal) n = readVector(normal(sampleU, sampleV));
+        else {
+          const left = evaluate(sampleU - step, sampleV),
+            right = evaluate(sampleU + step, sampleV);
+          const below = evaluate(sampleU, sampleV - step),
+            above = evaluate(sampleU, sampleV + step);
+          const du = normalized(right.map((value, axis) => value - left[axis]));
+          const dv = normalized(above.map((value, axis) => value - below[axis]));
+          n = [
+            du[1] * dv[2] - du[2] * dv[1],
+            du[2] * dv[0] - du[0] * dv[2],
+            du[0] * dv[1] - du[1] * dv[0]
+          ];
+        }
+        normals.set(normalized(n), row * 3);
+        uvs.set([u, v], row * 2);
+      }
+    for (const value of positions)
+      if (!Number.isFinite(value))
+        throw new RangeError('Positions must be representable as Float32');
+    const indices = count > 0xffff ? new Uint32Array(indexCount) : new Uint16Array(indexCount);
+    const stride = uSegments + 1;
+    let cursor = 0;
+    for (let j = 0; j < vSegments; j++)
+      for (let i = 0; i < uSegments; i++) {
+        const a = j * stride + i,
+          b = a + 1,
+          c = a + stride,
+          d = c + 1;
+        indices[cursor++] = a;
+        indices[cursor++] = b;
+        indices[cursor++] = d;
+        indices[cursor++] = a;
+        indices[cursor++] = d;
+        indices[cursor++] = c;
+      }
+    super({
+      id: props.id,
+      topology: 'triangle-list',
+      indices,
+      attributes: {
+        POSITION: {size: 3, value: positions},
+        NORMAL: {size: 3, value: normals},
+        TEXCOORD_0: {size: 2, value: uvs},
+        ...props.attributes
+      }
+    });
+  }
+}
+function readVector(value: Readonly<ArrayLike<number>>): number[] {
+  if (!value || value.length !== 3 || !Array.from(value).every(Number.isFinite))
+    throw new RangeError('Surface samples and normals must be finite triples');
+  return Array.from(value);
+}
+export function normalized(vector: number[]): number[] {
+  const scale = Math.max(...vector.map(Math.abs));
+  if (!scale) return [0, 0, 0];
+  const scaled = vector.map(value => value / scale),
+    length = Math.hypot(...scaled);
+  return scaled.map(value => (value === 0 ? 0 : value / length));
+}

package/src/parametric/torus-geometry.ts

@@ -0,0 +1,118 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import {Geometry} from '../lib/geometry';
+import {
+  assertPositive,
+  assertSegments,
+  makeIndices,
+  type PrimitiveGeometryProps
+} from '../geometries/geometry-helpers';
+import {ParametricGeometry} from './parametric-geometry';
+export type TorusGeometryProps = PrimitiveGeometryProps & {
+  majorRadius?: number;
+  minorRadius?: number;
+  majorSegments?: number;
+  minorSegments?: number;
+  /** Sweep in radians, (0, 2π]. Partial sweeps have open ends unless cap is enabled. */
+  arc?: number;
+  /** Rotation in radians about Y; positive angles turn toward negative Z. */
+  startAngle?: number;
+  /** Close partial sweeps with flat end disks. Ignored for a full revolution. */
+  cap?: boolean;
+};
+/** Ring torus around Y, with outward analytic normals and separate UV seam rows. */
+export class TorusGeometry extends ParametricGeometry {
+  constructor(props: TorusGeometryProps = {}) {
+    const {
+      majorRadius = 1,
+      minorRadius = 0.3,
+      majorSegments = 48,
+      minorSegments = 24,
+      arc = Math.PI * 2,
+      startAngle = 0,
+      cap = false
+    } = props;
+    assertPositive(majorRadius, 'majorRadius');
+    assertPositive(minorRadius, 'minorRadius');
+    if (minorRadius >= majorRadius)
+      throw new RangeError('Ring torus requires minorRadius < majorRadius');
+    if (!Number.isFinite(arc) || arc <= 0 || arc > Math.PI * 2)
+      throw new RangeError('arc must be in (0, 2π]');
+    assertSegments(majorSegments, 'majorSegments', 3);
+    assertSegments(minorSegments, 'minorSegments', 3);
+    if (!Number.isFinite(startAngle)) throw new RangeError('startAngle must be finite');
+    const hasCaps = cap && arc < Math.PI * 2;
+    super({
+      ...props,
+      attributes: hasCaps ? undefined : props.attributes,
+      uSegments: majorSegments,
+      vSegments: minorSegments,
+      periodicU: arc === Math.PI * 2,
+      periodicV: true,
+      sample: (u, v) => {
+        const theta = startAngle + u * arc,
+          phi = v * Math.PI * 2,
+          radius = majorRadius + minorRadius * Math.cos(phi);
+        return [radius * Math.cos(theta), minorRadius * Math.sin(phi), -radius * Math.sin(theta)];
+      },
+      normal: (u, v) => [
+        Math.cos(v * Math.PI * 2) * Math.cos(startAngle + u * arc),
+        Math.sin(v * Math.PI * 2),
+        -Math.cos(v * Math.PI * 2) * Math.sin(startAngle + u * arc)
+      ]
+    });
+    if (hasCaps) {
+      const surfacePositions = this.attributes['POSITION'].value;
+      const positions = Array.from(surfacePositions);
+      const normals = Array.from(this.attributes['NORMAL'].value);
+      const textureCoordinates = Array.from(this.attributes['TEXCOORD_0'].value);
+      const indices = Array.from(this.indices!.value);
+      for (const [angle, direction] of [
+        [startAngle, -1],
+        [startAngle + arc, 1]
+      ]) {
+        const normal = [-Math.sin(angle) * direction, 0, -Math.cos(angle) * direction];
+        const centerIndex = positions.length / 3;
+        positions.push(majorRadius * Math.cos(angle), 0, -majorRadius * Math.sin(angle));
+        normals.push(...normal);
+        textureCoordinates.push(0.5, 0.5);
+        for (let minorSegment = 0; minorSegment <= minorSegments; minorSegment++) {
+          // The final disk vertex duplicates the first exactly, matching the tube UV seam.
+          const tubeAngle = ((minorSegment % minorSegments) * Math.PI * 2) / minorSegments;
+          // Copy boundary positions so disk and tube edges match bit for bit.
+          const boundaryOffset =
+            (minorSegment * (majorSegments + 1) + (direction < 0 ? 0 : majorSegments)) * 3;
+          positions.push(...surfacePositions.slice(boundaryOffset, boundaryOffset + 3));
+          normals.push(...normal);
+          textureCoordinates.push((Math.cos(tubeAngle) + 1) / 2, (Math.sin(tubeAngle) + 1) / 2);
+          if (minorSegment < minorSegments) {
+            const firstIndex = centerIndex + minorSegment + 1;
+            const secondIndex = firstIndex + 1;
+            indices.push(
+              centerIndex,
+              ...(direction > 0 ? [secondIndex, firstIndex] : [firstIndex, secondIndex])
+            );
+          }
+        }
+      }
+      const cappedGeometry = new Geometry({
+        id: this.id,
+        topology: this.topology,
+        indices: makeIndices(positions.length / 3, indices),
+        attributes: {
+          POSITION: {size: 3, value: new Float32Array(positions)},
+          NORMAL: {size: 3, value: new Float32Array(normals)},
+          TEXCOORD_0: {size: 2, value: new Float32Array(textureCoordinates)},
+          ...props.attributes
+        }
+      });
+      // Finish construction with validated cap data while retaining ParametricGeometry inheritance.
+      Object.assign(this, {
+        attributes: cappedGeometry.attributes,
+        indices: cappedGeometry.indices,
+        vertexCount: cappedGeometry.vertexCount
+      });
+    }
+  }
+}

package/src/parametric.ts

@@ -0,0 +1,9 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+export {ParametricGeometry} from './parametric/parametric-geometry';
+export type {ParametricGeometryProps, SurfaceSampler} from './parametric/parametric-geometry';
+export {TorusGeometry} from './parametric/torus-geometry';
+export type {TorusGeometryProps} from './parametric/torus-geometry';
+export {LatheGeometry} from './parametric/lathe-geometry';
+export type {LatheGeometryProps} from './parametric/lathe-geometry';