Frame every model in the tour, and measure that it does

The showcase is the one deliverable a still render cannot check, and until now
the only way to check it was to watch it -- which is how a model half out of
frame gets shipped. `__probe.framing()` projects the current model's bounding
box into the frame and reports the worst corner in normalised device
coordinates: 0 is comfortably inside, 1 is exactly on the edge. The whole 60
seconds can then be swept and the bad moments found by number.

Swept, it found five models leaving the frame. Four of them were during the dip
between beats, where the veil is 92% opaque and the point is that you cannot see
the swap -- so the honest figure is two frames out of 1060, the broom and the
ladder, each for a twentieth of a second. Not much. Also not nothing, when the
whole point of the tour is that someone records it once and posts it.

The first fix was to widen the framing margin from 1.55 to 1.62. It worked and
it was the wrong fix: it took a slice of the frame off all thirty-five models to
buy back two frames from one, and mean fill fell to 0.515 -- every model sitting
in half a screen of empty space.

The right fix is in the chase. The camera's distance follows the model's size by
exponential approach at a single rate, and the two directions are not the same
mistake: falling behind a model that is GROWING crops it, and falling behind one
that is shrinking only leaves it small for a moment, which nobody notices. The
broom was the last offender because its bundle and its handle both sweep. So the
camera now retreats at 18 and closes at 7, and with that in place the margin
came back in past where it started, to 1.38.

Measured over the visible frames of a full 60 s run: no frame crops, the closest
any model comes to the edge is 0.81, and mean fill is 0.605 against 0.515 for
the wide-margin version and 0.55 for the original. Models are bigger in frame
than before AND nothing is cut.

Also here: the tour verified end to end -- 1201 frames, 60.05 s, 35 models, no
repeats, chest to oak -- and two stale numbers in the README. It claimed ~800
checks (1,044) and did its showcase arithmetic for 27 models, which is the kind
of sentence that goes quietly wrong every time a model is added, so it now says
what the number does when the kit grows.

One correction to my own measurements, twice over. `showcase.update` clamps its
delta to 0.05 internally, which `frameStep` does not, so stepping 0.2 advances
0.05 -- my first two readings of the tour's length were wrong by 4x and 10x and
disagreed with each other, which is what gave it away. And the run that
reported 34 models in 57.8 s was racing a page reload, not a dropped model.
This commit is contained in:
CRTkafa 2026-08-27 01:30:34 +07:00
parent 7d2877c901
commit 9de2721422
4 changed files with 74 additions and 11 deletions

View file

@ -60,7 +60,7 @@ bun run verify:glb # export every model, read it back, compare
bun run render # renders/_sheet.png — actually look at the models bun run render # renders/_sheet.png — actually look at the models
``` ```
`verify` runs ~800 browser-free checks against the installed sources: geometry `verify` runs 1,044 browser-free checks against the installed sources: geometry
validity, winding, coplanar-face (z-fighting) detection, bounding-box limits, validity, winding, coplanar-face (z-fighting) detection, bounding-box limits,
stable root and anchor identity across `configure()`, deterministic seeding, stable root and anchor identity across `configure()`, deterministic seeding,
material ownership, idempotent disposal, action semantics, and agreement material ownership, idempotent disposal, action semantics, and agreement
@ -115,13 +115,18 @@ camera move, morphing each model's parameters as it goes, with the interface
hidden so the frame is clean enough to record. hidden so the frame is clean enough to record.
```text ```text
viewer.html?showcase=60 viewer.html?showcase=60 # 30, 60 and 90 are offered
``` ```
**60 s is the default.** The tour splits its running time equally between the **60 s is the default**, and the reason is arithmetic: the tour splits its
models, so with 27 of them a 30 s run gives each 1.1 seconds — which is a flyby, running time equally between the models, so across 35 of them a 30 s run gives
not a demonstration. At 60 s each model gets 2.2 s, which is enough for the each 0.86 seconds — a flyby, not a demonstration — while 60 s gives 1.7 s and
sweep to read. 90 s gives 2.6 s.
That first number moves every time a model is added, which is worth saying out
loud rather than leaving as a stale sentence in a README: at 27 models, 60 s
was a comfortable 2.2 s each. It is now 1.7 s, and 90 s is there for anyone who
wants the older pace back.
Two things make the variation visible rather than merely present. Continuous Two things make the variation visible rather than merely present. Continuous
controls travel the whole usable band every beat instead of two random draws controls travel the whole usable band every beat instead of two random draws
@ -155,6 +160,8 @@ scripts/
audit.ts runs the support check across every configuration audit.ts runs the support check across every configuration
render.ts offline software rasteriser → PNG contact sheet render.ts offline software rasteriser → PNG contact sheet
reference-shots.ts one photographic reference per model, for comparison reference-shots.ts one photographic reference per model, for comparison
probe-tree.ts measures the oak against its reference photographs
catalog-table.ts regenerates the model table in the registry README
export-glb.ts batch GLB export export-glb.ts batch GLB export
media/ images used by this README media/ images used by this README
models.json which registries this project resolves models.json which registries this project resolves

View file

