How I went from two KDP rejections to seven books live

#!/usr/bin/env python3
"""Measure a KDP full-wrap cover PDF against KDP's print requirements.

Reports facts, not opinions: page geometry, image colour space and true DPI
(recursing into Form XObjects), leftover design guides, bleed coverage, and the
distance from every piece of ink to the trim line.

Usage:
    python verify_kdp_cover.py cover.pdf --pages 150
    python verify_kdp_cover.py cover.pdf --pages 150 --trim 8.5x11 --paper white

Requires: pypdf, Pillow. Raster checks additionally need `pdftoppm` (poppler);
they are skipped with a notice if it is absent.
"""
from __future__ import annotations

import argparse
import shutil
import subprocess
import sys
import tempfile
from dataclasses import dataclass
from pathlib import Path

# KDP constants. Verified against KDP's published paperback specification.
SPINE_PER_PAGE = {
    "white": 0.002252,
    "cream": 0.0025,
    "groundwood": 0.00235,
    "color": 0.002347,
}
BLEED = 0.125           # per outer edge, included in the cover sheet size
SAFE_INSET = 0.25       # text/important art must stay this far inside trim
SPINE_TEXT_MIN_PAGES = 79
SPINE_TEXT_INSET = 0.0625   # spine text must stay this far inside each fold
BARCODE_W, BARCODE_H = 2.0, 1.2
BARCODE_INSET = 0.25    # from the back cover's bottom and right trim
MIN_DPI = 300
RASTER_DPI = 96         # 1 px == 1/96 in, keeps the arithmetic readable

# Neon colours conventionally used for on-canvas KDP guides. KDP bans these.
GUIDE_COLOURS = {
    "cyan (trim)": (0x00, 0xE5, 0xFF),
    "magenta (safe)": (0xFF, 0x00, 0xA8),
    "yellow (spine fold)": (0xFF, 0xD4, 0x00),
    "green (spine safe)": (0x00, 0xFF, 0x66),
    "red (barcode)": (0xFF, 0x00, 0x00),
}


@dataclass(frozen=True)
class Geometry:
    """Derived KDP cover geometry, all values in inches."""

    pages: int
    trim_w: float
    trim_h: float
    paper: str
    spine: float
    cover_w: float
    cover_h: float
    fold_left: float
    fold_right: float


def compute_geometry(pages: int, trim_w: float, trim_h: float, paper: str) -> Geometry:
    """Derive full-wrap cover dimensions from trim size and page count."""
    if paper not in SPINE_PER_PAGE:
        raise ValueError(f"unknown paper {paper!r}; expected one of {sorted(SPINE_PER_PAGE)}")
    spine = pages * SPINE_PER_PAGE[paper]
    cover_w = 2 * trim_w + spine + 2 * BLEED
    cover_h = trim_h + 2 * BLEED
    fold_left = BLEED + trim_w
    return Geometry(
        pages=pages, trim_w=trim_w, trim_h=trim_h, paper=paper, spine=spine,
        cover_w=cover_w, cover_h=cover_h,
        fold_left=fold_left, fold_right=fold_left + spine,
    )


class Report:
    """Collects PASS/FAIL/INFO lines and tracks whether anything failed."""

    def __init__(self) -> None:
        self.failed = False
        self.lines: list[str] = []

    def ok(self, label: str, detail: str) -> None:
        self.lines.append(f"  [PASS] {label}: {detail}")

    def bad(self, label: str, detail: str) -> None:
        self.failed = True
        self.lines.append(f"  [FAIL] {label}: {detail}")

    def info(self, label: str, detail: str) -> None:
        self.lines.append(f"  [INFO] {label}: {detail}")

    def section(self, title: str) -> None:
        self.lines.append(f"\n{title}")

    def render(self) -> str:
        return "\n".join(self.lines)


def iter_images(resources, seen=None):
    """Yield (name, image_object), descending into Form XObjects.

    Canva and most design tools nest every placed image inside a Form XObject.
    A DPI check that does not recurse sees no images at all and silently
    falls back to nonsense.
    """
    seen = set() if seen is None else seen
    xobjects = (resources or {}).get("/XObject")
    if not xobjects:
        return
    for name, ref in xobjects.items():
        try:
            obj = ref.get_object()
        except Exception:
            continue
        key = id(obj)
        if key in seen:
            continue
        seen.add(key)
        subtype = obj.get("/Subtype")
        if subtype == "/Image":
            yield str(name), obj
        elif subtype == "/Form":
            yield from iter_images(obj.get("/Resources"), seen)


