From 1ed491b473b3eeb45508bef1865ba4a49dd9476f Mon Sep 17 00:00:00 2001
From: Francois <f.gueguen@24market.fr>
Date: Wed, 8 Oct 2025 18:20:07 +0900
Subject: [PATCH] feat: add marching cubes isosurface extraction

---
 README.md                   |   2 +-
 ROADMAP.md                  |   2 +-
 docs/index.d.ts             |  59 +++++
 docs/list.md                |   1 +
 examples/marchingCubes.ts   |  23 ++
 src/index.ts                |  14 ++
 src/visual/marchingCubes.ts | 487 ++++++++++++++++++++++++++++++++++++
 tests/index.test.ts         |   2 +
 tests/marchingCubes.test.ts |  89 +++++++
 9 files changed, 677 insertions(+), 2 deletions(-)
 create mode 100644 examples/marchingCubes.ts
 create mode 100644 src/visual/marchingCubes.ts
 create mode 100644 tests/marchingCubes.test.ts

diff --git a/README.md b/README.md
index 5dfe508..48c481f 100644
--- a/README.md
+++ b/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
diff --git a/ROADMAP.md b/ROADMAP.md
index 07cf6a8..4624733 100644
--- a/ROADMAP.md
+++ b/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)
diff --git a/docs/index.d.ts b/docs/index.d.ts
index 0c1f1e1..febbf63 100644
--- a/docs/index.d.ts
+++ b/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
 // ============================================================================
diff --git a/docs/list.md b/docs/list.md
index cd0b018..cce8a02 100644
--- a/docs/list.md
+++ b/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
diff --git a/examples/marchingCubes.ts b/examples/marchingCubes.ts
new file mode 100644
index 0000000..a9343ba
--- /dev/null
+++ b/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]);
diff --git a/src/index.ts b/src/index.ts
index 6b0f26d..debadcf 100644
--- a/src/index.ts
+++ b/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
 // ============================================================================
