docs: montage-renderer imagery, visual polish, README screenshots

- switch report frames to the scene best/worst montage renderer
  (Onscreen/Offscreen panels + TPI/FPI/FN legend): perfect-second hero,
  wedding couple, funeral 19-of-20, polygraph bridging, crew-scene FN
  ceiling, Robert Patrick ground-truth gap, rapid-cut double label,
  Herbie Hancock on an in-fiction screen
- deep dive restructured: extinction bridging framed as designed
  behavior with a measurable cost (debug overlay draws the boxes; the
  shipped output is presence windows), plus the face-vs-presence
  ceiling and two X-Ray-is-wrong exhibits
- Material polish: light/dark palette toggle, landing-page grid cards,
  figure/caption CSS, how-to-read admonition; site_url set so 404 links
  resolve under the Pages subpath
- README: perfect-second and screen-call frames committed (gitignore
  exceptions), readme_example.jpg retired
- build_site.sh: stage_frame helper downscales montage frames to 1920px
  and pulls any missing montage-frames packages
This commit is contained in:
2026-07-19 22:27:57 +02:00
parent 93b6827b14
commit 4b5557974b
10 changed files with 299 additions and 137 deletions
+50 -22
View File
@@ -5,32 +5,60 @@ film or TV episode — built on [KPN++](https://gitea.tourolle.paris/dtourolle/K
(a C++20 Kahn Process Network library) for the detect → track → match → scene
pipeline, with a Jellyfin-integrated gallery and an X-Ray-validated optimizer.
This is what a good second looks like — one sampled frame from a held-out film,
19 faces named, all 19 correct, the rest honestly declared unknown:
This is a perfect X-Ray second, on a film the optimizer never saw:
![19 correct identifications in one wedding shot, Downton Abbey: A New Era](assets/images/downton_wedding_19_correct.jpg)
![A perfect X-Ray second: three faces named at 100%, two more correctly carried off-screen](assets/images/lovelace_perfect_second.jpg)
And this is why the work isn't done: on this same film the same config misses
6 in 10 of the actor-seconds X-Ray says are present, and on the worst held-out
film it reports ghost actors over empty walls — at 100% confidence. Both
stories, with the evidence, are in the pages below.
Every visible face named at 100% — Chris Noth, Hank Azaria, Bobby Cannavale —
the background extra honestly left unnamed, and the two credited cast without
a visible face correctly carried as present off-screen by the tracker's
presence windows. That's the pipeline exactly reproducing Amazon X-Ray's
record for this second.
It doesn't always go like that: the hardest held-out film scores 46% F1, and
the report is honest about *why* — one tunable trade (extinction bridging at
hard cuts), one structural ceiling (X-Ray credits people whose faces never
appear), and a few cases where the pipeline is right and X-Ray is wrong. The
evidence for all of it is in the pages below.
## Start here — four questions this bake-off answers
- **[Which model is best?](best-model.md)** — calibration curves first
(discriminative power, independent of any threshold), then F1 on the actual
benchmark. LVFace-B Glint360K wins both.
- **[Whole gallery vs. limited (cast-restricted) gallery](gallery-scope.md)** —
restricting the matcher to a film's credited cast is a clean win on every
axis (+3.3pp F1, less than a third the misIDs), but isn't a shipped runtime
feature yet.
- **[Does pose expansion help?](pose-expansion.md)** — a real training-set
effect that didn't reproduce on 5 held-out films once two methodology bugs
were caught and fixed. An honest null result, not a forced narrative.
- **[Deep dive: LVFace-B Glint360K](lvface-deep-dive.md)** — the winning
model's held-out generalization gap, its two real failure modes (frozen-bbox
"ghost tracks"), and one case where it correctly identified an actor that
the X-Ray ground truth itself failed to credit.
<div class="grid cards" markdown>
- :material-trophy:{ .lg .middle } **[Which model is best?](best-model.md)**
---
Calibration curves first (discriminative power, independent of any
threshold), then F1 on the actual benchmark. LVFace-B Glint360K wins
both.
- :material-filter:{ .lg .middle } **[Whole vs. cast-restricted gallery](gallery-scope.md)**
---
Restricting the matcher to a film's credited cast is a clean win on
every axis (+3.3pp F1, less than a third the misIDs) — but isn't a
shipped runtime feature yet.
- :material-account-convert:{ .lg .middle } **[Does pose expansion help?](pose-expansion.md)**
---
A convincing training-set effect that didn't reproduce on 5 held-out
films once two methodology bugs were caught and fixed. An honest null
result, not a forced narrative.
- :material-magnify-expand:{ .lg .middle } **[Deep dive: LVFace-B Glint360K](lvface-deep-dive.md)**
---
The held-out generalization gap, how the error budget decomposes
(extinction bridging at hard cuts, X-Ray's scene-membership vs.
on-screen-face ceiling), and the frames where the pipeline is right
and the ground truth is wrong.
</div>
## The full technical log
@@ -43,7 +71,7 @@ stories, with the evidence, are in the pages below.
earlier scene-union-metric tuning pass, superseded by the per-second metric
used in the bake-off but kept for the ground-truth/architecture background.
- **[Service conversion (proposal)](service-conversion.md)** — design sketch
for an idle-GPU Docker worker, not yet built.
for a native idle-GPU worker gated on screen lock, not yet built.
## Reproducing the benchmarks