pith-jpeg 0.1.1__py3-none-win_amd64.whl

pith_jpeg/__init__.py

@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 pith-hash
+"""pith-jpeg SDK: JPEG decoding and kernel replay through ctypes.
+
+Decodes a native JPEG (baseline SOF0/SOF1 and progressive SOF2,
+byte-exact with libjpeg ``-dct int -nosmooth``) through the Rust
+cdylib. The cdylib computes the ``fnv1a64`` digest of the decoded
+sample bytes internally, so this package stays zero-dependency: one
+call per fixture returns the exact digest the ``reference.json``
+``digests`` section pins. The four numeric kernels the ``vectors``
+section pins (de-zigzag, dequantize, the fixed-point islow IDCT and
+the orthonormal ``f64`` oracle) replay through the same boundary over
+little-endian ``f64`` bit-pattern buffers.
+
+The cdylib is located through the suite's discovery chain:
+
+1. ``PITH_CDYLIB`` — an explicit cdylib *file* path;
+2. ``PITH_CDYLIB_DIR`` — a *directory* scanned for the cdylib names
+   (the CD pipeline points this at ``target/release``);
+3. the package directory itself (the built wheel ships the cdylib as
+   package data);
+4. ``<repo root>/target/release`` — the repository working-tree layout,
+   so a source checkout runs against a local cargo build with no
+   configuration.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+from pathlib import Path
+
+__all__ = [
+    "FfiError",
+    "LibraryNotFoundError",
+    "find_cdylib",
+    "decode_digest",
+    "channels",
+    "dequant_zigzag",
+    "dequant",
+    "idct_islow",
+    "idct_oracle",
+    "STATUS_OK",
+    "STATUS_INVALID",
+    "STATUS_REJECTED",
+    "LAYOUT_GRAY8",
+    "LAYOUT_RGB8",
+    "LAYOUT_RGBA8",
+    "BLOCK",
+]
+
+#: Status: success.
+STATUS_OK = 0
+#: Status: a caller argument is invalid — null pointer, unknown layout,
+#: wrong buffer length.
+STATUS_INVALID = -1
+#: Status: the decoder refused the input (malformed JPEG), or the
+#: requested conversion is not offered (RGB→gray).
+STATUS_REJECTED = -2
+
+#: Output layout: 8-bit grayscale (the ``pith-image`` code).
+LAYOUT_GRAY8 = 0
+#: Output layout: 8-bit RGB, channel-interleaved (the ``pith-image``
+#: code).
+LAYOUT_RGB8 = 2
+#: Output layout: 8-bit RGBA, channel-interleaved (the ``pith-image``
+#: code).
+LAYOUT_RGBA8 = 4
+
+#: One 8×8 kernel block: 64 ``f64`` values.
+BLOCK = 64
+
+#: Every cdylib file name cargo may drop into the build directory, per
+#: platform (windows / linux / macOS).
+CDYLIB_NAMES = ("pith_jpeg.dll", "libpith_jpeg.so", "libpith_jpeg.dylib")
+
+
+class LibraryNotFoundError(OSError):
+    """No cdylib was found through the discovery chain."""
+
+
+class FfiError(Exception):
+    """A non-zero status code came back from the cdylib."""
+
+    def __init__(self, op: str, status: int) -> None:
+        detail = {
+            STATUS_INVALID: "invalid argument",
+            STATUS_REJECTED: "input rejected",
+        }.get(status, "unknown failure")
+        super().__init__(f"{op} failed: {detail} (status {status})")
+        #: The raw status code the FFI returned.
+        self.status = status
+
+
+def find_cdylib() -> Path:
+    """Locates the cdylib through the suite's discovery chain."""
+    explicit = os.environ.get("PITH_CDYLIB")
+    if explicit:
+        p = Path(explicit)
+        if p.is_file():
+            return p
+    env_dir = os.environ.get("PITH_CDYLIB_DIR")
+    candidates: list[Path] = []
+    if env_dir:
+        env_dir_path = Path(env_dir)
+        candidates.append(env_dir_path)
+        if not env_dir_path.is_absolute():
+            # CD and local runs invoke tools from the repository root or
+            # from sdk/<lang>; resolve the env value against both.
+            candidates.append(Path.cwd() / env_dir_path)
+            candidates.append(Path(__file__).resolve().parents[3] / env_dir_path)
+    candidates.append(Path(__file__).resolve().parent)  # packaged wheel
+    candidates.append(Path(__file__).resolve().parents[3] / "target" / "release")
+    for directory in candidates:
+        for name in CDYLIB_NAMES:
+            p = directory / name
+            if p.is_file():
+                return p
+    raise LibraryNotFoundError(
+        "no pith-jpeg cdylib found (searched PITH_CDYLIB, PITH_CDYLIB_DIR, "
+        "the package directory and <repo>/target/release); "
+        "run `cargo build --release` first"
+    )
+
+
+_lib: ctypes.CDLL | None = None
+
+
+def _load() -> ctypes.CDLL:
+    global _lib
+    if _lib is None:
+        lib = ctypes.CDLL(str(find_cdylib()))
+        lib.pith_jpeg_decode.argtypes = [
+            ctypes.c_void_p,  # data
+            ctypes.c_size_t,  # len
+            ctypes.c_uint32,  # layout
+            ctypes.POINTER(ctypes.c_uint64),  # out digest
+        ]
+        lib.pith_jpeg_decode.restype = ctypes.c_int32
+        lib.pith_jpeg_channels.argtypes = [
+            ctypes.c_void_p,  # data
+            ctypes.c_size_t,  # len
+            ctypes.POINTER(ctypes.c_uint32),  # out channels
+        ]
+        lib.pith_jpeg_channels.restype = ctypes.c_int32
+        for op in (
+            "pith_jpeg_dequant_zigzag",
+            "pith_jpeg_dequant",
+            "pith_jpeg_idct_islow",
+            "pith_jpeg_idct_oracle",
+        ):
+            fn = getattr(lib, op)
+            fn.argtypes = [
+                ctypes.c_void_p,  # input buffer (LE f64 lanes)
+                ctypes.c_size_t,  # input length in bytes
+                ctypes.c_void_p,  # output buffer (LE f64 lanes)
+                ctypes.c_size_t,  # output length in bytes
+            ]
+            fn.restype = ctypes.c_int32
+        _lib = lib
+    return _lib
+
+
+def decode_digest(data: bytes, layout: int) -> int:
+    """Decodes a JPEG and returns the ``fnv1a64`` digest of the sample
+    bytes in ``layout`` encoding: row-major, channel-interleaved — the
+    exact value ``reference.json`` pins for the native layout.
+
+    Raises :class:`FfiError` with ``status == STATUS_REJECTED`` for
+    malformed input and for the refused RGB→gray conversion, and with
+    ``status == STATUS_INVALID`` for an unknown layout code.
+    """
+    digest = ctypes.c_uint64()
+    status = _load().pith_jpeg_decode(data, len(data), layout, ctypes.byref(digest))
+    if status != STATUS_OK:
+        raise FfiError("pith_jpeg_decode", status)
+    return digest.value
+
+
+def channels(data: bytes) -> int:
+    """Returns the frame's native channel count (1 or 3) — the digest-
+    exact layout is :data:`LAYOUT_GRAY8` for 1 and :data:`LAYOUT_RGB8`
+    for 3."""
+    out = ctypes.c_uint32()
+    status = _load().pith_jpeg_channels(data, len(data), ctypes.byref(out))
+    if status != STATUS_OK:
+        raise FfiError("pith_jpeg_channels", status)
+    return out.value
+
+
+def _replay(op: str, values: list[float], out_lanes: int) -> list[float]:
+    """Feeds ``values`` to one kernel op over little-endian ``f64``
+    bit-pattern buffers and returns the decoded output lanes."""
+    import struct
+
+    packed = b"".join(struct.pack("<d", v) for v in values)
+    out = (ctypes.c_ubyte * (out_lanes * 8))()
+    status = getattr(_load(), op)(
+        packed, len(packed), out, len(out)
+    )
+    if status != STATUS_OK:
+        raise FfiError(op, status)
+    raw = bytes(out)
+    return list(struct.unpack(f"<{out_lanes}d", raw))
+
+
+def dequant_zigzag(payload: list[float]) -> list[float]:
+    """Replays the ``dequant.zigzag.8x8`` kernel: 64 DQT-payload
+    values in scan order in, the same values in natural (row-major)
+    order out (``natural[ZIGZAG[k]] = payload[k]``)."""
+    return _replay("pith_jpeg_dequant_zigzag", payload, BLOCK)
+
+
+def dequant(coefs: list[float], qt: list[float]) -> list[float]:
+    """Replays the ``dequant.8x8`` kernel: 64 natural-order
+    coefficients and 64 quantizer values in, the 64 element-wise
+    products out."""
+    return _replay("pith_jpeg_dequant", coefs + qt, BLOCK)
+
+
+def idct_islow(coefs: list[float], qt: list[float]) -> list[float]:
+    """Replays the ``idct.islow.8x8`` kernel: the same input layout as
+    :func:`dequant`, the 64 ``u8`` samples of the fixed-point islow
+    transcription out as ``f64`` lanes."""
+    return _replay("pith_jpeg_idct_islow", coefs + qt, BLOCK)
+
+
+def idct_oracle(block: list[float]) -> list[float]:
+    """Replays the ``idct.oracle.8x8`` kernel: 64 dequantized
+    coefficients in, the raw orthonormal ``f64`` DCT-III oracle result
+    out. Platform-``libm``-shaped: compare within the recorded
+    tolerance, never bit-for-bit."""
+    return _replay("pith_jpeg_idct_oracle", block, BLOCK)

