Dragon-s-Lair-X68k/tools/analysis/30_packed_container.py

#!/usr/bin/env python3
"""The PACKED container: does it hold, and what is the picture actually worth?

    python3 tools/analysis/30_packed_container.py [packed.dlxp]
            [--frames tmp/fr_singe] [--codec tmp/rc_fr_singe_scsi_span.dlx]

ROADMAP K2.  Two jobs, and they are different kinds of claim.

1. THE FORMAT HOLDS.  A packed record is written into the palette registers and
   GVRAM by a DMA channel with no bounds test anywhere -- the channel has no
   opinion about what it is copying (FINDINGS 62) -- so "the geometry is right"
   is not a tidiness check, it is the whole of the container's correctness.
   Round-trip, sector geometry, and the two reserved indices are gated here.

2. THE PICTURE IS RE-DERIVED, and this is the number session 30 asked for.
   FINDINGS 61.9 measured the packed player at 34.08 dB against the codec's
   29.19 and filed TWO caveats: the quantiser was PIL's free 256-colour
   MEDIANCUT rather than this project's builder, and the figure was quoted in
   the RGB888 palette domain.  Both are paid here:

     * `vq.frame_palette` is what ships it -- 254 colours, because the packed
       layout spends index 0 on the transparency key and 255 on black (47.2).
     * the GRB555+I WORD is charged.  A palette entry in a packed record is
       already a hardware word; the display renders 5 bits a channel with one
       shared LSB (23.3).  Every PSNR in this project's encoder is measured
       upstream of that, so the codec is charged it here too and the comparison
       stays like for like.

   And the scene-palette CONTROL is built and scored, because "per-frame
   palettes became legal" is the mechanism 61.9 credits and an unrun control is
   an assumption.  The codec cannot take this row: every codeword it emits is an
   index INTO `vq.scene_palette`, so 31.33 dB is its ceiling at any bitrate.

WHAT THIS DOES NOT DO.  It does not put a packed frame on a machine -- that is
K3, and the layout itself was already rendered pixel-exactly on both emulators
in 47.2.  It does not price clocks: 29_packed_player.py owns that, off the
MEASURED blit, and nothing here moves it.  And it settles nothing about the
medium: 582.0 KB/s is geometry, and whether anything sustains it is B1.
"""
import argparse, glob, os, sys
sys.path.insert(0, "tools/encoder")
sys.path.insert(0, "tools/bench")
import numpy as np
from PIL import Image
import vq as VQ
import dlxp as P
from dlx import DLX
from dlxload import pack_palette

ap = argparse.ArgumentParser()
ap.add_argument("packed", nargs="?", default="tmp/packed_singe.dlxp")
ap.add_argument("--frames", default="tmp/fr_singe")
ap.add_argument("--mismatch-png", default=None,
                help="write the 62.5 mismatch as a picture: correct render | the "
                     "same frame under the NEXT frame's palette | the 24-bit "
                     "source. A dB is not a look, and this claim is about a look.")
ap.add_argument("--codec", default="tmp/rc_fr_singe_scsi_span.dlx",
                help="the shipping container this replaces. Its PSNR is COMPUTED "
                     "from its own bytes, not transcribed from docs (60.8).")
a = ap.parse_args()

fail = []
d = P.DLXP(a.packed)            # every format invariant is checked in here
print(f"{a.packed}: DLXP{d.version} {d.W}x{d.H} {d.fps}fps {d.nframes} frames")
print()

# --- 1. the format -----------------------------------------------------------
print("THE FORMAT, and why each line is a gate and not a courtesy check:")
print(f"  record {d.rec_bytes:,} B = {d.rec_bytes // P.SECTOR} sectors exactly, "
      f"palette {d.pal_bytes} B "
      f"{'LAST' if d.palette_last else 'first'}, picture {d.pic_bytes:,} B")
print(f"  1.0 B/pixel: {d.pic_bytes} bytes carry {d.W * d.H} pixels "
      f"(the unpacked path needs {2 * d.W * d.H:,})")