def check_geometry(page, geo: Geometry, rep: Report) -> None:
    """Page size, rotation, and stale box entries."""
    box = page.mediabox
    w, h = float(box.width) / 72, float(box.height) / 72
    tol = 0.001
    detail = f"{w:.4f} x {h:.4f} in (need {geo.cover_w:.4f} x {geo.cover_h:.4f})"
    if abs(w - geo.cover_w) <= tol and abs(h - geo.cover_h) <= tol:
        rep.ok("page size", detail)
    else:
        rep.bad("page size", detail)
        extra_w, extra_h = w - geo.cover_w, h - geo.cover_h
        if extra_w > 0.05 and abs(extra_w - extra_h) < 0.02:
            rep.info("page size", f"+{extra_w / 2:.4f} in on every edge — "
                                  "looks like 'crop marks and bleed' was left on at export")

    rotate = page.get("/Rotate")
    (rep.ok if not rotate else rep.bad)("rotation", f"/Rotate = {rotate!r}")


def check_content(page, rep: Report) -> None:
    """Fonts and placed-image colour space / resolution."""
    resources = page.get("/Resources") or {}
    fonts = list((resources.get("/Font") or {}).keys())
    if fonts:
        rep.info("fonts", f"{len(fonts)} present — each must be fully embedded")
    else:
        rep.ok("fonts", "none — text is outlined to vector paths")

    page_w_in = float(page.mediabox.width) / 72
    images = list(iter_images(resources))
    if not images:
        rep.info("images", "none found")
        return
    for name, img in images:
        width = int(img.get("/Width") or 0)
        cs = img.get("/ColorSpace")
        cs = cs if isinstance(cs, str) else (cs[0] if isinstance(cs, list) else str(cs))
        dpi = width / page_w_in if page_w_in else 0
        label = f"image {name}"
        note = f"{width}x{img.get('/Height')} {cs} ~{dpi:.0f} DPI across the full wrap"
        if dpi + 0.5 < MIN_DPI:
            rep.bad(label, note)
        else:
            rep.ok(label, note)
        if cs and "RGB" in str(cs):
            rep.info(label, "RGB — KDP prefers CMYK; export CMYK from the design tool, "
                            "never convert with ghostscript (it crushes saturated reds)")


def rasterize(pdf: Path, out_dir: Path):
    """Render page 1 at RASTER_DPI. Returns a PIL image, or None if unavailable."""
    if not shutil.which("pdftoppm"):
        return None
    stem = out_dir / "page"
    subprocess.run(
        ["pdftoppm", "-png", "-r", str(RASTER_DPI), "-singlefile", str(pdf), str(stem)],
        check=True, capture_output=True,
    )
    from PIL import Image
    return Image.open(f"{stem}.png").convert("RGB")


def check_guides(arr, rep: Report) -> None:
    """Any leftover neon guide shapes would print as bright lines."""
    import numpy as np

    present = {}
    for name, g in GUIDE_COLOURS.items():
        dist = np.abs(arr - np.array(g, dtype=np.int16)).sum(axis=2)
        count = int((dist < 60).sum())
        if count > 80:
            present[name] = count
    if present:
        rep.bad("design guides", f"leftover guide pixels {present} — delete them and re-export")
    else:
        rep.ok("design guides", "none detected")


def check_bleed(arr, rep: Report) -> None:
    """White along an outer edge means the art stops short of the bleed."""
    import numpy as np

    white = (arr > 248).all(axis=2)
    edges = {
        "left": white[:, 0], "right": white[:, -1],
        "top": white[0, :], "bottom": white[-1, :],
    }
    worst = [f"{n} {int(e.mean() * 100)}% white" for n, e in edges.items() if e.mean() > 0.02]
    if worst:
        rep.bad("bleed", f"{', '.join(worst)} — art does not reach the edge")
    else:
        rep.ok("bleed", "art covers all four outer edges")


