Levandor

KB wiring-gallery low-res fix (use marker-native crops) + Astro cache-control

4 min read

Two KB serving fixes on telep-mainframe. (1) The /wiring-gallery/ scanned diagrams were low-res not because of OCR but because a separate thumbnailing step downscaled the figure crops — fixed by copying the marker-native original crops verbatim (~2.5× sharper). (2) Flask app.py now sends correct Cache-Control headers (immutable for fingerprinted /_astro/*, no-cache for everything else) to stop stale-HTML / missing-image issues after redeploys. Follows the gallery pivot in 2026-07-30-kb-wiring-gallery-pivot-complete.

For Agents

  • The wiring-gallery images were downscaled by gen_thumbs.py, NOT by OCR. marker extracted the figure crops at native res; /home/levander/wiring-collection/gen_thumbs.py then shrank them to WIDTH=320, quality=72 for the gallery, and the gallery served the thumbnails.
  • Fix = copy the marker-native originals (the image_abs path in /home/levander/wiring-collection/gallery_items.json) into both manuals-src/docs/assets/wiring-gallery/ and kb-astro/public/wiring-gallery/img/. ~2.5× sharper (320 px → ~822 px).
  • ~822 px is the real detail ceiling — the source manual scans are only 150 dpi. Re-rendering PDF pages at 300 dpi is pointless upscaling.
  • build_content.py does NOT touch the wiring-gallery dirs — the copied originals are durable across rebuilds.

1. Wiring-gallery low-res — cause and fix

Symptom

The /wiring-gallery/ scanned diagrams were very low-res: 480 images, ~7 MB total, ~12–20 KB each.

Cause (NOT the OCR)

OCR / text extraction was fine. The pipeline was:

graph LR
    PDF["manual PDF<br/>(150 dpi scan)"] --> M["marker (marker-pdf / Surya OCR)<br/>native-res figure crops"]
    M --> T["gen_thumbs.py<br/>WIDTH=320, quality=72"]
    T --> G["/wiring-gallery/<br/>(served the THUMBNAILS)"]
    style M fill:#264653,stroke:#2a9d8f,color:#fff
    style T fill:#3d2020,stroke:#888,color:#fff

marker (marker-pdf / Surya OCR) extracted the figure crops at native resolution; /home/levander/wiring-collection/gen_thumbs.py downscaled them to WIDTH=320, quality=72 for the gallery, and the gallery used those thumbnails. So the loss was entirely in the thumbnailing step.

Fix

Copy the marker-native originals verbatim — their paths are in the image_abs field of /home/levander/wiring-collection/gallery_items.json — into both:

  • manuals-src/docs/assets/wiring-gallery/
  • kb-astro/public/wiring-gallery/img/

Result: ~2.5× sharper (e.g. 320 px → ~822 px).

The real ceiling

~822 px is the detail ceiling — do NOT re-render at 300 dpi

The source manual scans are only 150 dpi, so ~822 px is the true detail ceiling; re-rendering the PDF pages at 300 dpi would just be upscaling with no new detail. And marker’s *_meta.json has NO per-figure bounding boxes, so you can’t re-crop the figure regions from a fresh high-DPI render without re-running marker end-to-end. If genuinely higher resolution is ever needed, that means a full marker re-run on higher-dpi page renders, not a crop-from-existing.

Durability

build_content.py does not touch the wiring-gallery directories, so the copied marker-native originals survive KB rebuilds — no need to re-copy after a build_content.py run.

2. Astro cache-control in Flask app.py

Cache headers that stop stale-HTML / missing-image after a redeploy

Flask app.py now sets:

  • Cache-Control: immutable for /_astro/* (Astro’s content-fingerprinted assets — safe to cache forever)
  • no-cache for everything else (HTML etc.)

This stops the post-redeploy failure where a browser served stale HTML referencing old fingerprinted asset names (→ missing images / broken page) after an atomic dist → ~/knowledgebase/site swap.

Graph View

Backlinks