pyopticfilm

Python driver for Plustek OpticFilm USB film scanners, built on PyUSB and reverse-engineered from USB captures and the SANE genesys backend.

The library talks directly to the scanner’s Genesys ASIC (GL842, GL843, GL845, or GL128) over USB—no vendor Windows driver is required once the device is bound for libusb access.

Supported hardware

Only the OpticFilm 8200i SE and OpticFilm 8100 (V2) is hardware-tested for scanning in this release.

Support is one of:

• Hardware tested — live scan + park on physical hardware
• Protocol validated — USB/register traces match a golden setup without hardware; motors stay locked
• Experimental — tables and session code exist; scan/home/park/calibrate stay locked

Other OpticFilm models enumerate and open: you can read status, turn the lamp on/off (where implemented), and dump registers for bring-up. scan(), calibrate(), home(), and park() stay gated until a model is hardware-tested—calling them raises AsicError rather than risking carriage or lamp damage. Protocol validation does not flip that gate. See docs/scanner-validation.md.

Scanner.open() prefers a scan-ready 8200i SE when several Plustek film scanners are connected.

Features

• Color and infrared transparency scans at 150–7200 dpi (ASIC programs at ≥600 dpi; lower PPI shares the 600 dpi register set and is downsampled on the host; infrared is available only on supported hardware))
• Infrared as a dust plane on ScanImage.ir (mode="infrared", or infrared=True with colour)
• Multi-exposure (ME): short + long colour passes with host SNR/IVW merge into ScanImage.rgb (multi_exposure=True); bracket planes via Scanner.last_me_debug
• Optional crop via normalized area (x1, y1, x2, y2 in 0–1)
• Dark/white shading calibration with on-disk cache (~/.cache/pyopticfilm/calib_v2.json)
• GL128 ASIC shading path (AFE codes + shading blob) aligned with SilverFast capture order
• Adaptive quiet USB drain on GL128 (line-aligned; keeps motor creep continuous at high PPI)
• Left–right orientation corrected in ImagePipeline.assemble() for mirror_x models
• 16-bit RGB numpy output; optional TIFF export via tifffile
• Progress and cancel hooks for long scans

Not implemented or out of scope here: iSRD infrared dust removal, SilverFast-style UI, or shipping a desktop app—applications own post-processing.

Changelog

See CHANGELOG.md for release notes. Latest release: v1.1.2 on GitHub.

Requirements

• Python ≥ 3.11
• numpy, pyusb
• libusb 1.0 backend for PyUSB
  • Windows: libusb-package is installed automatically with pip install pyopticfilm and provides a bundled libusb-1.0.dll
  • Linux: system libusb-1.0 (e.g. libusb-1.0-0 on Debian/Ubuntu) and permission to access the device (udev rule or run as root—not recommended)
  • macOS: libusb via Homebrew or libusb-package

Optional: tifffile for ScanImage.save_tiff().

Installation

pip install pyopticfilm

From source:

git clone https://github.com/jboneng/pyopticfilm.git
cd pyopticfilm
uv sync --all-groups

USB access

The Plustek vendor driver must not own the device when using this library.

Windows

Use Zadig to replace the vendor driver with WinUSB (or libusbK) for the scanner’s USB interface. Step-by-step instructions, troubleshooting, and how to revert to the Plustek driver are in docs/windows-setup.md.

Linux

Install libusb and add a udev rule granting your user access to Plustek film scanners, for example:

# /etc/udev/rules.d/99-plustek-opticfilm.rules
SUBSYSTEM=="usb", ATTR{idVendor}=="07b3", MODE="0666"

Reload udev rules and replug the scanner.

Quick start

from pyopticfilm import Scanner

with Scanner.open() as scanner:
    print(scanner.model.model, scanner.device_id)
    scanner.warmup()  # init, home, lamp on
    image = scanner.scan(resolution=1800, mode="color")
    print(image.rgb.shape, image.rgb.dtype)  # H×W×3 uint16

    image.save_tiff("frame.tif")  # requires tifffile

Infrared scan (8200i SE):

with Scanner.open() as scanner:
    scanner.warmup()
    ir = scanner.scan(resolution=1800, mode="infrared")

Multi-exposure (8200i SE / GL128): short then long colour passes (3× exposure). The SNR/IVW-merged deliverable with film-base makeup is in rgb. Bracket planes and fusion stats are on :attr:~pyopticfilm.scanner.Scanner.last_me_debug (Scan Lab / audit tooling only — not part of the NegPy-facing ScanImage).

