pieusb 0.1.0__py3-none-any.whl

pieusb/__init__.py

@@ -0,0 +1,17 @@
+"""pieusb -- direct-USB acquisition library for USB-connected Reflecta film scanners.
+"""
+
+try:
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("pieusb")
+except Exception:  # pragma: no cover - only when the package isn't installed
+    __version__ = "0.1.0"
+
+from pieusb._device import get_devices
+
+__all__ = [
+    "__version__",
+    # module-level (python-sane-shaped)
+    "get_devices",
+]

pieusb/_device.py

@@ -0,0 +1,37 @@
+from pieusb.usb_utils import find_device
+from pieusb.transport import UASDevice, SCSI_INQUIRY
+from pieusb.scanner import Scanner
+
+from pieusb.inquiry import KNOWN_PIDS, PIE_VENDOR_ID, parse_inquiry
+from pieusb.types import DeviceInfo
+
+def _get_inquiry(dev: UASDevice):# -> InquiryResponse:
+    header = dev.command(SCSI_INQUIRY, in_size=5, cdb_length=5)
+    additional_length = header[4]
+    total_size = additional_length + 4
+    raw = dev.command(SCSI_INQUIRY, in_size=total_size, cdb_length=total_size)
+    return parse_inquiry(raw)
+
+def get_devices() -> list[DeviceInfo]:
+    devices: list[DeviceInfo] = []
+
+    for pid in KNOWN_PIDS:
+        dev = find_device(PIE_VENDOR_ID, pid)
+
+        if dev is not None:
+            with UASDevice(dev) as d:
+                r = _get_inquiry(d)
+                devices.append(DeviceInfo(
+                    dev=dev,
+                    vendor=r.vendor,
+                    model=r.model_str,
+                    inquiry=r
+                ))
+
+    return devices
+
+# Probably unnecessary.
+# The user can just s = Scanner(devices[0]) or with Scanner(devices[0]) as s
+# Device gets "opened" in the Scanner constructor
+def open(dev: DeviceInfo) -> Scanner:
+    return Scanner(dev)

pieusb/exceptions.py

