an.media.supersample#

Render bigger, then resolve back exactly — the supersample knob’s two halves.

Engine-independent: any engine whose frames come back k times the declared size is resolved here, in the frame stage (an.engines.capture). Moved from an/adapters/cutout/supersample.py (an#247), which re-exports it. The first paragraph below is about the stage engine, whose PixiJS options are where the k-times backbuffer comes from; it stays here because it is the reason the resolve exists at all.

`autoDensity: false` is the whole plumbing finding, and it is load-bearing. resolution: k alone reproduces the failure it exists to avoid: with autoDensity: true PixiJS sets the canvas CSS size to the logical size, so Chromium composites the k-times backbuffer down before the screenshot — a blind browser downscale, no filter choice, no record that it happened. Measured on a declared 320x240 scene: neither key -> 320x240 PNGs; resolution: 2, autoDensity: false -> 640x480; resolution: 2, autoDensity: true -> 320x240. It is the option whose name most suggests it is the right one.

**The resolve is an exact k x k block mean, and calling it a filter would be wrong** — at an integer ratio it is the supersample resolve. Measured against the alternatives on all six corpus scenes: PIL’s BOX agrees with it to four decimals, and lanczos triples the edge band on the most idiom-like scene (+208.8% on saturated_outline), because its negative lobes ring on hard-edged flat fills. An ffmpeg-side -vf scale is refused for a second, independent reason: it would move x264_argv, refusing every encode-side metric, and retire the cross-arch verdict’s load-bearing “ffmpeg never touches a frame” clause.

**Why PIL here and not an.bench.png.** The bench’s codec exists so a committed golden is a function of the pixel data alone rather than of Chromium’s libpng settings — a goal about files that get committed and diffed, which render-path frames are not. And it is the wrong tool for this job by an order of magnitude: Chromium’s screenshots are Paeth-filtered on ~87% of rows (measured: 209 of 240), which takes its scalar unfilter path at 416 ns/px against PIL’s 31 ns/px. Extrapolated to a 3840x2160 supersampled frame that is **3.46 s of decoding per frame** versus 256 ms — more than the render itself costs. Pillow reaches every install through tituli, a core dependency; it is still imported lazily, below the early return, so the off path needs nothing.

Module Attributes

NO_SUPERSAMPLE

The factor at which every code path here is a no-op rather than merely cheap.

Functions

`block_mean_resolve`(frame, factor)	`(Hk, Wk, C)` uint8 -> `(H, W, C)` uint8, by an exact `k x k` mean.
`check_factor`(factor)	Validate a supersample factor, or refuse with the reason.
`resolve_png_bytes`(data, *, factor)	Decode a screenshot, block-mean it down by `factor`, re-encode.

Exceptions

SupersampleError

A supersample factor or frame that cannot be resolved exactly.

an.media.supersample.NO_SUPERSAMPLE: int = 1#: The factor at which every code path here is a no-op rather than merely cheap. Aliased from an.base.DEFAULT_SUPERSAMPLE rather than restated: the default and the off-switch are the same fact, and two copies of a fact drift.

exception an.media.supersample.SupersampleError[source]#

Bases: ValueError

A supersample factor or frame that cannot be resolved exactly.

an.media.supersample.block_mean_resolve(frame, factor)[source]#

(H*k, W*k, C) uint8 -> (H, W, C) uint8, by an exact k x k mean.

Two-step, summing rows and then columns in uint16, rather than the obvious reshape(...).astype(float64).mean(axis=(1, 3)). The two agree bit for bit — asserted exhaustively over every possible 2x2 block, and on real frames — and the two-step form is 2.3x faster at 1080p (111.7 ms against 262.0 ms), because the cost here is the strided reduce and the 64-bit temporary, not the arithmetic.

Rounding is spelled out rather than inherited: np.rint is banker’s rounding, so a block averaging exactly .5 goes to the EVEN neighbour. Getting that wrong changes one code value on every half-block, which is invisible in a picture and moves every golden.

Return type:: Any

>>> import numpy as np
>>> f = np.array([[0, 0, 1, 2], [0, 4, 1, 2]], np.uint8)[..., None].repeat(3, -1)
>>> block_mean_resolve(f, 2)[0, :, 0].tolist()
[1, 2]
>>> block_mean_resolve(f, 1) is f
True

an.media.supersample.check_factor(factor)[source]#

Validate a supersample factor, or refuse with the reason.

Return type:: int

>>> check_factor(1), check_factor(2)
(1, 2)
>>> check_factor(0)
Traceback (most recent call last):
  ...
an.media.supersample.SupersampleError: supersample must be >= 1, got 0

an.media.supersample.resolve_png_bytes(data, *, factor)[source]#

Decode a screenshot, block-mean it down by factor, re-encode.

Returns data unchanged at factor == 1, so the un-supersampled path keeps Chromium’s own bytes and pays nothing at all — which is what makes this knob free when it is off.

The early return sits above the imports deliberately. “Off is free” should mean free of the dependency too: the default path must not need Pillow merely to decide it has nothing to do. (Found in CI, when Pillow came only with the cutout extra and the default lane did not install it.)

Return type:: bytes