with Scanner.open() as scanner:
    scanner.warmup()
    image = scanner.scan(
        resolution=1800,
        mode="color",
        multi_exposure=True,
    )
    print(image.rgb.shape)  # SNR/IVW merged deliverable
    image.save_tiff("merged.tif")
    debug = scanner.last_me_debug
    if debug is not None:
        from pyopticfilm.image import save_rgb16_tiff

        save_rgb16_tiff(debug.rgb_short, "short.tif", dpi=image.dpi)
        save_rgb16_tiff(debug.rgb_long, "long.tif", dpi=image.dpi)
        print(debug.exposure_short, debug.exposure_long)  # e.g. 14000, 42000

Colour + IR in one call (IR after the colour / ME passes):

image = scanner.scan(
    resolution=1800,
    mode="color",
    multi_exposure=True,
    infrared=True,
)
# image.rgb is the merged deliverable; image.ir is HxW uint16

Crop (normalized coordinates on the transparency window):

image = scanner.scan(
    resolution=2400,
    mode="color",
    area=(0.1, 0.1, 0.9, 0.9),  # x1, y1, x2, y2
)

List devices without opening:

from pyopticfilm.usb.device import find_devices

for info in find_devices():
    print(info.device_id, info.product_id, info.asic_hint, info.is_supported)

API overview

ScanImage fields: rgb (uint16 H×W×3), dpi, device_model, optional ir. For ME scans, rgb is the SNR/IVW-merged deliverable (with film-base makeup). Bracket planes live on Scanner.last_me_debug, not on ScanImage.

Scan modes: "color", "infrared". "gray" is not implemented.

scan(..., multi_exposure=True) is GL128 / 8200i SE only. When ME is on, rgb is always SNR/IVW-merged (per-channel clip confidence, soft highlight roll-off from ~80–95% FS; optional model.me_noise_alpha / me_noise_beta). Pass infrared=True with mode="color" for a dust/IR plane on the same ScanImage. Inspect short/long via scanner.last_me_debug after the scan.

Audit a saved bracket (and optional SilverFast ME TIFF)::

PYTHONPATH=src python -m tools.audit_me_bracket short.tif long.tif --sf sf_merged.tif

Enable debug logging:

from pyopticfilm.logging import enable_debug_logging

enable_debug_logging()

Calibration

Shading runs automatically before scan when a matching cache entry exists. Force a new calibration with scanner.calibrate(force=True) or scanner.scan(..., apply_calib=False) to skip applying cached data.

The cache key includes resolution, crop geometry, and scan method (transparency vs infrared). GL128 colour shading uses ASIC-internal measurements at home; IR uses a white-only path suitable for stationary shading.

Experimental / protocol-validated models

Code for additional OpticFilm variants is included so enumeration, model selection, SANE-derived geometry tables, and hardwareless USB traces can be exercised without hardware. These paths are deliberately locked for motor moves and image acquisition:

• model.scan_ready is False for every model except the 8200i SE
• Scanner._ensure_scan_ready() blocks scan, calibrate, home, and park
• GL128 motor moves stay disabled unless the model is scan-ready
• Protocol-validated (currently OpticFilm 8200i setup traces) is not hardware support

If you have a non-SE OpticFilm and want to help validate scanning, open an issue with your exact USB IDs (bcdDevice matters for some models) and we can work through capture-based bring-up. How traces are recorded and compared is in docs/scanner-validation.md.

Development

uv sync --all-groups
uv run ruff check .
uv run pytest -q

Optional PyQt6 scan lab (git checkout only — not on PyPI). From the repo root, Run against MOCK is on by default; uncheck it to use a plugged-in scanner:

uv sync --group lab
uv run python -m tools.scanlab

Full UI walkthrough: tools/scanlab/README.md.

USBPcap / Wireshark .pcapng recordings used during reverse-engineering (8200i SE sessions, PPI ladder, bit-depth pairs, etc.) are published separately in pyopticfilm_captures. Use Scan Lab Open capture… to decode them offline.

CI runs on Python 3.11–3.13 (lint + tests; no hardware in CI).

Project layout:

• src/pyopticfilm/usb/ — enumeration, claim, Genesys USB protocol, mock/recording transports
• src/pyopticfilm/asic/ — per-ASIC drivers (GL128, GL845, …)
• src/pyopticfilm/device/ — per-model register/geometry tables
• src/pyopticfilm/scan/ — geometry, calibration, scan session pipeline
• tests/scanners/ — golden USB traces, SANE log parser
• tools/scanlab/ — PyQt6 bring-up lab (repo only; not in the PyPI package); see tools/scanlab/README.md

License

GPL-3.0-or-later — see LICENSE.

Acknowledgements

Register and motor tables for GL845-family models are derived from the SANE genesys backend (see NOTICE and docs/sane-opticfilm.md). The 8200i SE (GL128) protocol was reconstructed from USB traffic captures of the Windows driver and SilverFast; it is not present in SANE.