def check_ink_margins(arr, geo: Geometry, rep: Report) -> None:
    """Distance from the trim line to the nearest non-background ink, per edge.

    Background is sampled from the page's own corners, so this works whether
    the cover sits on cream, white, or a dark field.

    A foreground run must be at least MIN_RUN px thick to count. Without that,
    a single antialiased pixel at a panel boundary reads as "ink at the trim
    line" and the whole measurement is wrong -- the exact false positive that
    makes eyeballed diagnoses unreliable.
    """
    import numpy as np

    h, w, _ = arr.shape
    d = int(round(BLEED * RASTER_DPI))
    corners = [arr[1, 1], arr[1, w - 2], arr[h - 2, 1], arr[h - 2, w - 2]]
    bg = np.zeros((h, w), dtype=bool)
    for c in corners:
        bg |= np.abs(arr - c.astype(np.int16)).sum(axis=2) < 45
    fg = ~bg
    fg[:d, :] = fg[-d:, :] = False           # ignore the bleed band itself
    fg[:, :d] = fg[:, -d:] = False

    MIN_RUN = 3
    col_counts, row_counts = fg.sum(axis=0), fg.sum(axis=1)
    cols = np.flatnonzero(col_counts >= MIN_RUN)
    rows = np.flatnonzero(row_counts >= MIN_RUN)
    if cols.size == 0 or rows.size == 0:
        rep.info("ink margins", "no distinct foreground found; inspect visually")
        return

    found = {
        "left": (cols[0] - d) / RASTER_DPI,
        "right": ((w - d) - cols[-1]) / RASTER_DPI,
        "top": (rows[0] - d) / RASTER_DPI,
        "bottom": ((h - d) - rows[-1]) / RASTER_DPI,
    }
    # Deliberately INFO, never FAIL. This finds the nearest non-background pixel,
    # which on a full-bleed cover is the artwork -- and artwork reaching the trim
    # is correct. Only a human (or a text-aware check) can say whether the thing
    # near the trim is art that should bleed or type that must stay inside.
    for edge, inches in sorted(found.items(), key=lambda kv: kv[1]):
        rep.info(f"nearest content {edge}", f"{inches:.3f} in inside trim")
    rep.info(
        "reading these",
        f"artwork at ~0.000 is correct on a bleed cover; confirm no TEXT is "
        f"closer than {SAFE_INSET} in by eye or by measuring the text colour only",
    )


def main() -> int:
    ap = argparse.ArgumentParser(description="Verify a KDP full-wrap cover PDF.")
    ap.add_argument("pdf", type=Path)
    ap.add_argument("--pages", type=int, required=True, help="interior page count")
    ap.add_argument("--trim", default="8.5x11", help="trim size, e.g. 8.5x11 or 6x9")
    ap.add_argument("--paper", default="white", choices=sorted(SPINE_PER_PAGE))
    args = ap.parse_args()

    trim_w, trim_h = (float(v) for v in args.trim.lower().split("x"))
    geo = compute_geometry(args.pages, trim_w, trim_h, args.paper)

    print(f"KDP cover check — {args.pdf.name}")
    print(f"  {args.pages} pp, {trim_w}x{trim_h} in, {args.paper} paper")
    print(f"  spine {geo.spine:.4f} in; cover sheet {geo.cover_w:.4f} x {geo.cover_h:.4f} in")
    print(f"  spine folds at x = {geo.fold_left:.4f} and {geo.fold_right:.4f} in")
    if args.pages < SPINE_TEXT_MIN_PAGES:
        print(f"  NOTE: under {SPINE_TEXT_MIN_PAGES} pp — KDP does not allow spine text")

    from pypdf import PdfReader
    reader = PdfReader(str(args.pdf))
    rep = Report()

    rep.section("Structure")
    if len(reader.pages) != 1:
        rep.bad("page count", f"{len(reader.pages)} pages — a cover must be exactly 1")
    else:
        rep.ok("page count", "1")
    page = reader.pages[0]
    check_geometry(page, geo, rep)
    check_content(page, rep)

    rep.section("Rendered ink")
    with tempfile.TemporaryDirectory() as td:
        img = rasterize(args.pdf, Path(td))
        if img is None:
            rep.info("raster checks", "skipped — pdftoppm (poppler) not on PATH")
        else:
            import numpy as np
            arr = np.asarray(img).astype(np.int16)
            check_guides(arr, rep)
            check_bleed(arr, rep)
            check_ink_margins(arr, geo, rep)

    print(rep.render())
    print("\n" + ("RESULT: problems found" if rep.failed else "RESULT: all checks passed"))
    return 1 if rep.failed else 0


if __name__ == "__main__":
    sys.exit(main())