@@ -0,0 +1,91 @@
+'''
+Exception hierarchy for pieusb.
+
+    PieusbError
+    |-- TransportError      USB/SCSI transaction failed below the command layer
+    |-- Timeout             a command or a wait did not complete in time
+    |-- CheckCondition      SCSI CHECK CONDITION, carrying decoded sense data
+    |-- DeviceNotReady      device is reachable but cannot start a scan
+    |   `-- WarmingUp       ... specifically because the lamp is warming up
+    `-- ScanInProgress      host-side: this Scanner already has a scan running
+
+Layering note: `CheckCondition` is what the transport layer raises -- it reports
+what the device said, nothing more. Turning a particular sense triple into
+`WarmingUp` or `DeviceNotReady` is the Scanner's job, because that is an
+interpretation of the sense data rather than a property of the transaction. The
+C backend splits it the same way: `sanei_pieusb_command()` returns a status and
+`sane_start()` decides what it means.
+'''
+
+# SCSI sense keys we distinguish (SPC-3 table 27)
+SENSE_KEY_NOT_READY = 0x02
+SENSE_KEY_UNIT_ATTENTION = 0x06
+
+class PieusbError(Exception):
+    '''Base class for every error raised by this package.'''
+
+class TransportError(PieusbError):
+    '''A USB or SCSI transaction failed below the command layer.'''
+
+class Timeout(PieusbError):
+    '''A command, or a wait for the device, did not complete in time.'''
+
+class ScanInProgress(PieusbError):
+    '''This Scanner already has a scan running.
+
+    Host-side state, not something the device reported -- deliberately not a
+    DeviceNotReady, because "wait and retry" and "you have a bug" want different
+    handling.
+    '''
+
+class DeviceNotReady(PieusbError):
+    '''The device is reachable but cannot start a scan.'''
+
+class WarmingUp(DeviceNotReady):
+    '''The lamp is still warming up. Retryable.
+
+    A subclass of DeviceNotReady because that is what the wire says: both are
+    sense key NOT_READY, and warming up is the single case singled out by
+    code 0x04 / qualifier 0x01 (sanei_pieusb_decode_sense, pieusb_usb.c:387-397).
+    '''
+
+class CheckCondition(PieusbError):
+    '''The device returned CHECK CONDITION; sense data has been read back.'''
+
+    def __init__(self, sense_key: int, sense_code: int, sense_qualifier: int) -> None:
+        self.sense_key = sense_key
+        self.sense_code = sense_code
+        self.sense_qualifier = sense_qualifier
+        super().__init__(
+            f"CHECK CONDITION key=0x{sense_key:02x} code=0x{sense_code:02x} "
+            f"qualifier=0x{sense_qualifier:02x}"
+        )
+
+    @property
+    def not_ready(self) -> bool:
+        '''Sense key NOT READY -- the device cannot act on commands yet.
+
+        Broader than `warming_up`: it also covers the not-ready reasons the C
+        backend lumps into a generic failure (pieusb_usb.c:393-396).
+        '''
+        return self.sense_key == SENSE_KEY_NOT_READY
+
+    @property
+    def warming_up(self) -> bool:
+        return self.not_ready and self.sense_code == 0x04 and self.sense_qualifier == 0x01
+
+    @property
+    def must_calibrate(self) -> bool:
+        # "Calibration disable not granted" -- returned by START SCAN when
+        # skipShadingAnalysis was requested but the scanner insists on
+        # calibrating. In the SANE backend (sanei_pieusb_decode_sense) this maps
+        # to PIEUSB_STATUS_MUST_CALIBRATE, which is NOT an error: it is the
+        # signal to enter the calibration phase and read shading reference data
+        # (pieusb.c:1091-1121). We treat it the same way.
+        return (self.sense_key == SENSE_KEY_UNIT_ATTENTION
+                and self.sense_code == 0x82
+                and self.sense_qualifier == 0x00)
+
+class ParamError(PieusbError):
+    '''Some parameter values are incompatible with each other
+    '''

pieusb/inquiry.py