pith_jpeg-0.1.1.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: pith-jpeg
+Version: 0.1.1
+Summary: pith-jpeg SDK: JPEG decoding and kernel replay through the pith-hash Rust cdylib
+Author: pith-hash
+License-Expression: MIT
+Project-URL: Repository, https://github.com/pith-hash/pith-jpeg
+Keywords: jpeg,phash,perceptual-hash,pith-hash,ffi,ctypes
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://pith-jpeg.n24q02m.com/logo.svg" alt="pith-jpeg" width="120">
+</p>
+
+<h1 align="center">pith-jpeg</h1>
+
+<p align="center">
+  <strong>pith jpeg lane: baseline and progressive JPEG decoding, byte-exact with libjpeg islow (zero-dep Rust)</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/pith-hash/pith-jpeg/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/pith-hash/pith-jpeg/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/pith-hash/pith-jpeg/actions/workflows/cd.yml"><img alt="CD" src="https://github.com/pith-hash/pith-jpeg/actions/workflows/cd.yml/badge.svg"></a>
+  <a href="https://github.com/pith-hash/pith-jpeg/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/pith-hash/pith-jpeg?display_name=tag&sort=semver"></a>
+  <a href="https://github.com/n24q02m/better-semantic-release"><img alt="semantic-release" src="https://img.shields.io/badge/semantic--release-e10079?logo=semantic-release&logoColor=white"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#the-pith-suite-contract">Suite contract</a>
+</p>
+
+<!-- BEGIN: AUTO-GENERATED-CROSS-PROMO -->
+<!-- END: AUTO-GENERATED-CROSS-PROMO -->
+
+## The pith suite contract
+
+pith-jpeg is part of the **pith** suite (pith-hash). Every suite repository
+follows the same rules; CI enforces them mechanically:
+
+- **Naming**: a library is always `pith-<domain>` (`pith-image`, `pith-audio`,
+  `pith-zip`, ...). The curator/repository of repositories is the bare
+  `pith-hash`. Never invent a second naming scheme inside the suite.
+- **Version pinning**: cross-library dependencies pin `~0.1` (e.g.
+  `pith-image = { version = "~0.1", path = "../pith-image" }`). The whole suite
+  moves together inside 0.1.x; breaking changes require a suite-wide version
+  bump, never a silent minor drift.
+- **Zero third-party dependencies**: every crate depends only on other
+  `pith-*` crates plus `std`. `scripts/check-zero-deps.py` (run in CI) fails
+  the build on any other crate, for normal, build and dev dependencies alike.
+- **No unsafe**: every crate root carries `#![forbid(unsafe_code)]`.
+- **Hex-exact vectors**: `reference.json` at the repo root is the
+  cross-language source of truth. The `gen-reference` binary regenerates it;
+  CI verifies the committed copy is current (`gen-reference verify`), and CD
+  ships the regenerated file with every SDK artifact. Python, Node and Go SDKs
+  MUST test against the same bytes.
+
+## Repository layout
+
+```
+crates/            one published crate per suite lib (pith-<domain>)
+tools/gen-reference  the vector generator binary (bin name: gen-reference)
+sdk/python         ctypes wheel; build backend reads PITH_CDYLIB_DIR
+sdk/node           koffi-based package; prebuilds/<os-arch>/ carry the cdylib
+sdk/go             cgo binding; go.mod carries the module's cgo flags
+fuzz/corpus        fuzz inputs, replayed by tests/fuzz_corpus.rs (parser crates)
+reference.json     hex-exact cross-SDK test vectors
+```
+
+## Overview
+
+JPEG decoding per ITU T.81: baseline (SOF0), extended sequential (SOF1)
+and progressive (SOF2) Huffman-coded frames — spectral selection,
+successive approximation and EOBRUN included — with restart markers,
+4:4:4/4:2:2/4:4:0/4:2:0 and other integral sampling factors, and 1- or
+3-component output as `pith_image::raster::Image` (`Gray`/`Rgb`, 8-bit).
+
+The pixel pipeline is a byte-exact transcription of libjpeg-turbo's
+`islow` integer IDCT, `fancy` triangle chroma upsampling and
+fixed-point YCbCr→RGB, validated against Pillow 12.3.0 fixtures byte
+for byte (see `tests/fixtures/PROVENANCE.md`). Arithmetic-coded,
+lossless, differential, hierarchical, 12-bit and CMYK/YCCK streams are
+refused with `Error::Unsupported` naming the coding process.
+
+## Install
+
+Rust (the core library):
+
+```bash
+cargo add pith-jpeg
+```
+
+Python / Node / Go SDKs are published from the same cdylib on every release;
+see the release assets or the package registries for the matching version.
+
+## Quick start
+
+Rust (the core library):
+
+```rust
+let img = pith_jpeg::decode(&bytes)?;
+
+match img {
+    pith_jpeg::Jpeg::Gray(g) => println!("{}x{}", g.width(), g.height()),
+    pith_jpeg::Jpeg::Rgb(rgb) => println!("{}x{}", rgb.width(), rgb.height()),
+}
+```
+
+`decode` never panics on untrusted input: malformed structure surfaces
+as `Error::Truncated` / `Error::BadValue`, refusals as
+`Error::Unsupported`. Hex-exact cross-SDK vectors — decode digests for
+every committed fixture plus the DCT/dequant numerics — live in
+`reference.json` (regenerate with `cargo run --bin gen-reference`,
+verify with `cargo run --bin gen-reference -- verify`).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Security
+
+See [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © pith-hash

pith_jpeg-0.1.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+pith_jpeg/__init__.py,sha256=9x9V6F47bUciIiEaJ1z-R94WnWWaKURb12FPDGha3JY,8337
+pith_jpeg/pith_jpeg.dll,sha256=6yvwQQZOu9j2oI0HrElBem67VfRtwfFdCqmfku6QkPU,184832
+pith_jpeg-0.1.1.dist-info/METADATA,sha256=rBNaKHTpPvoADYK3PSAdWXb9apPdDrbddb1sc3Fe58I,5851
+pith_jpeg-0.1.1.dist-info/WHEEL,sha256=Zx98gwb_dQKckJK3HEOVKnxxD52EfU_PXDG_usMJ2ng,98
+pith_jpeg-0.1.1.dist-info/top_level.txt,sha256=kbWDcEQWIvue9olhdeuUxmjIDsNM4oFqmK4xpcm8gCc,10
+pith_jpeg-0.1.1.dist-info/RECORD,,

pith_jpeg-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64
+

pith_jpeg-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pith_jpeg