zero = black = 0
for f in range(d.nframes):
    idx = d.indices(f)
    # The channel copies bytes; a container whose interleave is a byte out does
    # not fail, it paints. So the round trip is the assertion that the bytes in
    # the record ARE the picture, in the order GVRAM wants them.
    if P.pack_picture(idx).tobytes() != d._split(f)[1]:
        fail.append(f"frame {f}: the record does not round-trip through the "
                    f"interleave -- the container is not what it says it is")
        break
    zero += int((idx == 0).sum())
    black += int((idx == 255).sum())
if zero:
    fail.append(f"index 0 appears in the picture {zero:,} times -- it is the "
                f"TRANSPARENCY KEY of the top page and must stay unused (47.2)")
print(f"  round-trip: {d.nframes} records unpack and re-pack byte-identical")
print(f"  index 0 (transparency key) used {zero} times; "
      f"index 255 (black) {black:,} times in the picture")

# THE PICTURE'S wire, and it is the one this file is about. DLXP2 puts audio on
# the same wire at a cadence (65.3, 67) and `d.kbps()` is both; what is asserted
# here is that the PICTURE's share is still exactly geometry, because that is
# 61.6's claim and a second stream is exactly the thing that could quietly
# dilute it.
kbps = d.video_kbps()
geom = d.rec_bytes * d.fps / 1024
if abs(kbps - geom) > 1e-6:
    fail.append(f"wire {kbps} != geometry {geom}")
print(f"  wire {kbps:.1f} KB/s = {d.rec_bytes:,} B x {d.fps} fps. FIXED. A codec's "
      f"bitrate is a lever and a literal frame's is geometry (61.6)"
      + (f"\n  ...and {d.audio_kbps():.2f} KB/s of audio rides beside it on the "
         f"F={d.cad_f}/A={d.cad_a} cadence, for {d.kbps():.1f} KB/s total "
         f"(tools/analysis/34_packed_audio.py)" if d.has_audio else ""))
print()

# --- 2. the picture ----------------------------------------------------------
files = sorted(glob.glob(f"{a.frames}/f*.png"))[:d.nframes]
if len(files) < d.nframes:
    sys.exit(f"{a.frames}: {len(files)} frames, container has {d.nframes}")
src = [np.asarray(Image.open(f).convert("RGB")) for f in files]


def rendered(pal):
    """RGB888 as the DISPLAY produces it, from the same maths the loader uses."""
    return pack_palette(np.asarray(pal, np.uint8))[2]


def score(name, pal_rgb, idx_frames, note=""):
    """Two columns: the palette domain every encoder PSNR in this tree is
    quoted in, and the hardware word the display actually renders."""
    ren = rendered(pal_rgb)
    p_pal = np.mean([VQ.psnr(s, np.asarray(pal_rgb)[i])
                     for s, i in zip(src, idx_frames)])
    p_hw = np.mean([VQ.psnr(s, ren[i]) for s, i in zip(src, idx_frames)])
    print(f"  {name:<44s} {p_pal:6.2f}   {p_hw:6.2f}   {note}")
    return p_pal, p_hw


print("PSNR vs the 24-bit source, mean over frames:")
print(f"  {'':<44s} {'RGB888':>6}   {'GRB555':>6}")

codec_pal = codec_hw = None
if os.path.exists(a.codec):
    c = DLX(a.codec)
    if c.nframes < d.nframes:
        print(f"  (the codec container has {c.nframes} frames and this has "
              f"{d.nframes} -- its row is skipped rather than compared over a "
              f"different window)")
    else:
        # Its rate is printed with it because this is the GATE container -- the
        # heaviest stream the encoder emits, `--kbps 280 --span-kbps 488
        # --spans all` (check.sh) -- and NOT the 496.7 KB/s / 29.19 dB "current
        # encode" of the README. Two containers, two numbers; a row that named
        # neither would invite the difference to be read as a drift.
        ckbps = sum(c.record_lengths()) * c.fps / c.nframes / 1024
        codec_pal, codec_hw = score("CODEC, the GATE container", c.pal,
                                    c.decode_all()[:d.nframes],
                                    f"{ckbps:.1f} KB/s, "
                                    f"{os.path.basename(a.codec)}")
else:
    print(f"  (no codec container at {a.codec} -- its row is skipped)")