@@ -0,0 +1,158 @@
+from pieusb.types import (
+    InquiryResponse,
+    Filter,
+    ColorFormat,
+    ColorFormat,
+    ImageFormat,
+    ScanCapabilities,
+    OptionalDevices,
+    DeviceInfo
+)
+
+import struct
+
+PIE_VENDOR_ID = 0x05E3
+KNOWN_PIDS = [0x0142, 0x0144, 0x0145]
+MODEL_NAMES = {
+    0x003a: 'DigitDia 6000 Multiple Slide Scanner',
+    0x0030: 'CrystalScan 7200',
+    0x0036: 'ProScan 7200',
+    0x0047: 'ProScan 10T',
+    0x002e: 'CrystalScan 3600',
+    0x002f: 'DigitDia 4000',
+    0x0048: 'RPS 10M (aka Pacific Image PrimeFilm XAs)',
+}
+
+def parse_filters(byte: int) -> tuple[Filter, ...]:
+    out = []
+
+    if byte & 0x01:
+        out.append(Filter.NEUTRAL)
+    if byte & 0x02:
+        out.append(Filter.RED)
+    if byte & 0x04:
+        out.append(Filter.GREEN)
+    if byte & 0x08:
+        out.append(Filter.BLUE)
+    if byte & 0x10:
+        out.append(Filter.INFRARED)
+
+    return tuple(out)
+
+def parse_color_depths(byte: int) -> tuple[int, ...]:
+    out = []
+
+    if byte & 0x01:
+        out.append(1)
+    if byte & 0x02:
+        out.append(4)
+    if byte & 0x04:
+        out.append(8)
+    if byte & 0x08:
+        out.append(10)
+    if byte & 0x10:
+        out.append(12)
+    if byte & 0x20:
+        out.append(16)
+
+    return tuple(out)
+
+def parse_color_format(byte: int) -> tuple[ColorFormat, ...]:
+    out = []
+
+    if byte & 0x01:
+        out.append(ColorFormat.PIXEL)
+    if byte & 0x02:
+        out.append(ColorFormat.LINE)
+    if byte & 0x04:
+        out.append(ColorFormat.INDEXED)
+
+    return tuple(out)
+
+def parse_image_format(byte: int) -> tuple[ImageFormat, ...]:
+    out = []
+
+    if byte & 0x01:
+        out.append(ImageFormat.INTEL)
+    if byte & 0x02:
+        out.append(ImageFormat.MOTOROLA)
+    if byte & 0x04:
+        out.append(ImageFormat.BLACKONE)
+    if byte & 0x08:
+        out.append(ImageFormat.OKLINE)
+
+    return tuple(out)
+
+def parse_scan_capabilities(byte: int) -> tuple[ScanCapabilities, ...]:
+    out = []
+
+    if byte & 0x80:
+        out.append(ScanCapabilities.PWRSAV)
+    if byte & 0x40:
+        out.append(ScanCapabilities.EXT_CAL)
+    if byte & 0x10:
+        out.append(ScanCapabilities.FAST_PREVIEW)
+    if byte & 0x08:
+        out.append(ScanCapabilities.DISABLE_CAL)
+
+    return tuple(out)
+
+def parse_optional_devices(byte: int) -> tuple[OptionalDevices, ...]:
+    out = []
+
+    if byte & 0x80:
+        out.append(OptionalDevices.DEV_MPCL)
+    if byte & 0x04:
+        out.append(OptionalDevices.DEV_TP1)
+    if byte & 0x02:
+        out.append(OptionalDevices.DEV_TP)
+    if byte & 0x01:
+        out.append(OptionalDevices.DEV_ADF)
+
+    return tuple(out)
+
+def parse_inquiry(raw: bytes) -> InquiryResponse:
+    def txt(b):
+        return b.rstrip(b"\x00").decode("ascii", errors="replace").strip()
+
+    model_nr = struct.unpack_from("<H", raw, 116)[0]
+    if model_nr in MODEL_NAMES:
+        model_str = MODEL_NAMES[model_nr]
+    else:
+        model_str = 'Unknown'
+    return InquiryResponse(
+        vendor=txt(raw[8:16]),
+        product=txt(raw[16:32]),
+        revision=txt(raw[32:36]),
+        max_resolution_x=struct.unpack_from("<H", raw, 36)[0],
+        max_resolution_y=struct.unpack_from("<H", raw, 38)[0],
+        max_scan_w=struct.unpack_from("<H", raw, 40)[0],
+        max_scan_h=struct.unpack_from("<H", raw, 42)[0],
+        filters=parse_filters(raw[44]),
+        color_depths=parse_color_depths(raw[45]),
+        color_formats=parse_color_format(raw[46]),
+        image_formats=parse_image_format(raw[48]),
+        scan_capabilities=parse_scan_capabilities(raw[49]),
+        scan_speeds=raw[49] & 7,
+        optional_devices=parse_optional_devices(raw[50]),
+        enhancements=raw[51],
+        gamma_bits=raw[52],
+        last_filter=raw[53],
+        preview_scan_resolution=struct.unpack_from("<H", raw, 54)[0],
+        halftones=raw[100],
+        minimum_highlight=raw[101],
+        maximum_shadow=raw[102],
+        calibration_equation=raw[103],
+        maximum_exposure=struct.unpack_from("<H", raw, 104)[0],
+        minimum_exposure=struct.unpack_from("<H", raw, 106)[0],
+        x0=struct.unpack_from("<H", raw, 108)[0],
+        x1=struct.unpack_from("<H", raw, 110)[0],
+        y0=struct.unpack_from("<H", raw, 112)[0],
+        y1=struct.unpack_from("<H", raw, 114)[0],
+        model=model_nr,
+        model_str=model_str,
+        production=txt(raw[120:124]),
+        timestamp=txt(raw[124:144]),
+        signature=txt(raw[144:184]),
+        slide_transport=model_nr == 0x3a or model_nr == 0x2f
+    )