gen_comic_large_fixture.py

Go to the documentation of this file.

#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Brighton Sikarskie
"""Generate the baked oversized single-page CBZ fixture for ereader_comic (#344).
 
Emits a pure 7-bit-ASCII C header (comic_large_fixture.h) holding one CBZ with a
single deliberately-large grayscale PNG page. Decoded at full resolution the page
far exceeds the app's whole-decode arena, so the reader cannot open it that way;
it exercises the tile path (comic_tiles -> JOF atlas -> ra8_tile_cache)
instead. The art is flat-shaded horizontal bands plus a frame and a left gutter,
so it DEFLATEs to a few hundred bytes and the baked array stays tiny on disk
while the decoded image is multiple megabytes.
 
The output is deterministic (fixed art, fixed zlib level), so the tile digest the
app prints is identical on host, ra8_emulator, and silicon.
 
Usage:
  python3 scripts/gen/gen_comic_large_fixture.py \
      examples/ek_ra8d2/hw_pending/ereader_comic/inc/comic_large_fixture.h
"""
 
from __future__ import annotations
 
import struct
import sys
import zlib
from pathlib import Path
 
# Oversized on purpose: 1024x1400 decodes to ~4.3 MiB RGB (or ~5.7 MiB at the
# reader's 4 bpp footprint estimate), well past the 2 MiB whole-decode arena.
PAGE_W = 1024
PAGE_H = 1400
 
PNG_BIT_DEPTH_8 = 8
PNG_COLOR_GRAY = 0
DEFAULT_OUTPUT = (
    Path(__file__).resolve().parents[2]
    / "examples"
    / "ek_ra8d2"
    / "hw_pending"
    / "ereader_comic"
    / "inc"
    / "comic_large_fixture.h"
)
ZIP_LOCAL_MAGIC = 0x04034B50
ZIP_CENTRAL_MAGIC = 0x02014B50
ZIP_EOCD_MAGIC = 0x06054B50
ZIP_VERSION = 20
ZIP_METHOD_DEFLATE = 8
DEFLATE_RAW_WBITS = -15
ZLIB_BEST = 9
BYTES_PER_ROW = 16
 
BORDER = 8
GUTTER = 48
BAND_COUNT = 8
BAND_BASE = 40
BAND_STEP = 24
GUTTER_GRAY = 20
 
 
def gray(x: int, y: int) -> int:
    """Deterministic, DEFLATE-friendly grayscale sample for one pixel."""
    if x < BORDER or x >= PAGE_W - BORDER or y < BORDER or y >= PAGE_H - BORDER:
        return 0  # black frame
    if x < GUTTER:
        return GUTTER_GRAY  # dark left gutter
    band = (y * BAND_COUNT) // PAGE_H
    return min(255, BAND_BASE + BAND_STEP * band)
 
 
def render_page() -> bytearray:
    """Render the whole page into a flat grayscale buffer."""
    out = bytearray(PAGE_W * PAGE_H)
    for y in range(PAGE_H):
        row = y * PAGE_W
        for x in range(PAGE_W):
            out[row + x] = gray(x, y)
    return out
 
 
def png_chunk(tag: bytes, data: bytes) -> bytes:
    """Wrap a payload in one PNG chunk: length, type, data, CRC-32."""
    out = struct.pack(">I", len(data)) + tag + data
    crc = zlib.crc32(tag + data) & 0xFFFFFFFF
    return out + struct.pack(">I", crc)
 
 
def encode_png(g: bytes | bytearray) -> bytes:
    """8-bit grayscale PNG (color type 0), one filter-0 byte per scanline."""
    sig = b"\x89PNG\r\n\x1a\n"
    ihdr = struct.pack(">IIBBBBB", PAGE_W, PAGE_H, PNG_BIT_DEPTH_8, PNG_COLOR_GRAY, 0, 0, 0)
    raw = bytearray()
    for y in range(PAGE_H):
        raw.append(0)
        raw += g[y * PAGE_W : (y + 1) * PAGE_W]
    idat = zlib.compress(bytes(raw), ZLIB_BEST)
    return sig + png_chunk(b"IHDR", ihdr) + png_chunk(b"IDAT", idat) + png_chunk(b"IEND", b"")
 
 