# The codec's CEILING: 256 colours, one palette for the scene, no VQ loss at
# all. Not a rival, a bound -- no bitrate takes the codec past this row.
ref, spal = VQ.scene_palette(src, reserve_black=True)
sidx = VQ.palettise(src, ref)
ceil_pal, ceil_hw = score("256c SCENE palette -- the CODEC'S CEILING",
                          spal, sidx, "no bitrate crosses this")

# The control for the mechanism 61.9 credits: same LAYOUT and the same 254
# picture colours, one palette for the scene instead of one per frame.  It is
# built to 255 with black reserved and then black is MOVED from 0 to 255, which
# is the packed layout's convention (47.2) rather than the codec's -- so the
# only variable between this row and the container's is per-frame vs scene-wide.
cref, c255 = VQ.scene_palette(src, colors=255, reserve_black=True)
cpal = np.vstack([np.zeros((1, 3), np.uint8), c255[1:],
                  np.zeros((1, 3), np.uint8)])
cidx = [np.where(i == 0, np.uint8(255), i)
        for i in VQ.palettise(src, cref)]
ctl_pal, ctl_hw = score("PACKED, 254c SCENE palette  [the CONTROL]", cpal, cidx)

# And the container itself.  The right-hand column is read out of the CONTAINER'S
# OWN BYTES -- `DLXP.render` unpacks the GRB555 words the record carries -- and
# the left-hand one is recomputed from the encoder, because a packed record has
# no RGB888 palette in it to score.  The two are tied together by a gate rather
# than by trust: the palettes the encoder builds here must reproduce the
# container's indices exactly, or the left column is describing a different file.
pk_idx, pk_pal_rgb, mismatch, palbad = [], [], 0, 0
for n, s in enumerate(src):
    pal, idx = VQ.frame_palette(s)
    if not np.array_equal(idx, d.indices(n)):
        mismatch += 1
    # And the WORD.  The encoder packed GRB555+I with `dlxload.pack_palette` and
    # `DLXP.palette_rgb` unpacks it: two separate pieces of maths over the same
    # 23.3 rule, and a container is the only place they meet. Required to agree,
    # not assumed to -- a wrong shared LSB is a 1.96 dB bug that still renders.
    if not np.array_equal(rendered(pal), d.palette_rgb(n)):
        palbad += 1
    pk_idx.append(idx)
    pk_pal_rgb.append(pal)
if palbad:
    fail.append(f"{palbad} of {d.nframes} records carry palette words that do "
                f"not unpack to the RGB the encoder packed -- pack_palette and "
                f"DLXP.palette_rgb disagree about GRB555+I")
if mismatch:
    fail.append(f"{mismatch} of {d.nframes} frames re-quantise to different "
                f"indices than the container holds -- the RGB888 column would "
                f"be scoring a file that is not this one")
pk_pal = np.mean([VQ.psnr(s, p[i]) for s, p, i in zip(src, pk_pal_rgb, pk_idx)])
pk_hw = np.mean([VQ.psnr(s, d.render(f)) for f, s in enumerate(src)])
print(f"  {'PACKED CONTAINER, 254c PER-FRAME':<44s} {pk_pal:6.2f}   {pk_hw:6.2f}   "
      f"GRB555 read out of {os.path.basename(a.packed)}")
print()
print("  The right-hand column is the PLAYER'S number. Every PSNR this project")
print("  has quoted -- 29.19, 31.33, 34.08 -- lives in the left one, upstream of")
print("  the 5-bit hardware word (23.3), and 61.9's 34.08 is directly comparable")
print("  to the packed row's left-hand entry and to nothing else.")
print()

# --- 3. what it means --------------------------------------------------------
if codec_hw is not None:
    print(f"  packed vs the codec gate container, as the DISPLAY renders both: "
          f"{pk_hw - codec_hw:+.2f} dB")
print(f"  packed vs the codec's CEILING:                             "
      f"{pk_hw - ceil_hw:+.2f} dB")
print(f"  what the PER-FRAME palette is worth (vs the control):      "
      f"{pk_hw - ctl_hw:+.2f} dB")
print(f"  what the GRB555 word costs the ceiling row:                "
      f"{ceil_hw - ceil_pal:+.2f} dB")
# 60.3 measured ONE reserved entry at 0.04 dB; the packed layout spends two.
# Scored here at scene scale, where the control makes it a clean subtraction.
print(f"  what the packed layout's TWO reserved entries cost:         "
      f"{ctl_pal - ceil_pal:+.4f} dB  (256c -> 254c, scene palette, RGB888)")
