Wave 3 A/B — what supersampling actually looks like (and why lanczos is out)

[thorwhalen]

Wave 3 changes what every frame looks like, and the case for it has so far been made
entirely in numbers. Here are the pictures behind them, so the decision can be made by
looking as well as by reading.

Nothing here is shipped. Supersampling will land opt-in, and the default flip is a
separate one-line PR that should not happen until someone has actually looked at this
page. That is what it is for.

Every image is four panels: as it renders today, then the supersampled render brought
back to size three different ways. Regenerate any of them with one command — see
How these were made at the bottom.

---

1. promote_demo — the character rig, and the clearest result

Look at the hairline and the eyebrows. Today's render (panel 1) is soft and smeared;
that is not artistic intent, it is the SVG sprite being rasterised at 1x and then
stretched. At k=2 box (panel 3) the same art comes out crisp, because the sprite
rasterises at 2x and is resolved down.

	edge width	distinct colours
k=1 (today)	5.637 px	1213
k=2 nearest	3.693 px	1117
k=2 box	3.677 px	932
k=2 lanczos	5.584 px	1346

This is the biggest single-scene improvement in the wave — a 35% narrower edge band —
and it is on the descriptor path, which is the path an illustrator's art actually
travels. It is also the exact path the existing disabled_aa lever is blind to, so
nothing in the instrument has ever been able to see this before.

Panel 4 is why the epic's specified filter is refused: look for the pale halo sitting
just above each eyebrow. That is lanczos's negative lobe ringing.

---

2. aa_probe — diagonals, where gradation is visible

The diagonal edge is where you can see gradation being added rather than
smeared. Panel 2 (nearest) is the harsh control — sub-samples discarded, so the
staircase is at its worst. Panel 3 (box) has visibly more steps along the same
diagonal, at almost the same band width. Panel 4 has lost the edge.

	edge width	distinct colours
k=1 (today)	2.881 px	8
k=2 nearest	2.325 px	7
k=2 box	3.095 px	22
k=2 lanczos	4.188 px	281

8 → 22 colours for +7% band width is the whole thesis. Lanczos's 281 colours are not
gradation, they are ringing overshoot — which is exactly why no single number can
adjudicate this and the pair has to.

---

3. saturated_outline — hard black outlines, the target idiom

Panels 1–3 look nearly identical here on purpose: this scene is all axis-aligned
rectangles, and an axis-aligned edge has nothing to anti-alias. That is a useful
negative — supersampling is not silently changing art that has no diagonals.

Panel 4 is not identical. The black outlines have grey ghosts either side.

	edge width
k=1 (today)	2.368 px
k=2 box	2.492 px
k=2 lanczos	7.313 px

Lanczos triples the edge band on the scene closest to the style this whole epic is
aiming at. That single number is what took the brief's specified filter off the table.

---

4. The rest

single_character, multi_shot, graded_field — click to expand

scene	k=1	k=2 box	k=2 lanczos
single_character	2.092 px / 34 col	2.146 px / 102 col	4.044 px / 449 col
multi_shot	2.331 px / 36 col	2.449 px / 103 col	4.191 px / 520 col
graded_field	2.604 px / 120 col	2.812 px / 132 col	3.891 px / 333 col

Same shape every time: box roughly triples the colour count for a 3–8% wider band;
lanczos doubles the band.

Full frames (not magnified) are beside each zoom sheet in the same directory, if you want
to confirm nothing moved except the edges.

---

What I would like your eye on

1. Is promote_demo panel 3 better than panel 1? I think obviously yes, but it is
   the single biggest visible change and it is a taste call, not a measurement.
2. Is the +3–8% wider band on the other scenes acceptable? The measured ceiling says
   that widening is convergence toward the correct value, not softening — k=2 gets
   57–97% of the way from today's value to where the edge converges at k≥4. But "correct"
   and "what I want it to look like" are different questions and only one of them is mine.
3. Anything in panel 2 (nearest) that looks better to you than panel 3 (box)? If
   so I have the trade backwards somewhere.

---

How these were made

The generator is committed at misc/bench/wave3_ab.py:

python misc/bench/wave3_ab.py                       # every scene, k=2
python misc/bench/wave3_ab.py --k 3 promote_demo    # one scene, deeper
python misc/bench/wave3_ab.py --zoom 10 --out /tmp  # bigger magnification

The load-bearing part is thirty lines. It renders through the same seam the
disabled_aa bench lever uses — copy the staged runtime, patch the copy, rebind
render.runtime_dir — so the shipped runtime.js is never written to:

@contextmanager
def supersampled_runtime(k: int):
    staged = Path(tempfile.mkdtemp(prefix="an-wave3-ab-")) / "runtime"
    shutil.copytree(runtime_dir(), staged)
    source = (staged / "runtime.js").read_text(encoding="utf-8")
    (staged / "runtime.js").write_text(
        source.replace(
            APP_OPEN, f"{APP_OPEN}\n            resolution: {k}, autoDensity: false,"
        ),
        encoding="utf-8",
    )
    original = render.runtime_dir
    render.runtime_dir = lambda: staged
    try:
        yield
    finally:
        render.runtime_dir = original
        shutil.rmtree(staged.parent, ignore_errors=True)

autoDensity: false is the entire finding. With it true, Pixi sets the canvas CSS
size to the logical size and Chromium composites the 2x backbuffer down before the
screenshot ever happens — a blind downscale, no filter choice, no record that it
occurred. Measured, rendering a 320x240 scene:

Application options	PNG on disk
today (neither key set)	320x240
resolution: 2, autoDensity: false	640x480
resolution: 2, autoDensity: true	320x240

The option whose name most suggests it is the right one is the one that silently
reintroduces the failure the epic warned about for device_scale_factor.

The box resolve is a plain block mean, which at an integer ratio is the
supersample resolve rather than an approximation of one — no resampler, no filter to
defend, and no new dependency:

n, h, w, c = frames.shape
blocks = frames.reshape(n, h // k, k, w // k, k, c).astype(np.float64)
resolved = np.rint(blocks.mean(axis=(2, 4))).clip(0, 255).astype(np.uint8)

The crop is picked by edge-mask density via a summed-area table, not by eye, so the
zoom is reproducible and nobody gets to choose a flattering corner.

---

Full measured record: misc/docs/wave3_research.md.
Decisions of record: #9 comment.
Images are committed and stay committed. I originally planned to drop them before the
branch landed, on sdist-weight grounds — that was wrong twice over: a squash merge makes
these commits non-ancestors of main, so the pinned URLs would then depend on GitHub
keeping PR refs alive, and 228 KB is far under this repo's own stated revisit trigger
(a corpus over 20 MB). Evidence for a decision is what misc/ is for. The generator
regenerates them in about a minute either way.