photo-to-scanned-pdf

Photo → Scanned PDF

Two related pipelines, same destination look, different starting point:

phone photos of paper documents, or a digital document that needs a synthetic

signature before it looks signed. The pipelines that work, and the failure

modes that ship wrong PDFs if skipped.

Which one do you need?

| The input is... | Use |

|---|---|

| Phone photos of an already-signed/stamped paper document | This file, main pipeline below |

| A digital document (docx/PDF) with no signature yet, and you need to make it look hand-signed | [references/digital-signature-synthesis.md](references/digital-signature-synthesis.md) |

photos ──► rectify (photo_to_scan.py --raw)
       ──► ORDER BY CONTENT, detect colored paper   ← agent eyes, not filenames
       ──► enhance: noteshrink (white batch with -g │ colored pages separately,
                                after white-balance pre-pass)
       ──► assemble_pdf.py → A4 PDF
       ──► make_contact_sheet.py → READ IT, verify EVERY page   ← mandatory

Division of labor: scripts carry execution; you (the agent) carry the two

judgment steps — content-based page ordering, and whole-document verification.

Neither can be automated away: filenames lie about order, and per-page spot

checks miss wrong-slot bugs. The digital-signature branch shares this same

philosophy with its own two judgment calls — see the reference file.

Step 0 — Dependencies

which pdftoppm || brew install poppler   # contact sheet + any PDF rendering
uvx noteshrink --help | head -3          # first run builds it (~30 s)

Scripts are uv run single-file scripts (PEP 723); OpenCV/PIL/img2pdf resolve

automatically on first run.

Step 1 — Rectify

uv run <skill>/scripts/photo_to_scan.py --raw --out-dir work --prefix page \
    photo1.jpg photo2.jpg ...

Expected: one page_NN.jpg per photo, each tagged [quad]. A

[FULLFRAME-fallback] tag means the paper outline wasn't found (busy background,

page cut off) — view that photo and decide: retake, or accept the uncropped frame.

The script handles EXIF rotation internally (cv2.imread ignores EXIF; phone

photos come rotated — this silently produces sideways pages if you rectify with

raw OpenCV).

Step 2 — Order by content, detect colored paper (agent judgment)

Read every rectified image (batch of ~6 per message) and record two things:

1. Its identity — date, title, page number, whatever distinguishes pages.

Batch-exported photos (WeChat, AirDrop) get timestamps of the export

moment, often all within one second — filename order is meaningless. Real

case: 17 photos turned out to be in exact reverse document order; only

content reading caught it.

1. Its paper color — white, or colored (blue/yellow/pink stock)? Colored

pages take a different path in Step 3. If unsure, sample programmatically:

mean RGB of a blank region; B > R + 25 ⇒ blue-ish paper.

Build the final page order as an explicit list before proceeding. If pages are

supposed to match an external register (an invoice list, a session table),

cross-check identity against it now — missing/duplicate pages found here cost

seconds; found after delivery they cost a redo.

Step 3 — Enhance (noteshrink, split by paper color)

White-paper pages — one batch, global palette:

uvx noteshrink -w -g -K -q -b ns -c "true" page_03.jpg page_01.jpg page_07.jpg ...
# inputs IN FINAL PAGE ORDER → outputs ns0000.png, ns0001.png, ... in that order

• -w white background, -g one global palette (uniform ink/stamp color across

pages), -K keep given order, -c "true" skips its internal PDF step (we

assemble ourselves).

• Pass filenames explicitly. zsh does not word-split $VAR — a file list in

a variable arrives as one giant "filename", noteshrink exits without output,

and -q keeps it silent. Verify outputs exist (ls ns0*.png) rather than

trusting stdout.

Colored-paper pages — separate, with white-balance pre-pass:

uv run <skill>/scripts/photo_to_scan.py --out-dir work --prefix wb colored_photo.jpg   # no --raw
uvx noteshrink -w -g -K -q -b nc -c "true" work/wb_01.jpg

Two distinct failure modes force this split (both shipped as bugs before the

rule existed):

1. Colored pages inside the -g batch poison the whole document — the paper

color enters the global palette and white pages come out with tinted

shadows/artifacts.

1. **noteshrink alone on colored paper whitens the background but not the

foreground cast** — black ink photographed on blue stock reads blue-purple, a

red stamp reads maroon. The default (non---raw) mode of photo_to_scan.py

divides out the paper color first, so ink returns to black and stamps to red.

Step 4 — Assemble

uv run <skill>/scripts/assemble_pdf.py --out scanned.pdf \
    ns0000.png ns0001.png nc0000.png ns0002.png ...   # FINAL page order

Expected: OK scanned.pdf (N pages, ~0.05 MB/page). Edge crop (default

24px top / 12px sides at 200 dpi) removes the sliver of desk surface that

rectification drags in along page borders; document margins dwarf it.

Step 5 — Verify the WHOLE document (mandatory, not optional)

uv run <skill>/scripts/make_contact_sheet.py scanned.pdf --out contact.png

Read contact.png and check every page: identity sequence complete and

correct (each date/title where it should be, no duplicates, none missing), no

off-color page, stamps/signatures present. Then spot-read 1–2 pages at full

resolution for text sharpness.

Why whole-document, every time: two shipped-bug stories from the session this

skill was distilled from —

• A page-replacement task wrote the new page into the wrong slot (an

off-by-one in a copy command), silently overwriting a neighboring page. The

per-page check of the replaced slots passed; the clobbered neighbor was only

caught by the user.

• A palette-poisoning bug (Step 3 #1) tinted pages that were not being

edited. Checking only the edited pages missed it.

The cost asymmetry is absolute: contact sheet = one Read; a wrong page in a

delivered PDF = redo + lost trust. **"I verified the pages I changed" is not

verification.**

Replacing pages in an existing scanned PDF

Keep the per-page enhanced PNGs (ns/nc) as the working set. To replace page

k: process the new photo through Steps 1–3, overwrite that page's PNG, re-run

Steps 4–5. When copying into numbered slots, mind the mapping — slot numbers

shift when photo order was reversed; derive the slot from the page's *content

identity*, never from its position in the photo batch. Then the Step 5 full

check is what actually protects you.

Troubleshooting

| Symptom | Cause / fix |

|---|---|

| Output "doesn't look scanned" — gray haze, soft text | You hand-rolled levels/curves/divide enhancement. Don't — two attempts were rejected by a real user before switching to noteshrink (background sampling + palette quantization is what produces the flat-white scan look). |

| White pages have tinted shadows | A colored-paper page was inside the -g batch. Re-run whites-only batch (Step 3). |

| Ink looks blue/purple, stamp looks maroon on a colored page | noteshrink got the colored page raw. Insert the white-balance pre-pass (photo_to_scan.py without --raw). |

| noteshrink produced no output, no error | File list passed via an unquoted shell variable under zsh (no word splitting), or paths with spaces. Pass explicit filenames; check ls ns0*.png. |

| Page sideways / upside down | EXIF ignored somewhere upstream, or the quad landed landscape. photo_to_scan.py corrects EXIF + rotates to portrait; upside-down pages it cannot know — catch at Step 2 and rotate the source photo. |

| [FULLFRAME-fallback] on a photo | Paper outline not detected (low contrast vs table, page cut off). Retake against a dark background, or accept full frame + rely on edge crop. |

| Thin dark strip along page edge in the PDF | Desk surface dragged in by rectification. Raise --crop-top/--crop-side in assemble_pdf.py. |

| Pages in wrong order in the PDF | Filename-order assumption. Order comes from Step 2 content reading, passed explicitly to noteshrink (-K) and assemble_pdf.py. |