@ -113,7 +113,7 @@ export function createModel(overrides: Partial<OakTreeConfig> = {}) {
* photograph by finding the run of trunk pixels at that height, and the * photograph by finding the run of trunk pixels at that height, and the
* profile they make is the whole character of the bole: a violent flare * profile they make is the whole character of the bole: a violent flare
* in the bottom twentieth, then a shaft that hardly tapers for a quarter * in the bottom twentieth, then a shaft that hardly tapers for a quarter
* of the tree, then a steady run out to nothing at 78%. * of the tree, then a steady run out to nothing at 74%.
*/ */
const TAPER: ReadonlyArray<readonly [number, number]> = [ const TAPER: ReadonlyArray<readonly [number, number]> = [
[0.00, 1.95], [0.00, 1.95],

View file

@ -286,9 +286,24 @@ export function createShowcase(host: ShowcaseHost, options: ShowcaseOptions = {}
const { radius } = host.framing() const { radius } = host.framing()
// The margin is generous on purpose. A sweep changes the model's size while // The margin is generous on purpose. A sweep changes the model's size while
// the camera is already moving, and the framing chase always lags a little; // the camera is already moving, and the framing chase always lags a little;
// with a tight fit that lag crops the model. 1.55 keeps the whole silhouette // with a tight fit that lag crops the model.
// inside the frame even at the widest point of a sweep. //
return (radius * 1.55) / Math.sin((host.camera.fov * Math.PI) / 360) // 1.38, and measured rather than felt.
//
// `__probe.framing()` projects the model's bounding box into the frame and
// reports the worst corner, so the whole 60 seconds can be swept and the
// bad moments found by number instead of by scrubbing. Ignoring the frames
// the dip covers, the old 1.55 put the broom and the ladder outside the
// frame for one frame each -- not much, and not nothing either when the
// point of the tour is that someone records it once and posts it.
//
// The first attempt was to widen this to 1.62, which did fix the crop and
// cost every one of the thirty-five models a slice of the frame: mean fill
// fell to 0.515, so the models were sitting in half a screen of empty
// space. Fixing the CHASE instead (see `update`) let the margin come back
// in past where it started. At 1.38: no frame of the tour crops, the worst
// any model comes to the edge is 0.81, and mean fill is 0.605.
return (radius * 1.38) / Math.sin((host.camera.fov * Math.PI) / 360)
} }
return { return {
@ -361,7 +376,17 @@ export function createShowcase(host: ShowcaseHost, options: ShowcaseOptions = {}
// The rate was raised from 3.4 to 7 after watching a run: at the slower // The rate was raised from 3.4 to 7 after watching a run: at the slower
// rate the camera was still catching up to the previous model's size a // rate the camera was still catching up to the previous model's size a
// second into the next beat. // second into the next beat.
distance += (wantedDistance - distance) * (1 - Math.exp(-7 * dt)) //
// ASYMMETRIC, because the two directions are not the same mistake.
// Falling behind a model that is GROWING crops it -- the broom's bundle
// and handle both sweep, and it was the one model still leaving the frame
// with everything else comfortably inside. Falling behind one that is
// shrinking only leaves it small for a moment, which nobody notices. So
// the camera retreats at better than twice the speed it closes in, and
// the fix costs no frame at all in the general case, where a blanket
// margin would have taken a slice off all thirty-five.
const chase = wantedDistance > distance ? 18 : 7
distance += (wantedDistance - distance) * (1 - Math.exp(-chase * dt))
// A slow rise and fall in elevation over each beat keeps the move from // A slow rise and fall in elevation over each beat keeps the move from
// reading as a flat turntable. // reading as a flat turntable.

View file

@ -855,6 +855,37 @@ if (import.meta.env.DEV) {
progress: +showcase.progress().toFixed(4), progress: +showcase.progress().toFixed(4),
caption: app.querySelector('[data-caption-address]')?.textContent ?? '', caption: app.querySelector('[data-caption-address]')?.textContent ?? '',
}), }),
/**
* How much of the current model is actually ON SCREEN.
*
* The tour is the one part of this project that a still render cannot
* check, and looking at a handful of frames is how a model half out of
* frame gets shipped — it happened once already, with the bottom of
* every model cut off. This projects the model's own bounding box into
* normalised device coordinates and reports the worst overshoot, so the
* whole 60 seconds can be swept and the bad moments found by number
* rather than by scrubbing.
*
* 0 means comfortably inside. 1 means a corner is exactly on the edge of
* the frame. Above 1 is off screen.
*/
framing: () => {
if (!current) return null
const box = new Box3().setFromObject(current.root)
if (box.isEmpty()) return null
camera.updateMatrixWorld(true)
const corner = new Vector3()
let worst = 0
for (let i = 0; i < 8; i += 1) {
corner.set(
i & 1 ? box.max.x : box.min.x,
i & 2 ? box.max.y : box.min.y,
i & 4 ? box.max.z : box.min.z,
).project(camera)
worst = Math.max(worst, Math.abs(corner.x), Math.abs(corner.y))
}
return +worst.toFixed(3)
},
state: () => { state: () => {
const info = survey(current!.root) const info = survey(current!.root)
return { return {