Marching Squares Metaballs Stay Smooth

Marching squares metaballs turn a handful of moving points into liquid contours by sampling a scalar field and extracting one threshold. The appealing blob is the easy part; the craft lives in resolving ambiguous cells, stitching loops, stabilizing motion, and staying inside a frame budget.

The contour is treated as both algorithm and drawing material. The proposed receipt includes field equation, threshold, grid spacing, ambiguous-case rule, interpolation method, topology fixtures, path hash, and performance trace.

The method connects scalar field contours, isoline extraction, implicit surfaces, and liquid shapes once each while keeping one intent: reliable smooth blob geometry. That vocabulary supports the article's marching squares metaballs decision without creating a second intent.

1. Field
2. Threshold
3. Cases
4. Loops

Marching squares metaballs begin with a field

Each source contributes influence at a sample point, and the sum becomes geometry only relative to a threshold. The d3-contour source provides a production implementation context for contour generation on sampled scalar grids. The scalar field is the geometry's source of truth, and its threshold explains why identical source points can produce islands or one fused mass. A proposed review of “Marching squares metaballs begin with a field” has four inspectable moves.

• Choose a bounded influence equation
• Protect the zero-distance case
• Normalize coordinates and source weights
• Decide where the field stops mattering

The proposed evidence for marching squares metaballs begin with a field is field values at a small grid of hand-computable points. The marching squares metaballs begin with a field receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this marching squares metaballs decision is tuning the contour without documenting the underlying influence. If tuning the contour without documenting the underlying influence occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is all samples remain finite and reproduce from serialized sources. Promotion under “all samples remain finite and reproduce from serialized sources” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

Encode the sixteen cases

Four corner comparisons form a compact local topology code whose edge crossings can be tested exhaustively. The scikit-image contour example demonstrates constant-value contour extraction and calls out ambiguous diagonal cases. An exhaustive sixteen-row case table is small enough to verify completely and valuable enough to prevent rotated-edge mistakes. A proposed review of “Encode the sixteen cases” has four inspectable moves.

• Fix corner ordering
• Fix bit significance
• Map cases to edge pairs
• Keep complements orientation-consistent

The proposed evidence for encode the sixteen cases is a table-driven test across all sixteen inputs. The encode the sixteen cases receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this marching squares metaballs decision is rotating a case mentally and reversing one edge. If rotating a case mentally and reversing one edge occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is every code yields the declared number and orientation of segments. Promotion under “every code yields the declared number and orientation of segments” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

Art-direct the threshold

The iso-value determines whether sources remain islands, touch as delicate bridges, or fuse into one heavy silhouette. The SVG specification defines the closed path output, fill rules, and accessible vector presentation used by the final artwork. Threshold contact sheets make topology an art-direction decision by showing loop count, holes, and visual weight over the same field. A proposed review of “Art-direct the threshold” has four inspectable moves.

• Hold source positions fixed
• Sweep a narrow threshold range
• Count loops and holes
• Name the visual consequence

The proposed evidence for art-direct the threshold is topology and enclosed area beside each specimen. The art-direct the threshold receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this marching squares metaballs decision is choosing a threshold by one attractive frame. If choosing a threshold by one attractive frame occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is select a value whose topology stays intentional across the motion range. Promotion under “select a value whose topology stays intentional across the motion range” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

Signal	Decision	Evidence
τ 0.7	Islands	5 loops
τ 1.0	Liquid	2 loops
τ 1.4	Merged	1 heavy mass

Test ambiguous cells first

Diagonal high corners can connect in two plausible ways, and an inconsistent choice creates flicker or a topological pop. Diagonal cases should be tested first because an unstable tie-breaker becomes visible as contour flicker during motion. A proposed review of “Test ambiguous cells first” has four inspectable moves.

• Create both diagonal fixtures
• Use a declared center-value decider
• Test complement symmetry
• Repeat near the tie boundary

The proposed evidence for test ambiguous cells first is stable connectivity under small field perturbations. The test ambiguous cells first receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this marching squares metaballs decision is choosing a branch from iteration order. If choosing a branch from iteration order occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is the same sampled cell always resolves from its documented scalar evidence. Promotion under “the same sampled cell always resolves from its documented scalar evidence” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

Runnable artifact. Save this bounded specimen as metaballs-marching-squares.test.mjs and run node --test metaballs-marching-squares.test.mjs. Expected result: PASS: cell bits encode all corners.

