make_imgfmt_fixtures.py

Go to the documentation of this file.

#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Brighton Sikarskie
"""Generate imgfmt_fixtures.h: deterministic BMP and GIF images for the gate.
 
These close a coverage hole. The firmware links four stb_image formats, and
STBI_ONLY_BMP and STBI_ONLY_GIF were the two with no example exercising them --
PNG and JPEG already have ereader_image and ereader_jpeg. A decoder nobody
calls is a decoder nobody knows is broken.
 
The on-device ereader_imgfmt gate decodes both through `ra8_img_decode_blit`
(zero-heap) into a 160x120 framebuffer and CRC-gates each independently, so a
regression in one format cannot be masked by the other passing.
 
Determinism is the requirement that shapes everything here: the CRCs are pinned
in the gate, so a fixture that varied run to run would break the gate rather
than detect anything. Output is pure 7-bit ASCII at 16 bytes per row inside a
clang-format-off guard, so the formatter leaves it byte-identical.
 
Usage:
    python3 examples/ek_ra8d2/hw_validated/hil/ereader_imgfmt/scripts/make_imgfmt_fixtures.py
"""
 
from __future__ import annotations
 
import io
from pathlib import Path
 
from PIL import Image
 
W, H = 40, 30
QUAD = [(0xC0, 0x10, 0x20), (0x18, 0x90, 0x30), (0x20, 0x40, 0xC0), (0xD0, 0xA0, 0x18)]
 
 
def make_image(layout: str) -> Image.Image:
    """Render a 40x30 RGB test pattern in one of two layouts.
 
    The two layouts exist so BMP and GIF decode to DIFFERENT pixels and
    therefore pin two different CRCs. Identical images would let a gate pass
    while decoding the wrong buffer -- a copy-paste bug in the gate would be
    invisible.
 
    Colors come from QUAD, chosen to be far apart so GIF's 4-color adaptive
    palette reproduces them exactly rather than approximating.
 
    Args:
        layout: "quad" for four quadrants, anything else for horizontal bands.
 
    Returns:
        A 40x30 RGB Pillow Image.
    """
    # Two distinct patterns so the BMP and GIF decode to different pixels and
    # therefore pin two different CRCs (each path independently gated).
    img = Image.new("RGB", (W, H))
    px = img.load()
    for y in range(H):
        for x in range(W):
            if layout == "quad":
                idx = (1 if x >= W // 2 else 0) + (2 if y >= H // 2 else 0)
            else:  # horizontal bands
                idx = min(y // (H // len(QUAD)), len(QUAD) - 1)
            px[x, y] = QUAD[idx]
    return img
 
 
def encode(fmt: str) -> bytes:
    """Render and encode the test image for one format.
 
    Pairs each format with its own layout -- BMP gets quadrants, anything else
    gets bands -- so the two fixtures never collide. GIF is additionally
    converted to a 4-color adaptive palette: GIF is palette-only anyway, and
    pinning the color count keeps the encoder from choosing a different palette
    size and shifting the bytes.
 
    Args:
        fmt: A Pillow format name, in practice "BMP" or "GIF". Any other value
            takes the bands layout and is passed to Pillow unchanged.
 
    Returns:
        The encoded image bytes; identical across runs for a given format.
 
    Raises:
        KeyError: Pillow does not know `fmt`.
    """
    # BMP gets the quadrant layout; GIF gets horizontal bands.
    img = make_image("quad" if fmt == "BMP" else "bands")
    out = io.BytesIO()
    if fmt == "GIF":
        # Palette mode keeps the GIF tiny and deterministic.
        img = img.convert("P", palette=Image.ADAPTIVE, colors=4)
    img.save(out, format=fmt)
    return out.getvalue()
 
 
def bake_array(name: str, data: bytes) -> str:
    """Render bytes as a C length enum plus a `static const uint8_t` array.
 
    The length is emitted as `enum : size_t` and used to size the array, so the
    declared size and the data can never disagree.
 
    The table is wrapped in `clang-format off`/`on` and laid out 16 bytes per
    row. That keeps the formatter from reflowing it, which is what makes a
    regenerated fixture diff empty when nothing actually changed.
 
    Args:
        name: Lowercase stem for the identifiers; produces `k_<name>` and
            `k_<name>_len`, and is upper-cased for the doc comments. Used
            unquoted, so it must already be a valid C identifier fragment.
        data: Bytes to bake.
 
    Returns:
        The declarations as C source text.
    """
    rows = []
    for i in range(0, len(data), 16):
        chunk = data[i : i + 16]
        rows.append("  " + ", ".join(f"0x{b:02X}" for b in chunk) + ",")
    body = "\n".join(rows)
    return (
        f"/** @brief Length of the baked {name.upper()} image, bytes. */\n"
        f"enum : size_t {{ k_{name}_len = {len(data)}U "
        f"/**< {name.capitalize()} length. */ }};\n"
        "\n"
        f"/** @brief Baked 40x30 four-quadrant {name.upper()} image. */\n"
        "/* Suppression rationale: generated bytes stay at 16 per row for stable diffs. */\n"
        "/* clang-format off */\n"
        f"static const uint8_t k_{name}[k_{name}_len] = {{\n"
        f"{body}\n"
        "};\n"
        "/* clang-format on */\n"
    )
 
 
def main() -> int:
    """Regenerate the owning component's inc/imgfmt_fixtures.h.
 
    Regenerating changes the baked bytes only if Pillow's encoders change. If it
    does, the CRCs pinned in the on-device gate no longer match and must be
    re-pinned in the same commit -- otherwise the gate fails on a fixture that
    is actually correct.
    """
    bmp = encode("BMP")
    gif = encode("GIF")
    header = (
        "/**\n"
        " * @file imgfmt_fixtures.h\n"
        " * @brief Baked BMP + GIF test images for the ereader_imgfmt gate.\n"
        " *\n"
        " * @details The two stb_image formats (STBI_ONLY_BMP / STBI_ONLY_GIF) that\n"
        " * had no example. Each is a 40x30 four-quadrant image, byte-identical run to\n"
        " * run. Generated by examples/ek_ra8d2/hw_validated/hil/ereader_imgfmt/scripts/\n"
        " * make_imgfmt_fixtures.py. Pure ASCII, 16 bytes per row.\n"
        " *\n"
        " * @copyright Copyright (c) 2026 Brighton Sikarskie\n"
        " * SPDX-License-Identifier: MIT\n"
        " */\n"
        "#pragma once\n"
        "\n"
        "#include <stddef.h>\n"
        "#include <stdint.h>\n"
        "\n"
        f"{bake_array('bmp', bmp)}"
        "\n"
        f"{bake_array('gif', gif)}"
    )
    output = Path(__file__).resolve().parent.parent / "inc" / "imgfmt_fixtures.h"
    with output.open("w", encoding="ascii") as f:
        f.write(header)
    print(f"wrote {output} (bmp {len(bmp)} B, gif {len(gif)} B)")
 
 
if __name__ == "__main__":
    main()