def build_cbz(png: bytes) -> bytes:
    """Minimal deterministic single-member ZIP (DEFLATE) that miniz reads."""
    name = b"01_large.png"
    comp = zlib.compressobj(ZLIB_BEST, zlib.DEFLATED, DEFLATE_RAW_WBITS)
    body = comp.compress(png) + comp.flush()
    crc = zlib.crc32(png) & 0xFFFFFFFF
    local = (
        struct.pack(
            "<IHHHHHIIIHH",
            ZIP_LOCAL_MAGIC,
            ZIP_VERSION,
            0,
            ZIP_METHOD_DEFLATE,
            0,
            0,
            crc,
            len(body),
            len(png),
            len(name),
            0,
        )
        + name
        + body
    )
    central = (
        struct.pack(
            "<IHHHHHHIIIHHHHHII",
            ZIP_CENTRAL_MAGIC,
            ZIP_VERSION,
            ZIP_VERSION,
            0,
            ZIP_METHOD_DEFLATE,
            0,
            0,
            crc,
            len(body),
            len(png),
            len(name),
            0,
            0,
            0,
            0,
            0,
            0,
        )
        + name
    )
    eocd = struct.pack(
        "<IHHHHIIH",
        ZIP_EOCD_MAGIC,
        0,
        0,
        1,
        1,
        len(central),
        len(local),
        0,
    )
    return local + central + eocd
 
 
def emit_header(path: str | Path, cbz: bytes) -> None:
    """Write the generated pure-ASCII C header holding the CBZ byte array."""
    header = (
        "/**\n"
        " * @file comic_large_fixture.h\n"
        " * @brief Baked oversized single-page CBZ for the ereader_comic tile self-check\n"
        " *        (#344; generated by scripts/gen/gen_comic_large_fixture.py -- do not edit).\n"
        " *\n"
        f" * @details A miniz-decodable ZIP of one {PAGE_W}x{PAGE_H} grayscale PNG page whose\n"
        " *          decoded size far exceeds the reader's whole-decode arena, so it can only\n"
        " *          be opened through the JOF tile path (comic_tiles). Flat-shaded art\n"
        " *          keeps the baked array tiny while the decoded image is multiple MiB.\n"
        " *\n"
        " * @copyright Copyright (c) 2026 Brighton Sikarskie\n"
        " * SPDX-License-Identifier: MIT\n"
        " */\n"
        "#pragma once\n\n"
        "#include <stdint.h>\n\n"
        f"/** @brief Baked {len(cbz)}-byte single-page oversized CBZ. */\n"
        "static const uint8_t k_comic_large_cbz[] = {\n"
    )
    rows = []
    for start in range(0, len(cbz), BYTES_PER_ROW):
        chunk = cbz[start : start + BYTES_PER_ROW]
        rows.append("  " + " ".join(f"0x{byte:02X}," for byte in chunk))
    # The length is derived from the array rather than emitted as a literal,
    # and the geometry is a typed enum: check_magic_numbers.py now reads
    # headers too, and both spellings are what the project rule asks for.
    footer = (
        "\n};\n\n"
        "/** @brief Length of ::k_comic_large_cbz in bytes. */\n"
        "static const uint32_t k_comic_large_cbz_len = (uint32_t)sizeof(k_comic_large_cbz);\n\n"
        "/**\n"
        " * @brief Decoded geometry of the baked oversized page.\n"
        " * @details These are properties of the baked bytes above, not tunables: the\n"
        " * decoder must reproduce exactly this size or the fixture is wrong.\n"
        " */\n"
        "typedef enum : uint32_t {\n"
        f"  k_comic_large_w = {PAGE_W}U, /**< Decoded width in pixels.  */\n"
        f"  k_comic_large_h = {PAGE_H}U, /**< Decoded height in pixels. */\n"
        "} comic_large_geometry_t;\n"
    )
    Path(path).write_text(header + "\n".join(rows) + footer, encoding="ascii")
 
 
def main() -> None:
    """Render the oversized page, pack it into a CBZ, write the C header."""
    out = Path(sys.argv[1]) if len(sys.argv) > 1 else DEFAULT_OUTPUT
    cbz = build_cbz(encode_png(render_page()))
    emit_header(out, cbz)
    sys.stderr.write(f"wrote {out} ({len(cbz)} bytes CBZ, {PAGE_W}x{PAGE_H})\n")
 
 
if __name__ == "__main__":
    main()