diff --git a/src/visual/marchingCubes.ts b/src/visual/marchingCubes.ts
new file mode 100644
index 0000000..ab69d60
--- /dev/null
+++ b/src/visual/marchingCubes.ts
@@ -0,0 +1,487 @@
+export interface ScalarField3D {
+  data: ReadonlyArray<ReadonlyArray<ReadonlyArray<number>>>;
+  cellSize?: number | { x: number; y: number; z: number };
+}
+
+export interface MarchingCubesOptions {
+  field: ScalarField3D | ReadonlyArray<ReadonlyArray<ReadonlyArray<number>>>;
+  threshold?: number;
+}
+
+export interface Vector3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export interface Triangle {
+  a: Vector3;
+  b: Vector3;
+  c: Vector3;
+}
+
+export interface MarchingCubesResult {
+  triangles: Triangle[];
+}
+
+type CubeValues = [number, number, number, number, number, number, number, number];
+
+const EDGE_TABLE = new Int32Array([
+  0x0, 0x109, 0x203, 0x30a, 0x406, 0x50f, 0x605, 0x70c, 0x80c, 0x905, 0xa0f, 0xb06, 0xc0a, 0xd03, 0xe09, 0xf00,
+  0x190, 0x99, 0x393, 0x29a, 0x596, 0x49f, 0x795, 0x69c, 0x99c, 0x895, 0xb9f, 0xa96, 0xd9a, 0xc93, 0xf99, 0xe90,
+  0x230, 0x339, 0x33, 0x13a, 0x636, 0x73f, 0x435, 0x53c, 0xa3c, 0xb35, 0x83f, 0x936, 0xe3a, 0xf33, 0xc39, 0xd30,
+  0x3a0, 0x2a9, 0x1a3, 0xaa, 0x7a6, 0x6af, 0x5a5, 0x4ac, 0xbac, 0xaa5, 0x9af, 0x8a6, 0xfaa, 0xea3, 0xda9, 0xca0,
+  0x460, 0x569, 0x663, 0x76a, 0x66, 0x16f, 0x265, 0x36c, 0xc6c, 0xd65, 0xe6f, 0xf66, 0x86a, 0x963, 0xa69, 0xb60,
+  0x5f0, 0x4f9, 0x7f3, 0x6fa, 0x1f6, 0xff, 0x3f5, 0x2fc, 0xdfc, 0xcf5, 0xfff, 0xef6, 0x9fa, 0x8f3, 0xbf9, 0xaf0,
+  0x650, 0x759, 0x453, 0x55a, 0x256, 0x35f, 0x55, 0x15c, 0xe5c, 0xf55, 0xc5f, 0xd56, 0xa5a, 0xb53, 0x859, 0x950,
+  0x7c0, 0x6c9, 0x5c3, 0x4ca, 0x3c6, 0x2cf, 0x1c5, 0xcc, 0xfcc, 0xec5, 0xdcf, 0xcc6, 0xbca, 0xac3, 0x9c9, 0x8c0,
+  0x8c0, 0x9c9, 0xac3, 0xbca, 0xcc6, 0xdcf, 0xec5, 0xfcc, 0xcc, 0x1c5, 0x2cf, 0x3c6, 0x4ca, 0x5c3, 0x6c9, 0x7c0,
+  0x950, 0x859, 0xb53, 0xa5a, 0xd56, 0xc5f, 0xf55, 0xe5c, 0x15c, 0x55, 0x35f, 0x256, 0x55a, 0x453, 0x759, 0x650,
+  0xaf0, 0xbf9, 0x8f3, 0x9fa, 0xef6, 0xfff, 0xcf5, 0xdfc, 0x2fc, 0x3f5, 0xff, 0x1f6, 0x6fa, 0x7f3, 0x4f9, 0x5f0,
+  0xb60, 0xa69, 0x963, 0x86a, 0xf66, 0xe6f, 0xd65, 0xc6c, 0x36c, 0x265, 0x16f, 0x66, 0x76a, 0x663, 0x569, 0x460,
+  0xca0, 0xda9, 0xea3, 0xfaa, 0x8a6, 0x9af, 0xaa5, 0xbac, 0x4ac, 0x5a5, 0x6af, 0x7a6, 0xaa, 0x1a3, 0x2a9, 0x3a0,
+  0xd30, 0xc39, 0xf33, 0xe3a, 0x936, 0x83f, 0xb35, 0xa3c, 0x53c, 0x435, 0x73f, 0x636, 0x13a, 0x33, 0x339, 0x230,
+  0xe90, 0xf99, 0xc93, 0xd9a, 0xa96, 0xb9f, 0x895, 0x99c, 0x69c, 0x795, 0x49f, 0x596, 0x29a, 0x393, 0x99, 0x190,
+  0xf00, 0xe09, 0xd03, 0xc0a, 0xb06, 0xa0f, 0x905, 0x80c, 0x70c, 0x605, 0x50f, 0x406, 0x30a, 0x203, 0x109, 0x0,
+]);
+
+const TRI_TABLE = new Int32Array([
+  -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  0, 8, 3, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  0, 1, 9, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  1, 8, 3, 9, 8, 1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  1, 2, 10, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  0, 8, 3, 1, 2, 10, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  9, 2, 10, 0, 2, 9, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  2, 8, 3, 2, 10, 8, 10, 9, 8, -1, -1, -1, -1, -1, -1, -1,
+  3, 11, 2, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  0, 11, 2, 8, 11, 0, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  1, 9, 0, 2, 3, 11, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  1, 11, 2, 1, 9, 11, 9, 8, 11, -1, -1, -1, -1, -1, -1, -1,
+  3, 10, 1, 11, 10, 3, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  0, 10, 1, 0, 8, 10, 8, 11, 10, -1, -1, -1, -1, -1, -1, -1,
+  3, 9, 0, 3, 11, 9, 11, 10, 9, -1, -1, -1, -1, -1, -1, -1,
+  9, 8, 10, 10, 8, 11, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  4, 7, 8, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  4, 3, 0, 7, 3, 4, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  0, 1, 9, 8, 4, 7, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  4, 1, 9, 4, 7, 1, 7, 3, 1, -1, -1, -1, -1, -1, -1, -1,
+  1, 2, 10, 8, 4, 7, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  3, 4, 7, 3, 0, 4, 1, 2, 10, -1, -1, -1, -1, -1, -1, -1,
+  9, 2, 10, 9, 0, 2, 8, 4, 7, -1, -1, -1, -1, -1, -1, -1,
+  2, 10, 9, 2, 9, 7, 2, 7, 3, 7, 9, 4, -1, -1, -1, -1,
+  8, 4, 7, 3, 11, 2, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  11, 4, 7, 11, 2, 4, 2, 0, 4, -1, -1, -1, -1, -1, -1, -1,
+  9, 0, 1, 8, 4, 7, 2, 3, 11, -1, -1, -1, -1, -1, -1, -1,
+  4, 7, 11, 9, 4, 11, 9, 11, 2, 9, 2, 1, -1, -1, -1, -1,
+  3, 10, 1, 3, 11, 10, 7, 8, 4, -1, -1, -1, -1, -1, -1, -1,
+  1, 11, 10, 1, 4, 11, 1, 0, 4, 7, 11, 4, -1, -1, -1, -1,
+  4, 7, 8, 9, 0, 11, 9, 11, 10, 11, 0, 3, -1, -1, -1, -1,
+  4, 7, 11, 4, 11, 9, 9, 11, 10, -1, -1, -1, -1, -1, -1, -1,
+  9, 5, 4, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  9, 5, 4, 0, 8, 3, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  0, 5, 4, 1, 5, 0, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  8, 5, 4, 8, 3, 5, 3, 1, 5, -1, -1, -1, -1, -1, -1, -1,
+  1, 2, 10, 9, 5, 4, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  3, 0, 8, 1, 2, 10, 4, 9, 5, -1, -1, -1, -1, -1, -1, -1,
+  5, 2, 10, 5, 4, 2, 4, 0, 2, -1, -1, -1, -1, -1, -1, -1,
+  2, 10, 5, 3, 2, 5, 3, 5, 4, 3, 4, 8, -1, -1, -1, -1,
+  9, 5, 4, 2, 3, 11, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  0, 11, 2, 0, 8, 11, 4, 9, 5, -1, -1, -1, -1, -1, -1, -1,
+  0, 5, 4, 0, 1, 5, 2, 3, 11, -1, -1, -1, -1, -1, -1, -1,
+  2, 1, 5, 2, 5, 8, 2, 8, 11, 4, 8, 5, -1, -1, -1, -1,
+  10, 3, 11, 10, 1, 3, 9, 5, 4, -1, -1, -1, -1, -1, -1, -1,
+  4, 9, 5, 0, 8, 1, 8, 10, 1, 8, 11, 10, -1, -1, -1, -1,
+  5, 4, 0, 5, 0, 11, 5, 11, 10, 11, 0, 3, -1, -1, -1, -1,
+  5, 4, 8, 5, 8, 10, 10, 8, 11, -1, -1, -1, -1, -1, -1, -1,
+  9, 7, 8, 5, 7, 9, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  9, 3, 0, 9, 5, 3, 5, 7, 3, -1, -1, -1, -1, -1, -1, -1,
+  0, 7, 8, 0, 1, 7, 1, 5, 7, -1, -1, -1, -1, -1, -1, -1,
+  1, 5, 3, 3, 5, 7, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  9, 7, 8, 9, 5, 7, 10, 1, 2, -1, -1, -1, -1, -1, -1, -1,
+  10, 1, 2, 9, 5, 0, 5, 3, 0, 5, 7, 3, -1, -1, -1, -1,
+  8, 0, 2, 8, 2, 5, 8, 5, 7, 10, 5, 2, -1, -1, -1, -1,
+  2, 10, 5, 2, 5, 3, 3, 5, 7, -1, -1, -1, -1, -1, -1, -1,
+  7, 9, 5, 7, 8, 9, 3, 11, 2, -1, -1, -1, -1, -1, -1, -1,
+  9, 5, 7, 9, 7, 2, 9, 2, 0, 2, 7, 11, -1, -1, -1, -1,
+  2, 3, 11, 0, 1, 8, 1, 7, 8, 1, 5, 7, -1, -1, -1, -1,
+  11, 2, 1, 11, 1, 7, 7, 1, 5, -1, -1, -1, -1, -1, -1, -1,
+  9, 5, 8, 8, 5, 7, 10, 1, 3, 10, 3, 11, -1, -1, -1, -1,
+  5, 7, 0, 5, 0, 9, 7, 11, 0, 1, 0, 10, 11, 10, 0, -1,
+  11, 10, 0, 11, 0, 3, 10, 5, 0, 8, 0, 7, 5, 7, 0, -1,
+  11, 10, 5, 7, 11, 5, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  10, 6, 5, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  0, 8, 3, 5, 10, 6, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  9, 0, 1, 5, 10, 6, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  1, 8, 3, 1, 9, 8, 5, 10, 6, -1, -1, -1, -1, -1, -1, -1,
+  1, 6, 5, 2, 6, 1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  1, 6, 5, 1, 2, 6, 3, 0, 8, -1, -1, -1, -1, -1, -1, -1,
+  9, 6, 5, 9, 0, 6, 0, 2, 6, -1, -1, -1, -1, -1, -1, -1,
+  5, 9, 8, 5, 8, 2, 5, 2, 6, 3, 2, 8, -1, -1, -1, -1,
+  2, 3, 11, 10, 6, 5, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  11, 0, 8, 11, 2, 0, 10, 6, 5, -1, -1, -1, -1, -1, -1, -1,
+  0, 1, 9, 2, 3, 11, 5, 10, 6, -1, -1, -1, -1, -1, -1, -1,
+  5, 10, 6, 1, 9, 2, 9, 11, 2, 9, 8, 11, -1, -1, -1, -1,
+  6, 3, 11, 6, 5, 3, 5, 1, 3, -1, -1, -1, -1, -1, -1, -1,
+  0, 8, 11, 0, 11, 5, 0, 5, 1, 5, 11, 6, -1, -1, -1, -1,
+  3, 11, 6, 0, 3, 6, 0, 6, 5, 0, 5, 9, -1, -1, -1, -1,
+  6, 5, 9, 6, 9, 11, 11, 9, 8, -1, -1, -1, -1, -1, -1, -1,
+  5, 10, 6, 4, 7, 8, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  4, 3, 0, 4, 7, 3, 6, 5, 10, -1, -1, -1, -1, -1, -1, -1,
+  1, 9, 0, 5, 10, 6, 8, 4, 7, -1, -1, -1, -1, -1, -1, -1,
+  10, 6, 5, 1, 9, 7, 1, 7, 3, 7, 9, 4, -1, -1, -1, -1,
+  6, 1, 2, 6, 5, 1, 4, 7, 8, -1, -1, -1, -1, -1, -1, -1,
+  1, 2, 5, 5, 2, 6, 3, 0, 4, 3, 4, 7, -1, -1, -1, -1,
+  8, 4, 7, 9, 0, 5, 0, 6, 5, 0, 2, 6, -1, -1, -1, -1,
+  7, 3, 9, 7, 9, 4, 3, 2, 9, 5, 9, 6, 2, 6, 9, -1,
+  3, 11, 2, 7, 8, 4, 10, 6, 5, -1, -1, -1, -1, -1, -1, -1,
+  5, 10, 6, 4, 7, 2, 4, 2, 0, 2, 7, 11, -1, -1, -1, -1,
+  0, 1, 9, 4, 7, 8, 2, 3, 11, 5, 10, 6, -1, -1, -1, -1,
+  9, 2, 1, 9, 11, 2, 9, 4, 11, 7, 11, 4, 5, 10, 6, -1,
+  8, 4, 7, 3, 11, 5, 3, 5, 1, 5, 11, 6, -1, -1, -1, -1,
+  5, 1, 11, 5, 11, 6, 1, 0, 11, 7, 11, 4, 0, 4, 11, -1,
+  0, 5, 9, 0, 6, 5, 0, 3, 6, 11, 6, 3, 8, 4, 7, -1,
+  6, 5, 9, 6, 9, 11, 4, 7, 9, 7, 11, 9, -1, -1, -1, -1,
+  10, 4, 9, 6, 4, 10, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  4, 10, 6, 4, 9, 10, 0, 8, 3, -1, -1, -1, -1, -1, -1, -1,
+  10, 0, 1, 10, 6, 0, 6, 4, 0, -1, -1, -1, -1, -1, -1, -1,
+  8, 3, 1, 8, 1, 6, 8, 6, 4, 6, 1, 10, -1, -1, -1, -1,
+  1, 4, 9, 1, 2, 4, 2, 6, 4, -1, -1, -1, -1, -1, -1, -1,
+  3, 0, 8, 1, 2, 9, 2, 4, 9, 2, 6, 4, -1, -1, -1, -1,
+  0, 2, 4, 4, 2, 6, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  8, 3, 2, 8, 2, 4, 4, 2, 6, -1, -1, -1, -1, -1, -1, -1,
+  10, 4, 9, 10, 6, 4, 11, 2, 3, -1, -1, -1, -1, -1, -1, -1,
+  0, 8, 2, 2, 8, 11, 4, 9, 10, 4, 10, 6, -1, -1, -1, -1,
+  3, 11, 2, 0, 1, 6, 0, 6, 4, 6, 1, 10, -1, -1, -1, -1,
+  6, 4, 1, 6, 1, 10, 4, 8, 1, 2, 1, 11, 8, 11, 1, -1,
+  9, 6, 4, 9, 3, 6, 9, 1, 3, 11, 6, 3, -1, -1, -1, -1,
+  8, 11, 1, 8, 1, 0, 11, 6, 1, 9, 1, 4, 6, 4, 1, -1,
+  3, 11, 6, 3, 6, 0, 0, 6, 4, -1, -1, -1, -1, -1, -1, -1,
+  6, 4, 8, 11, 6, 8, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  7, 10, 6, 7, 8, 10, 8, 9, 10, -1, -1, -1, -1, -1, -1, -1,
+  0, 7, 3, 0, 10, 7, 0, 9, 10, 6, 7, 10, -1, -1, -1, -1,
+  10, 6, 7, 1, 10, 7, 1, 7, 8, 1, 8, 0, -1, -1, -1, -1,
+  10, 6, 7, 10, 7, 1, 1, 7, 3, -1, -1, -1, -1, -1, -1, -1,
+  1, 2, 6, 1, 6, 8, 1, 8, 9, 8, 6, 7, -1, -1, -1, -1,
+  2, 6, 9, 2, 9, 1, 6, 7, 9, 0, 9, 3, 7, 3, 9, -1,
+  7, 8, 0, 7, 0, 6, 6, 0, 2, -1, -1, -1, -1, -1, -1, -1,
+  7, 3, 2, 6, 7, 2, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  2, 3, 11, 10, 6, 8, 10, 8, 9, 8, 6, 7, -1, -1, -1, -1,
+  2, 0, 7, 2, 7, 11, 0, 9, 7, 6, 7, 10, 9, 10, 7, -1,
+  1, 8, 0, 1, 7, 8, 1, 10, 7, 6, 7, 10, 2, 3, 11, -1,
+  11, 2, 1, 11, 1, 7, 10, 6, 1, 6, 7, 1, -1, -1, -1, -1,
+  8, 9, 6, 8, 6, 7, 9, 1, 6, 11, 6, 3, 1, 3, 6, -1,
+  0, 9, 1, 11, 6, 7, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  7, 8, 0, 7, 0, 6, 3, 11, 0, 11, 6, 0, -1, -1, -1, -1,
+  7, 11, 6, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  7, 6, 11, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  3, 0, 8, 11, 7, 6, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  0, 1, 9, 11, 7, 6, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  8, 1, 9, 8, 3, 1, 11, 7, 6, -1, -1, -1, -1, -1, -1, -1,
+  10, 1, 2, 6, 11, 7, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  1, 2, 10, 3, 0, 8, 6, 11, 7, -1, -1, -1, -1, -1, -1, -1,
+  2, 9, 0, 2, 10, 9, 6, 11, 7, -1, -1, -1, -1, -1, -1, -1,
+  6, 11, 7, 2, 10, 3, 10, 8, 3, 10, 9, 8, -1, -1, -1, -1,
+  7, 2, 3, 6, 2, 7, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  7, 0, 8, 7, 6, 0, 6, 2, 0, -1, -1, -1, -1, -1, -1, -1,
+  2, 7, 6, 2, 3, 7, 0, 1, 9, -1, -1, -1, -1, -1, -1, -1,
+  1, 6, 2, 1, 8, 6, 1, 9, 8, 8, 6, 7, -1, -1, -1, -1,
+  10, 7, 6, 10, 1, 7, 1, 3, 7, -1, -1, -1, -1, -1, -1, -1,
+  10, 7, 6, 1, 7, 10, 1, 8, 7, 1, 0, 8, -1, -1, -1, -1,
+  0, 3, 7, 0, 7, 10, 0, 10, 9, 6, 10, 7, -1, -1, -1, -1,
+  7, 6, 10, 7, 10, 8, 8, 10, 9, -1, -1, -1, -1, -1, -1, -1,
+  6, 8, 4, 11, 8, 6, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  3, 6, 11, 3, 0, 6, 0, 4, 6, -1, -1, -1, -1, -1, -1, -1,
+  8, 6, 11, 8, 4, 6, 9, 0, 1, -1, -1, -1, -1, -1, -1, -1,
+  9, 4, 6, 9, 6, 3, 9, 3, 1, 11, 3, 6, -1, -1, -1, -1,
+  6, 8, 4, 6, 11, 8, 2, 10, 1, -1, -1, -1, -1, -1, -1, -1,
+  1, 2, 10, 3, 0, 11, 0, 6, 11, 0, 4, 6, -1, -1, -1, -1,
+  4, 11, 8, 4, 6, 11, 0, 2, 9, 2, 10, 9, -1, -1, -1, -1,
+  10, 9, 3, 10, 3, 2, 9, 4, 3, 11, 3, 6, 4, 6, 3, -1,
+  8, 2, 3, 8, 4, 2, 4, 6, 2, -1, -1, -1, -1, -1, -1, -1,
+  0, 4, 2, 4, 6, 2, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  1, 9, 0, 2, 3, 4, 2, 4, 6, 4, 3, 8, -1, -1, -1, -1,
+  1, 9, 4, 1, 4, 2, 2, 4, 6, -1, -1, -1, -1, -1, -1, -1,
+  8, 1, 3, 8, 6, 1, 8, 4, 6, 6, 10, 1, -1, -1, -1, -1,
+  10, 1, 0, 10, 0, 6, 6, 0, 4, -1, -1, -1, -1, -1, -1, -1,
+  4, 6, 3, 4, 3, 8, 6, 10, 3, 0, 3, 9, 10, 9, 3, -1,
+  10, 9, 4, 6, 10, 4, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  4, 9, 5, 7, 6, 11, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  0, 8, 3, 4, 9, 5, 11, 7, 6, -1, -1, -1, -1, -1, -1, -1,
+  5, 0, 1, 5, 4, 0, 7, 6, 11, -1, -1, -1, -1, -1, -1, -1,
+  11, 7, 6, 8, 3, 4, 3, 5, 4, 3, 1, 5, -1, -1, -1, -1,
+  9, 5, 4, 10, 1, 2, 7, 6, 11, -1, -1, -1, -1, -1, -1, -1,
+  6, 11, 7, 1, 2, 10, 0, 8, 3, 4, 9, 5, -1, -1, -1, -1,
+  7, 6, 11, 5, 4, 10, 4, 2, 10, 4, 0, 2, -1, -1, -1, -1,
+  3, 4, 8, 3, 5, 4, 3, 2, 5, 10, 5, 2, 11, 7, 6, -1,
+  7, 2, 3, 7, 6, 2, 5, 4, 9, -1, -1, -1, -1, -1, -1, -1,
+  9, 5, 4, 0, 8, 6, 0, 6, 2, 6, 8, 7, -1, -1, -1, -1,
+  3, 6, 2, 3, 7, 6, 1, 5, 0, 5, 4, 0, -1, -1, -1, -1,
+  6, 2, 8, 6, 8, 7, 2, 1, 8, 4, 8, 5, 1, 5, 8, -1,
+  9, 5, 4, 10, 1, 6, 1, 7, 6, 1, 3, 7, -1, -1, -1, -1,
+  1, 6, 10, 1, 7, 6, 1, 0, 7, 8, 7, 0, 9, 5, 4, -1,
+  4, 0, 10, 4, 10, 5, 0, 3, 10, 6, 10, 7, 3, 7, 10, -1,
+  7, 6, 10, 7, 10, 8, 5, 4, 10, 4, 8, 10, -1, -1, -1, -1,
+  6, 9, 5, 6, 11, 9, 11, 8, 9, -1, -1, -1, -1, -1, -1, -1,
+  3, 6, 11, 3, 0, 6, 0, 5, 6, 0, 9, 5, -1, -1, -1, -1,
+  0, 11, 8, 0, 5, 11, 0, 1, 5, 5, 6, 11, -1, -1, -1, -1,
+  6, 11, 3, 6, 3, 5, 5, 3, 1, -1, -1, -1, -1, -1, -1, -1,
+  1, 2, 10, 9, 5, 11, 9, 11, 8, 11, 5, 6, -1, -1, -1, -1,
+  0, 11, 3, 0, 6, 11, 0, 9, 6, 5, 6, 9, 1, 2, 10, -1,
+  11, 8, 5, 11, 5, 6, 8, 0, 5, 10, 5, 2, 0, 2, 5, -1,
+  6, 11, 3, 6, 3, 5, 2, 10, 3, 10, 5, 3, -1, -1, -1, -1,
+  5, 8, 9, 5, 2, 8, 5, 6, 2, 3, 8, 2, -1, -1, -1, -1,
+  9, 5, 6, 9, 6, 0, 0, 6, 2, -1, -1, -1, -1, -1, -1, -1,
+  1, 5, 8, 1, 8, 0, 5, 6, 8, 3, 8, 2, 6, 2, 8, -1,
+  1, 5, 6, 2, 1, 6, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  1, 3, 6, 1, 6, 10, 3, 8, 6, 5, 6, 9, 8, 9, 6, -1,
+  10, 1, 0, 10, 0, 6, 9, 5, 0, 5, 6, 0, -1, -1, -1, -1,
+  0, 3, 8, 5, 6, 10, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  10, 5, 6, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  11, 5, 10, 7, 5, 11, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  11, 5, 10, 11, 7, 5, 8, 3, 0, -1, -1, -1, -1, -1, -1, -1,
+  5, 11, 7, 5, 10, 11, 1, 9, 0, -1, -1, -1, -1, -1, -1, -1,
+  10, 7, 5, 10, 11, 7, 9, 8, 1, 8, 3, 1, -1, -1, -1, -1,
+  11, 1, 2, 11, 7, 1, 7, 5, 1, -1, -1, -1, -1, -1, -1, -1,
+  0, 8, 3, 1, 2, 7, 1, 7, 5, 7, 2, 11, -1, -1, -1, -1,
+  9, 7, 5, 9, 2, 7, 9, 0, 2, 2, 11, 7, -1, -1, -1, -1,
+  7, 5, 2, 7, 2, 11, 5, 9, 2, 3, 2, 8, 9, 8, 2, -1,
+  2, 5, 10, 2, 3, 5, 3, 7, 5, -1, -1, -1, -1, -1, -1, -1,
+  8, 2, 0, 8, 5, 2, 8, 7, 5, 10, 2, 5, -1, -1, -1, -1,
+  9, 0, 1, 5, 10, 3, 5, 3, 7, 3, 10, 2, -1, -1, -1, -1,
+  9, 8, 2, 9, 2, 1, 8, 7, 2, 10, 2, 5, 7, 5, 2, -1,
+  1, 3, 5, 3, 7, 5, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  0, 8, 7, 0, 7, 1, 1, 7, 5, -1, -1, -1, -1, -1, -1, -1,
+  9, 0, 3, 9, 3, 5, 5, 3, 7, -1, -1, -1, -1, -1, -1, -1,
+  9, 8, 7, 5, 9, 7, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  5, 8, 4, 5, 10, 8, 10, 11, 8, -1, -1, -1, -1, -1, -1, -1,
+  5, 0, 4, 5, 11, 0, 5, 10, 11, 11, 3, 0, -1, -1, -1, -1,
+  0, 1, 9, 8, 4, 10, 8, 10, 11, 10, 4, 5, -1, -1, -1, -1,
+  10, 11, 4, 10, 4, 5, 11, 3, 4, 9, 4, 1, 3, 1, 4, -1,
+  2, 5, 1, 2, 8, 5, 2, 11, 8, 4, 5, 8, -1, -1, -1, -1,
+  0, 4, 11, 0, 11, 3, 4, 5, 11, 2, 11, 1, 5, 1, 11, -1,
+  0, 2, 5, 0, 5, 9, 2, 11, 5, 4, 5, 8, 11, 8, 5, -1,
+  9, 4, 5, 2, 11, 3, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  2, 5, 10, 3, 5, 2, 3, 4, 5, 3, 8, 4, -1, -1, -1, -1,
+  5, 10, 2, 5, 2, 4, 4, 2, 0, -1, -1, -1, -1, -1, -1, -1,
+  3, 10, 2, 3, 5, 10, 3, 8, 5, 4, 5, 8, 0, 1, 9, -1,
+  5, 10, 2, 5, 2, 4, 1, 9, 2, 9, 4, 2, -1, -1, -1, -1,
+  8, 4, 5, 8, 5, 3, 3, 5, 1, -1, -1, -1, -1, -1, -1, -1,
+  0, 4, 5, 1, 0, 5, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  8, 4, 5, 8, 5, 3, 9, 0, 5, 0, 3, 5, -1, -1, -1, -1,
+  9, 4, 5, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  4, 11, 7, 4, 9, 11, 9, 10, 11, -1, -1, -1, -1, -1, -1, -1,
+  0, 8, 3, 4, 9, 7, 9, 11, 7, 9, 10, 11, -1, -1, -1, -1,
+  1, 10, 11, 1, 11, 4, 1, 4, 0, 7, 4, 11, -1, -1, -1, -1,
+  3, 1, 4, 3, 4, 8, 1, 10, 4, 7, 4, 11, 10, 11, 4, -1,
+  4, 11, 7, 9, 11, 4, 9, 2, 11, 9, 1, 2, -1, -1, -1, -1,
+  9, 7, 4, 9, 11, 7, 9, 1, 11, 2, 11, 1, 0, 8, 3, -1,
+  11, 7, 4, 11, 4, 2, 2, 4, 0, -1, -1, -1, -1, -1, -1, -1,
+  11, 7, 4, 11, 4, 2, 8, 3, 4, 3, 2, 4, -1, -1, -1, -1,
+  2, 9, 10, 2, 7, 9, 2, 3, 7, 7, 4, 9, -1, -1, -1, -1,
+  9, 10, 7, 9, 7, 4, 10, 2, 7, 8, 7, 0, 2, 0, 7, -1,
+  3, 7, 10, 3, 10, 2, 7, 4, 10, 1, 10, 0, 4, 0, 10, -1,
+  1, 10, 2, 8, 7, 4, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  4, 9, 1, 4, 1, 7, 7, 1, 3, -1, -1, -1, -1, -1, -1, -1,
+  4, 9, 1, 4, 1, 7, 0, 8, 1, 8, 7, 1, -1, -1, -1, -1,
+  4, 0, 3, 7, 4, 3, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  4, 8, 7, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  9, 10, 8, 10, 11, 8, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  3, 0, 9, 3, 9, 11, 11, 9, 10, -1, -1, -1, -1, -1, -1, -1,
+  0, 1, 10, 0, 10, 8, 8, 10, 11, -1, -1, -1, -1, -1, -1, -1,
+  3, 1, 10, 11, 3, 10, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  1, 2, 11, 1, 11, 9, 9, 11, 8, -1, -1, -1, -1, -1, -1, -1,
+  3, 0, 9, 3, 9, 11, 1, 2, 9, 2, 11, 9, -1, -1, -1, -1,
+  0, 2, 11, 8, 0, 11, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  3, 2, 11, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  2, 3, 8, 2, 8, 10, 10, 8, 9, -1, -1, -1, -1, -1, -1, -1,
+  9, 10, 2, 0, 9, 2, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  2, 3, 8, 2, 8, 10, 0, 1, 8, 1, 10, 8, -1, -1, -1, -1,
+  1, 10, 2, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  1, 3, 8, 9, 1, 8, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  0, 9, 1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  0, 3, 8, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+  -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+]);
+
+const TRI_TABLE_STRIDE = 16;
+
+const EDGE_VERTEX_MAP: ReadonlyArray<readonly [number, number]> = [
+  [0, 1],
+  [1, 2],
+  [2, 3],
+  [3, 0],
+  [4, 5],
+  [5, 6],
+  [6, 7],
+  [7, 4],
+  [0, 4],
+  [1, 5],
+  [2, 6],
+  [3, 7],
+];
+
+const VERTEX_OFFSETS: ReadonlyArray<readonly [number, number, number]> = [
+  [0, 0, 0],
+  [1, 0, 0],
+  [1, 1, 0],
+  [0, 1, 0],
+  [0, 0, 1],
+  [1, 0, 1],
+  [1, 1, 1],
+  [0, 1, 1],
+];
+
+export function computeMarchingCubes(options: MarchingCubesOptions): MarchingCubesResult {
+  const normalized = normalizeField3D(options.field);
+  const grid = normalized.grid;
+  const cellSize = normalized.cellSize;
+  validateGrid3D(grid);
+
+  const threshold = options.threshold ?? 0;
+  const depth = grid.length;
+  const rows = grid[0].length;
+  const cols = grid[0][0].length;
+  const triangles: Triangle[] = [];
+  const vertexPositions: (Vector3 | null)[] = Array.from({ length: 12 }, () => null);
+
+  for (let z = 0; z < depth - 1; z += 1) {
+    for (let y = 0; y < rows - 1; y += 1) {
+      for (let x = 0; x < cols - 1; x += 1) {
+        const cubeValues = getCubeValues(grid, x, y, z);
+        for (let i = 0; i < vertexPositions.length; i += 1) {
+          vertexPositions[i] = null;
+        }
+        let cubeIndex = 0;
+        if (cubeValues[0] >= threshold) cubeIndex |= 1;
+        if (cubeValues[1] >= threshold) cubeIndex |= 2;
+        if (cubeValues[2] >= threshold) cubeIndex |= 4;
+        if (cubeValues[3] >= threshold) cubeIndex |= 8;
+        if (cubeValues[4] >= threshold) cubeIndex |= 16;
+        if (cubeValues[5] >= threshold) cubeIndex |= 32;
+        if (cubeValues[6] >= threshold) cubeIndex |= 64;
+        if (cubeValues[7] >= threshold) cubeIndex |= 128;
+
+        const edges = EDGE_TABLE[cubeIndex];
+        if (edges === 0) {
+          continue;
+        }
+
+        for (let edge = 0; edge < 12; edge += 1) {
+          if ((edges & (1 << edge)) !== 0) {
+            const [aIndex, bIndex] = EDGE_VERTEX_MAP[edge];
+            const v1 = cubeValues[aIndex];
+            const v2 = cubeValues[bIndex];
+            const t = interpolate(v1, v2, threshold);
+            const [ax, ay, az] = VERTEX_OFFSETS[aIndex];
+            const [bx, by, bz] = VERTEX_OFFSETS[bIndex];
+            vertexPositions[edge] = {
+              x: (x + lerp(ax, bx, t)) * cellSize.x,
+              y: (y + lerp(ay, by, t)) * cellSize.y,
+              z: (z + lerp(az, bz, t)) * cellSize.z,
+            };
+          }
+        }
+
+        const triOffset = cubeIndex * TRI_TABLE_STRIDE;
+        for (let i = 0; i < TRI_TABLE_STRIDE; i += 3) {
+          const edgeA = TRI_TABLE[triOffset + i];
+          if (edgeA === -1) {
+            break;
+          }
+          const edgeB = TRI_TABLE[triOffset + i + 1];
+          const edgeC = TRI_TABLE[triOffset + i + 2];
+          const pointA = vertexPositions[edgeA];
+          const pointB = vertexPositions[edgeB];
+          const pointC = vertexPositions[edgeC];
+          if (!pointA || !pointB || !pointC) {
+            continue;
+          }
+          triangles.push({ a: pointA, b: pointB, c: pointC });
+        }
+      }
+    }
+  }
+
+  return { triangles };
+}
+
+function normalizeField3D(
+  field: ScalarField3D | ReadonlyArray<ReadonlyArray<ReadonlyArray<number>>>
+): { grid: ReadonlyArray<ReadonlyArray<ReadonlyArray<number>>>; cellSize: { x: number; y: number; z: number } } {
+  if (Array.isArray(field)) {
+    return { grid: field, cellSize: { x: 1, y: 1, z: 1 } };
+  }
+  const scalarField = field as ScalarField3D;
+  const size = scalarField.cellSize;
+  if (typeof size === 'number' || size === undefined) {
+    const scalar = size ?? 1;
+    return { grid: scalarField.data, cellSize: { x: scalar, y: scalar, z: scalar } };
+  }
+  return { grid: scalarField.data, cellSize: size };
+}
+
+function validateGrid3D(grid: ReadonlyArray<ReadonlyArray<ReadonlyArray<number>>>): void {
+  if (grid.length < 2) {
+    throw new Error('field must contain at least two slices.');
+  }
+  const rowCount = grid[0]?.length ?? 0;
+  if (rowCount < 2) {
+    throw new Error('field slices must contain at least two rows.');
+  }
+  const colCount = grid[0]?.[0]?.length ?? 0;
+  if (colCount < 2) {
+    throw new Error('field rows must contain at least two columns.');
+  }
+  for (let z = 0; z < grid.length; z += 1) {
+    const slice = grid[z];
+    if (slice.length !== rowCount) {
+      throw new Error('field slices must share the same row count.');
+    }
+    for (let y = 0; y < slice.length; y += 1) {
+      if (slice[y].length !== colCount) {
+        throw new Error('field rows must share the same column count.');
+      }
+    }
+  }
+}
+
+function getCubeValues(
+  grid: ReadonlyArray<ReadonlyArray<ReadonlyArray<number>>>,
+  x: number,
+  y: number,
+  z: number
+): CubeValues {
+  return [
+    grid[z][y][x],
+    grid[z][y][x + 1],
+    grid[z][y + 1][x + 1],
+    grid[z][y + 1][x],
+    grid[z + 1][y][x],
+    grid[z + 1][y][x + 1],
+    grid[z + 1][y + 1][x + 1],
+    grid[z + 1][y + 1][x],
+  ];
+}
+
+function interpolate(v1: number, v2: number, threshold: number): number {
+  const denom = v2 - v1;
+  if (Math.abs(denom) < 1e-12) {
+    return 0.5;
+  }
+  return clamp((threshold - v1) / denom, 0, 1);
+}
+
+function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  if (value < min) {
+    return min;
+  }
+  if (value > max) {
+    return max;
+  }
+  return value;
+}
diff --git a/tests/index.test.ts b/tests/index.test.ts
index 793adea..ec636a3 100644
--- a/tests/index.test.ts
+++ b/tests/index.test.ts
@@ -34,6 +34,7 @@ describe('package entry point', () => {
     expect(examples.visual.mixRgbColors).toBe('examples/color.ts');
     expect(examples.visual.computeForceDirectedLayout).toBe('examples/forceDirected.ts');
     expect(examples.visual.computeMarchingSquares).toBe('examples/marchingSquares.ts');
+    expect(examples.visual.computeMarchingCubes).toBe('examples/marchingCubes.ts');
     expect(examples.gameplay.createDeltaTimeManager).toBe('examples/deltaTime.ts');
     expect(examples.gameplay.createFixedTimestepLoop).toBe('examples/fixedTimestep.ts');
     expect(examples.gameplay.createCamera2D).toBe('examples/camera2D.ts');
@@ -186,6 +187,7 @@ describe('package entry point', () => {
       | 'mixRgbColors'
       | 'computeForceDirectedLayout'
       | 'computeMarchingSquares'
+      | 'computeMarchingCubes'
     >();
   });
 });
