Menu ▾ ▴

#42 Create a PDF from a scanner

open
nobody
None
2026-11-08
2026-11-06
Anonymous
No

Originally created by: rohanvijaykumar

Closes [#35] (suggested by @Lehnemann).

Draft. Scanning for 1.3.0, as planned in PLAN-SCANNING-AND-CERTIFICATES (Part 1): every way of reaching a scanner, a scan dialog in the style of the print dialog with everything Acrobat's Create ▸ Scanner and Custom scan settings offer, and the entry points Acrobat has. CI machines have no scanner: the scanner-facing code is tested against stand-ins, a pretend network scanner, and the TWAIN Working Group's sample scanner (on GitHub's Windows runner only).

This branch merges the parallel work: scan/win-helper (Windows helpers), scan/escl-mac (network scanners, Mac helper v2, the pretend eSCL scanner) and scan/image (clean-up worker, CCITT G4, PDF builder).

What it does

  • Where: Create ▸ Scanner; All tools ▸ Create a PDF ▸ Scanner and Convert ▸ Create PDF from (a Paperwing tool in catalog.ts, found by tool search for "scan"/"scanner"); All tools ▸ Scan & OCR is a start page like Acrobat's (Select a file · Scan a document with Recognize text on · Enhance scanned pages); Insert pages from scanner… in the page thumbnails' menu (Acrobat's Insert Pages choice: before/after, first/last/page N); main menu ▸ Create PDF from scanner ▸ a preset scans straight away (also File ▸ Create PDF from Scanner ▸ in the macOS menu bar); command palette. The scan menu command stays.
  • Scanners, listed once (desktop/scan.cjs v2): the x64 and x86 Windows helpers (WIA 2/1, TWAIN 64/32), the Mac helper (Image Capture) and escl.cjs (AirScan/eSCL) run together; devices sharing a deviceKey (or an eSCL uuid = Image Capture deviceKey) are one entry, best driver first (Windows TWAIN-64 > WIA 2 > eSCL > TWAIN-32 > WIA 1; Mac eSCL > ICA), the others under Options ▸ Driver. Options also has the scanner's own window (the helper gets -Window so it opens in front; no time limit while it's open), TWAIN transfer method, invert black and white, stop on double-feed, and how long to wait for a slow network scanner. Add by IP address… (remembered), Refresh, and Import from a scanner app (watches a chosen folder; half-written files wait until complete).
  • The dialog (scan.ts + scan-settings.ts, scan-preview.ts, scan-review.ts, scan-process.ts): presets at the top (My settings, Autodetect color mode, Black and white / Grayscale / Color document, Color photograph, Save as preset…), then Scanner, Pages (source, front/both sides, flip back sides), Image (color mode + threshold, resolution incl. custom, paper sizes that fit + auto + custom W×H in/mm + orientation, brightness, contrast, a network scanner's own sharpness), Clean-up (deskew on by default, auto-crop, background removal, descreen, text sharpening, despeckle, remove blank pages + sensitivity, edge shadows, auto-rotate, rotate all), File size (Small ↔ High quality, JPEG/ZIP; black and white is CCITT G4; Compress after scanning opens Compress a PDF, since Hyper Compress has no adaptive compression), Output (new PDF / append to an open document or Browse… for any PDF / save multiple files; prompt to scan more; Recognize text with language; PDF/A; Add metadata). Settings a scanner can't do are hidden; what it can't do itself is done by scan-image afterwards. Settings are kept per preset and per scanner.
  • Right side: flatbed Preview with the document boxed (detectDocument) and draggable corners (also arrow keys); pages arrive as thumbnails and are cleaned up in the worker; after each pass rotate, delete, drag (or Ctrl+arrows), rescan, keep a page found blank; Scan more pages / Scan reverse sides (interleaved) / Scan is complete, the last choice offered first.
  • Results: a new unsaved "Scan YYYY-MM-DD HH.MM.pdf" (recovered after a crash); appended/inserted with one undo step; a PDF that isn't open is opened with the pages added, never written behind your back; several files saved into a chosen folder; OCR runs right after scanning with the app's Tesseract; PDF/A with the app's Ghostscript (falls back to a message).
  • Errors in plain words: no scanner (with tips), busy, offline, jam, feeder empty, double-feed, cover open, unsupported settings, blocked (Windows: IT policy; Mac: Local Network permission, with Search again). Cancel/Stop always lets the scanner go (stdin cancel, killed after 10 s).
  • Stand-in scanners (desktop/scan-test.cjs, development builds only, not packaged): three scanners (one through three drivers, a gray one-sided feeder with a resolution range, a network-only flatbed), a preview of a crooked page on the glass, ranges, auto-size, blank and crooked pages, errors after n pages.

Tests

  • node --test desktop/tests/scan.test.mjs: 35 (+3 run only on CI with the TWAIN sample through the real helpers): contract, caps, merging (incl. eSCL uuid ↔ Image Capture), routing, streaming, cancel and kill, errors, one job at a time, folder watching with partial writes, the eSCL adapter, the stand-in scanners. With escl.test.mjs: 89 pass, 2 skipped (multicast/CI-only).
  • vitest: paperwing-scan.test.ts 27 (settings visibility from caps, presets and what's remembered, the request/clean-up split, interleave, multiple-file splitting, insert positions, names, messages); with scan/image's tests 90 across the scan files. Full suite: 1431 pass; 9 fail locally in unrelated suites because of this worktree's junctioned node_modules (Vite denies the path) — they pass on CI (Linux test job green).
  • Benches (real Electron, real clicks; Windows):
  • check-scan.mjs 57/57: entries per scanner, Options ▸ Driver, Preview box + dragging a corner (page = box size), more pages, feeder + reverse sides, last choice first, rotate/delete/drag/Ctrl+arrow/rescan, blank left out and kept, append to the open document + undo, jam, double-feed after 2 pages, Stop mid-scan and the scanner free again, no scanners, blocked.
  • check-scan-more.mjs 65/65: settings per scanner, every group, custom dpi/size (in↔mm), presets + Save as preset + remembered, menu preset scans at once, save multiple files (3×2 pages), insert at page N and before the first, append via Browse… (file on disk untouched; undo), OCR text present in the PDF, PDF/A metadata, Compress after scanning, Convert/All tools/search entries, Scan & OCR start page, Enhance scanned pages + undo, Import from a scanner app (half-written PDF waits), Add by IP address, recovery after a crash.
  • check-scan-network.mjs 10/10: the app's real eSCL code against fake-escl.mjs (add by IP, caps, sharpness, preview, flatbed, two-sided feeder).
  • Existing benches still pass: check-shell 24, check-qol 25, check-ui12 36, check-branding OK, check-print 5, check-forms 49, check-results (all), check-copy-text 10, check-open-running 18.
  • CI is green on the latest commit (Tests incl. Windows jobs, macOS, CodeQL): Windows helper build + 167 C# tests, the helpers with no scanner, the TWAIN sample through the helpers and through scan.cjs, eSCL tests (multicast on Windows), macOS helper build, eSCL + Bonjour/Image Capture test, and all scanning benches in the macOS workflow.

Not verifiable here

Real WIA, real TWAIN drivers other than the sample, real Image Capture scanners, real network scanners, auto-rotate on real upside-down pages (it reads the page at each quarter turn with Tesseract; Tesseract's own orientation data isn't shipped). Insert from scanner isn't inside BentoPDF's Organize pages tool (that would patch BentoPDF); it's in Paperwing's page menu and palette.

🤖 Generated with Claude Code

Related

Tickets: #35

Discussion


Log in to post a comment.