Add marching cubes isosurface extraction

README.md

@@ -33,7 +33,7 @@ CDN usage:
 | Search & text | `fuzzySearch`, `fuzzyScore`, `Trie`, `binarySearch`, `levenshteinDistance`, `kmpSearch`, `rabinKarp`, `boyerMooreSearch`, `buildSuffixArray`, `longestCommonSubsequence`, `diffStrings` | `search/*.ts` | `examples/search.ts` |
 | Data & diff pipelines | `diff`, `deepClone`, `groupBy`, `diffJson`, `diffJsonAdvanced`, `applyJsonDiff`, `applyJsonDiffSelective`, `flatten`, `unflatten`, `diffTree`, `applyTreeDiff` | `data/*.ts` | `examples/jsonDiff.ts`, `examples/treeDiff.ts` |
 | Graph algorithms | `graphBFS`, `graphDFS`, `topologicalSort` | `graph/traversal.ts` | `examples/graph.ts` |
-| Visual & geometry | `convexHull`, `lineIntersection`, `pointInPolygon`, `bresenhamLine`, `easing`, `quadraticBezier`, `cubicBezier`, `hexToRgb`, `rgbToHex`, `rgbToHsl`, `hslToRgb`, `mixRgbColors`, `computeForceDirectedLayout`, `computeMarchingSquares` | `geometry/*.ts`, `visual/*.ts` | `examples/geometry.ts`, `examples/bresenham.ts`, `examples/visual.ts`, `examples/color.ts`, `examples/forceDirected.ts`, `examples/marchingSquares.ts` |
+| Visual & geometry | `convexHull`, `lineIntersection`, `pointInPolygon`, `bresenhamLine`, `easing`, `quadraticBezier`, `cubicBezier`, `hexToRgb`, `rgbToHex`, `rgbToHsl`, `hslToRgb`, `mixRgbColors`, `computeForceDirectedLayout`, `computeMarchingSquares`, `computeMarchingCubes` | `geometry/*.ts`, `visual/*.ts` | `examples/geometry.ts`, `examples/bresenham.ts`, `examples/visual.ts`, `examples/color.ts`, `examples/forceDirected.ts`, `examples/marchingSquares.ts`, `examples/marchingCubes.ts` |
 
 ## Scripts
 ```bash

ROADMAP.md

@@ -90,7 +90,7 @@
   - [x] Color manipulation helpers (RGB/HSL conversion, blending)
   - [x] Force-directed graph layout
   - [x] Marching squares contour extraction
-  - [ ] Marching cubes isosurface generation
+  - [x] Marching cubes isosurface generation
 - **Graph algorithms**
   - [ ] Minimum spanning tree (Kruskal)
   - [ ] Strongly connected components (Tarjan/Kosaraju)

docs/index.d.ts

@@ -159,6 +159,7 @@ export const examples: {
     readonly mixRgbColors: 'examples/color.ts';
     readonly computeForceDirectedLayout: 'examples/forceDirected.ts';
     readonly computeMarchingSquares: 'examples/marchingSquares.ts';
+    readonly computeMarchingCubes: 'examples/marchingCubes.ts';
   };
 };
 
@@ -3139,6 +3140,64 @@ export interface MarchingSquaresResult {
  */
 export function computeMarchingSquares(options: MarchingSquaresOptions): MarchingSquaresResult;
 
+/**
+ * Scalar field configuration for marching cubes.
+ * Use for: volumetric data, signed distance fields, density grids.
+ * Import: visual/marchingCubes.ts
+ */
+export interface ScalarField3D {
+  data: ReadonlyArray<ReadonlyArray<ReadonlyArray<number>>>;
+  cellSize?: number | { x: number; y: number; z: number };
+}
+
+/**
+ * Marching cubes configuration options.
+ * Use for: extracting isosurfaces from 3D scalar fields.
+ * Import: visual/marchingCubes.ts
+ */
+export interface MarchingCubesOptions {
+  field: ScalarField3D | ReadonlyArray<ReadonlyArray<ReadonlyArray<number>>>;
+  threshold?: number;
+}
+
+/**
+ * 3D vector representation used by marching cubes.
+ * Use for: triangle vertices, normals, mesh construction.
+ * Import: visual/marchingCubes.ts
+ */
+export interface Vector3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+/**
+ * Triangle output from marching cubes.
+ * Use for: mesh generation, collision geometry, visualization.
+ * Import: visual/marchingCubes.ts
+ */
+export interface Triangle {
+  a: Vector3;
+  b: Vector3;
+  c: Vector3;
+}
+
+/**
+ * Marching cubes result payload.
+ * Use for: converting scalar fields into triangle meshes.
+ * Import: visual/marchingCubes.ts
+ */
+export interface MarchingCubesResult {
+  triangles: Triangle[];
+}
+
+/**
+ * Computes triangles using the marching cubes algorithm.
+ * Use for: isosurface extraction, voxel rendering, volumetric meshing.
+ * Import: visual/marchingCubes.ts
+ */
+export function computeMarchingCubes(options: MarchingCubesOptions): MarchingCubesResult;
+
 // ============================================================================
 // 🤖 STEERING BEHAVIOURS
 // ============================================================================

docs/list.md

@@ -52,6 +52,7 @@ Weighted Random Selection - Probability-based selection
 Fisher-Yates Shuffle - Unbiased array randomization
 Bresenham's Line - Grid line drawing
 Marching Squares - Contour generation from scalar fields
+Marching Cubes - 3D isosurface extraction
 Object Pool - Memory optimization for reusable objects
 
 🎮 GAME SYSTEMS

examples/marchingCubes.ts

@@ -0,0 +1,23 @@
+import { computeMarchingCubes } from '../src/index.js';
+
+const size = 6;
+const field: number[][][] = [];
+const radius = 2.2;
+for (let z = 0; z < size; z += 1) {
+  const slice: number[][] = [];
+  for (let y = 0; y < size; y += 1) {
+    const row: number[] = [];
+    for (let x = 0; x < size; x += 1) {
+      const dx = x - (size - 1) / 2;
+      const dy = y - (size - 1) / 2;
+      const dz = z - (size - 1) / 2;
+      row.push(radius - Math.hypot(dx, dy, dz));
+    }
+    slice.push(row);
+  }
+  field.push(slice);
+}
+
+const { triangles } = computeMarchingCubes({ field, threshold: 0 });
+console.log('Generated triangles:', triangles.length);
+console.log('First triangle:', triangles[0]);

src/index.ts

@@ -158,6 +158,7 @@ export const examples = {
     mixRgbColors: 'examples/color.ts',
     computeForceDirectedLayout: 'examples/forceDirected.ts',
     computeMarchingSquares: 'examples/marchingSquares.ts',
+    computeMarchingCubes: 'examples/marchingCubes.ts',
   },
 } as const;
 
@@ -1067,6 +1068,19 @@ export type {
   Point2D,
 } from './visual/marchingSquares.js';
 
+/**
+ * Marching cubes isosurface extraction.
+ */
+export { computeMarchingCubes } from './visual/marchingCubes.js';
+
+export type {
+  MarchingCubesOptions,
+  MarchingCubesResult,
+  ScalarField3D,
+  Vector3,
+  Triangle,
+} from './visual/marchingCubes.js';
+
 // ============================================================================
 // 🤖 AI & BEHAVIOUR
 // ============================================================================