Add Plustek (USB) scanner backend for OpticFilm 8200i SE and enable the Scan tab on Windows

[jboneng]

Summary

Adds a first-party Plustek (USB) scanner backend and enables the Scan tab on Windows by integrating the external pyopticfilm driver (PyUSB / libusb) for the OpticFilm series.

Until now, film-scanner acquisition went only through SANE (python-sane), which is unavailable on Windows, so the Scan UI was a placeholder there. This PR:

• Integrates pyopticfilm via a thin adapter at negpy/infrastructure/scanners/plustek_backend.py (same ScannerBackend / ScanResult pattern as SANE)
• Registers pyOpticfilm (Plustek) in the backend registry and turns on ScanSidebar on Windows
• Decouples prescan UI from driver internals via ScannerCapabilities (prescan_dpi, prescan_mirror_x, prescan_default_crop) and shared helpers in params.py
• Documents WinUSB setup and optional pyopticfilm install
• Hardens SE colour/IR capture (geometry, ASIC shading / host fallback, IR registration) and capability-gates Scan UI controls

Supported scan hardware today: Plustek OpticFilm 8200i SE only (07b3:1825, GL128). Other OpticFilm PIDs may enumerate/probe but are locked out of scan until validated.

Driver packaging: device-specific code lives in pyopticfilm (PyPI >=1.0, currently 1.1.1). NegPy does not vendor the driver tree.

Backend selection

Platform	Backends in the dropdown	Default
Windows	Plustek (USB) only	plustek
macOS / Linux	SANE + Plustek (USB)	sane

Persisted backend: "sane" on Windows is coerced to plustek on load so old settings do not try to open python-sane.

Architecture

ScanSidebar → ScanWorker → ScannerService → create_backend("plustek") → PlustekBackend (adapter) → pyopticfilm.Scanner → pyusb / libusb-package

• Colour + IR = two USB passes when capture_ir is enabled; IR is registered to RGB with whole-pixel phase correlation after the carriage re-homes
• Missing pyopticfilm / PyUSB → ScannerUnavailable with install / WinUSB hint (soft fail; app still runs)
• USB transport glitches → TransientScanError (ScannerService retries)
• Guard test: only plustek_backend.py may import pyopticfilm

SE capture quality (post-landing fixes on this branch)

• Full-window geometry at every supported PPI so scans clear the motor gate (Lab-aligned window, not a bare area that stalls feed)
• GL128 color ASIC shading (DVDSET) builds a per-pixel RGB dark/gain table from post-unity white strips; if gain validation fails but the dark/white strips are still usable, DVDSET stays off and host dark/white stretch is used instead.
• Shear fix: keep Full-window line width (~2592 @ 1800) and pad the shading table rather than shrinking image X to AHB width
• Host-path border clamp: after exposure makeup, clamp Full-window holder-chrome highlights to the film-inset peak so NegPy auto-bounds are not skewed by chrome
• Calib cache versioned in pyopticfilm (~/.cache/pyopticfilm/); NegPy adapter cache under plustek_calib/ — see docs/PLUSTEK_WINDOWS.md troubleshooting

Scan UI capability gating

Controls appear only when the selected device reports a real choice / feature:

Control	Shown when
Autofocus	caps.autofocus (SANE when "autofocus" in opt; Plustek SE = false)
Auto-exposure	caps.auto_exposure (SANE ae; Plustek SE = false)
Depth	len(supported_depths) > 1 (Plustek SE is 16-bit only → hidden; sole depth still sent in scan params)
Prescan	caps.prescan (8200i SE: 1200 dpi preview, interactive crop)
Exposure / Frames	unchanged (range / capacity as before)

Packaging

• Driver is external: pyopticfilm on PyPI (not in-tree)
• Optional install paths:

  [project.optional-dependencies]
  plustek = ["pyopticfilm>=1.0"]
  
  [dependency-groups]
  plustek = ["pyopticfilm>=1.0"]
  

• uv sync --group plustek
• pip install negpy[plustek]
• pyusb / libusb-package are not core NegPy deps — pulled in via pyopticfilm
• CI: uv sync --group dev --group plustek
• Windows release: uv sync --group plustek --no-group scanner; PyInstaller bundles pyopticfilm + libusb
• Plustek adapter unit tests stub usb / usb.core so they pass without hardware (CI)
• ASIC shading / driver internals tested in pyopticfilm repo; NegPy keeps adapter contract tests only
• SANE/genesys + pyopticfilm attribution in NOTICE.md

Docs

• docs/PLUSTEK_WINDOWS.md — Zadig / WinUSB steps + SE calib troubleshooting
• README, CONTRIBUTING, USER_GUIDE §13, CHANGELOG updated (pyopticfilm optional dep + capability-gated controls)

Known follow-ups (out of scope)

-Non-SE OpticFilm models: enumerate but do not scan until validated in pyopticfilm

Future ToDos

• Validate ported model tables for other OpticFilm variants on real hardware in pyopticfilm, then flip scan_ready per model

Test plan

• uv sync --group dev --group plustek (resolves pyopticfilm==1.1 from PyPI)
• uv run pytest tests/scanners/test_backend_registry.py tests/scanners/test_plustek_backend.py tests/scanners/test_capabilities.py tests/test_scan_sidebar.py -q
• Plustek adapter tests pass without PyUSB installed (stub / CI simulation)
• test_only_adapter_imports_plustek_driver — no pyopticfilm imports outside adapter
• Windows: Scan tab opens (no “unsupported” placeholder); Backend shows only Plustek (USB)
• Windows: Without scanner / without WinUSB — refresh lists empty devices (or clear hint), no SANE traceback
• Windows + SE + WinUSB: list OpticFilm 8200i SE → colour scan @ 1800 → TIFF opens via asset discovery
• Same with IR enabled → RGB + _IR sidecar / dust path works
• SE Scan UI: Autofocus, Auto-exposure, and Depth hidden; Prescan + IR available
• Windows + SE + WinUSB: colour scan @ every supported PPI → TIFF opens
• Windows + SE + WinUSB: colour + IR @ every supported PPI → TIFF opens
• Linux/macOS: Backend dropdown offers SANE and Plustek (USB); default remains SANE
• Saved settings with backend: "sane" on Windows do not crash; coerce to Plustek
• Coolscan-like device (multi depth + AF/AE): Depth / Autofocus / Auto-exposure visible and flow into scan params (SANE backend)
• Plustek HW other than 8200i SE: detect/show in dropdown, but do not allow scan (unvalidated motor path) (Plustek USB backend)