import assert from "node:assert/strict";
import test from "node:test";
const code = (values, threshold) => values.reduce((bits, value, i) => bits | (value >= threshold ? 1 << i : 0), 0);
test("encodes case index", () => {
  assert.equal(code([1,0,1,0], .5), 5);
  assert.equal(code([1,1,1,1], .5), 15);
  console.log("PASS: cell bits encode all corners");
});

Interpolate edge crossings

Midpoint segments expose the grid; linear interpolation uses the two corner values to place the threshold more faithfully. Edge interpolation removes much of the grid signature without moving the boundary away from the sampled threshold evidence. A proposed review of “Interpolate edge crossings” has four inspectable moves.

• Guard equal endpoint values
• Clamp interpolation factors
• Compare coarse and fine grids
• Retain raw crossings for debugging

The proposed evidence for interpolate edge crossings is contour distance against a high-resolution reference. The interpolate edge crossings receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this marching squares metaballs decision is adding a smoothing filter that moves the threshold boundary. If adding a smoothing filter that moves the threshold boundary occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is interpolation reduces stair steps without violating the sampled field. Promotion under “interpolation reduces stair steps without violating the sampled field” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

Stitch deterministic loops

A pile of valid segments is not yet an SVG path with stable orientation, holes, and edit points. Stitching must conserve every segment; silently dropping an awkward fragment makes the final loop smooth by falsifying its source. A proposed review of “Stitch deterministic loops” has four inspectable moves.

• Quantize edge identities consistently
• Walk unused segments
• Close only matching endpoints
• Orient outer and inner loops

The proposed evidence for stitch deterministic loops is segment conservation and closed-loop assertions. The stitch deterministic loops receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this marching squares metaballs decision is dropping short pieces that are difficult to join. If dropping short pieces that are difficult to join occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is every emitted segment belongs to exactly one closed or explicitly clipped contour. Promotion under “every emitted segment belongs to exactly one closed or explicitly clipped contour” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

1. SampleSample

   Evaluate the field on a bounded grid.

2. ClassifyClassify

   Encode four threshold comparisons into a case index.

3. InterpolateInterpolate

   Place crossings between corner samples.

4. StitchStitch

   Join segments into closed, oriented paths.

Keep motion topologically calm

Moving sources can cross threshold boundaries between frames, so temporal coherence needs more than drawing each frame independently. Temporal calm comes from deterministic connectivity and logged merge events, not from smoothing coordinates after topology has flipped. A proposed review of “Keep motion topologically calm” has four inspectable moves.

• Use fixed source IDs
• Limit velocity near merge events
• Track loop area and count
• Interpolate display state rather than topology guesses

The proposed evidence for keep motion topologically calm is frame-to-frame path distance and topology event logs. The keep motion topologically calm receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this marching squares metaballs decision is smoothing coordinates after inconsistent connectivity. If smoothing coordinates after inconsistent connectivity occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is every merge or split is explainable by the sampled field rather than unstable tie-breaking. Promotion under “every merge or split is explainable by the sampled field rather than unstable tie-breaking” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

Budget grid resolution

Finer grids improve geometric fidelity while multiplying field evaluations, allocation, and path points. Grid resolution is a fidelity budget whose useful point is the coarsest responsive field with acceptable contour error. A proposed review of “Budget grid resolution” has four inspectable moves.

• Measure several cell sizes
• Cull inactive regions
• Reuse typed buffers
• Reduce resolution before dropping input responsiveness

The proposed evidence for budget grid resolution is p95 extraction time versus contour error. The budget grid resolution receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this marching squares metaballs decision is choosing the finest grid that fits one desktop screenshot. If choosing the finest grid that fits one desktop screenshot occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is ship the coarsest grid whose error is visually acceptable across supported viewports. Promotion under “ship the coarsest grid whose error is visually acceptable across supported viewports” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

Keep the boundary visible

Keep the field, case table, ambiguity rule, interpolation, and loop stitcher explicit. Liquid character emerges from those deterministic geometric decisions, not from hiding them under a blur.

Threshold and resolution are art-direction controls with topology and performance consequences. Preserve the rejected specimens and ambiguous fixtures; they explain why the chosen contour feels calm.

Continue through four related field notes: canvas blend modes, WebGPU generative art, SDF typography, CSS masking. Each extends the marching squares metaballs method without changing this article's single search intent.