Image extraction from PDF: extract_images.py for picture-page embedding

[Arkoniak]

Background

Picture pages (cover, illustrations) are currently skipped in build_html.py — they produce no HTML output. For a correct EPUB they must be embedded as <figure><img src="images/page_NNN.jpg"/> so Pandoc can include them in the EPUB container.

The cover specifically goes via --epub-cover-image in the Pandoc call, not as inline <figure>.

Plan

Write scripts/extract_images.py:

• Input: PDF path + page list (or "all picture pages" from a consensus summary.json)
• Render each page as JPEG/PNG via PyMuPDF (fitz) at a target DPI (150–200 dpi for body illustrations; 300 dpi for cover)
• Output: books/output/<book>/images/page_NNN.jpg
• Print a manifest of extracted images (page → path) for use by build_html.py and the Pandoc call

Usage in the pipeline

# After consensus is run:
uv run python scripts/extract_images.py --book mindblast --pdf books/input/mindblast.pdf

# build_html.py picks up images/ directory automatically
uv run python scripts/build_html.py --book mindblast

# Pandoc uses --resource-path to find images/
pandoc book.html --resource-path books/output/mindblast/consensus/full -o mindblast.epub ...

Depends on

• Enrich consensus with voted_tokens + build per-page HTML fragments #30 (consensus output identifies picture pages via picture_page: true)

Required by

• Page-level classifier: content / chapter_opener / special_page / picture #33 (page classifier — picture pages emit <figure><img>)
• EPUB assembly via Pandoc (HTML canonical) + metadata from ISBN #23 (EPUB assembly — cover via --epub-cover-image)

Acceptance criteria

• extract_images.py produces images/page_NNN.jpg for each picture page
• Cover image (page 1) is extracted at higher resolution
• Images are referenced correctly in book.html after Page-level classifier: content / chapter_opener / special_page / picture #33 is done
• Pandoc embeds them into the EPUB without manual intervention