print()

# The three claims 61.9 makes, restated as gates. A tree where any of these
# flipped has a different answer to ROADMAP K and should say so out loud.
if codec_hw is not None and pk_hw <= codec_hw:
    fail.append(f"the packed container is {pk_hw:.2f} dB and the codec it "
                f"replaces is {codec_hw:.2f} -- 61.9's headline is inverted")
if pk_hw <= ceil_hw:
    fail.append(f"the packed container is {pk_hw:.2f} dB and the codec's own "
                f"CEILING is {ceil_hw:.2f} -- the per-frame palette bought "
                f"nothing, and 61.9's reason for building this branch is gone")
if pk_hw <= ctl_hw:
    fail.append(f"per-frame {pk_hw:.2f} dB is not better than the SCENE-palette "
                f"control {ctl_hw:.2f} -- the mechanism 61.9 credits is absent")

# --- 4. FINDINGS 62.5, which needed this encoder to exist ---------------------
# 62.5 filed the chain's order -- palette first or 193rd -- as a free choice with
# a visible consequence, and said the severity "depends on how much the palette
# moves between consecutive frames, which is a property of the encoder K2 has
# not been written yet". It is written now, so the number exists.
#
# The mismatch is a WIPE, not a flash: rows arrive top to bottom, so at any
# instant part of the screen is right. What is bounded here is the WORST
# instant of each order -- the whole screen wrong -- which is the start of the
# transfer for palette-first and the end of it for palette-last. The mean over
# the transfer is about half of each, because the wipe is linear in rows.
print("FINDINGS 62.5 PRICED -- palette FIRST vs LAST, at the worst instant of each:")
churn = np.mean([int((d.palette_words(n) != d.palette_words(n - 1)).sum())
                 for n in range(1, d.nframes)])
first = np.mean([VQ.psnr(src[n - 1], d.palette_rgb(n)[d.indices(n - 1)])
                 for n in range(1, d.nframes)])
last = np.mean([VQ.psnr(src[n], d.palette_rgb(n - 1)[d.indices(n)])
                for n in range(1, d.nframes)])
correct = np.mean([VQ.psnr(src[n], d.render(n)) for n in range(1, d.nframes)])
print(f"  palette entries that CHANGE frame to frame: {churn:.1f} of 256 "
      f"({100 * churn / 256:.0f}%) -- a per-frame palette is not a small delta")
print(f"  palette FIRST, old rows under the new palette: {first:6.2f} dB "
      f"({first - correct:+.2f} against the correct pairing)")
print(f"  palette LAST,  new rows under the old palette: {last:6.2f} dB "
      f"({last - correct:+.2f})")
print(f"  the container is currently palette "
      f"{'LAST' if d.palette_last else 'FIRST'} (dlxp.py, --palette-last)")
if a.mismatch_png:
    # The frame whose mismatch is CLOSEST TO THE MEAN, so the picture is not an
    # outlier picked to make the point look worse than the number.
    mis = np.array([VQ.psnr(src[n - 1], d.palette_rgb(n)[d.indices(n - 1)])
                    for n in range(1, d.nframes)])
    n = int(np.argmin(np.abs(mis - mis.mean()))) + 1
    z = lambda x: np.repeat(np.repeat(x, 2, 0), 2, 1)
    gap = np.full((d.H * 2, 6, 3), 30, np.uint8)
    Image.fromarray(np.concatenate(
        [z(d.render(n - 1)), gap, z(d.palette_rgb(n)[d.indices(n - 1)]), gap,
         z(src[n - 1])], axis=1)).save(a.mismatch_png)
    print(f"  wrote {a.mismatch_png}: frame {n-1} correct | frame {n-1} under "
          f"frame {n}'s palette ({mis[n-1]:.2f} dB) | the 24-bit source")
print("  Both are one paint, and both are MOOT if buffer mode blanks the layer")
print("  (47.4/B2). This bounds the cost of being wrong; it does not decide it,")
print("  because dB over a whole frame is not what an eye sees in a wipe.")
print()

for x in fail:
    print("FAIL " + x)
sys.exit(1 if fail else 0)