diff --git a/tests/marchingCubes.test.ts b/tests/marchingCubes.test.ts
new file mode 100644
index 0000000..cfdebaa
--- /dev/null
+++ b/tests/marchingCubes.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+
+import { computeMarchingCubes } from '../src/index.js';
+import type { MarchingCubesResult } from '../src/index.js';
+
+describe('computeMarchingCubes', () => {
+  it('extracts triangles around a spherical scalar field', () => {
+    const size = 4;
+    const field: number[][][] = [];
+    const radius = 1.5;
+    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.sqrt(dx * dx + dy * dy + dz * dz));
+        }
+        slice.push(row);
+      }
+      field.push(slice);
+    }
+
+    const result: MarchingCubesResult = computeMarchingCubes({ field, threshold: 0 });
+    expect(result.triangles.length).toBeGreaterThan(0);
+
+    for (const triangle of result.triangles) {
+      for (const vertex of [triangle.a, triangle.b, triangle.c]) {
+        expect(vertex.x).toBeGreaterThanOrEqual(0);
+        expect(vertex.y).toBeGreaterThanOrEqual(0);
+        expect(vertex.z).toBeGreaterThanOrEqual(0);
+        expect(vertex.x).toBeLessThanOrEqual(size - 1);
+        expect(vertex.y).toBeLessThanOrEqual(size - 1);
+        expect(vertex.z).toBeLessThanOrEqual(size - 1);
+      }
+    }
+  });
+
+  it('supports non-uniform cell sizes', () => {
+    const field = [
+      [
+        [0, 1],
+        [0, 1],
+      ],
+      [
+        [1, 0],
+        [1, 0],
+      ],
+    ];
+
+    const result: MarchingCubesResult = computeMarchingCubes({
+      field: { data: field, cellSize: { x: 2, y: 3, z: 4 } },
+      threshold: 0.5,
+    });
+
+    const maxX = (field[0][0].length - 1) * 2;
+    const maxY = (field[0].length - 1) * 3;
+    const maxZ = (field.length - 1) * 4;
+    for (const triangle of result.triangles) {
+      for (const vertex of [triangle.a, triangle.b, triangle.c]) {
+        expect(vertex.x).toBeGreaterThanOrEqual(0);
+        expect(vertex.x).toBeLessThanOrEqual(maxX);
+        expect(vertex.y).toBeGreaterThanOrEqual(0);
+        expect(vertex.y).toBeLessThanOrEqual(maxY);
+        expect(vertex.z).toBeGreaterThanOrEqual(0);
+        expect(vertex.z).toBeLessThanOrEqual(maxZ);
+      }
+    }
+  });
+
+  it('validates field dimensions and shape', () => {
+    expect(() => computeMarchingCubes({ field: [[[1]]] })).toThrow('field must contain at least two slices.');
+    expect(() =>
+      computeMarchingCubes({
+        field: {
+          data: [
+            [
+              [0, 0],
+              [0, 0],
+            ],
+            [[0]],
+          ],
+        },
+      })
+    ).toThrow('field slices must share the same row count.');
+  });
+});