leanjpeg 0.1.0__py3-none-any.whl

leanjpeg/__init__.py

@@ -0,0 +1,188 @@
+"""leanjpeg: lean JPEG and JPEG XL encoding/decoding for NumPy.
+
+Two independently installable backends live behind this package:
+
+``leanjpeg.simple``
+    The *fast path*: a fork of simplejpeg (https://github.com/jfolz/simplejpeg,
+    libjpeg-turbo) with free-threaded CPython (3.13t/3.14t) support and pooled
+    codec handles / output buffers so that repeated calls do not allocate.
+    Distribution: ``leanjpeg-simple`` (``pip install "leanjpeg[simple]"``).
+
+``leanjpeg.xl``
+    The *offline path*: a light binding over libjxl (https://github.com/libjxl/libjxl)
+    mirroring the simplejpeg API, with lossy/lossless encoding, decoding and
+    bit-exact lossless JPEG -> JPEG XL recompression.
+    Distribution: ``leanjpeg-xl`` (``pip install "leanjpeg[xl]"``).
+
+This root package only contains pure-Python glue: backend discovery,
+format sniffing and a tiny format-agnostic ``decode``/``encode`` dispatcher.
+"""
+from __future__ import annotations
+
+import importlib
+import importlib.util
+
+__version__ = "0.1.0"
+__all__ = [
+    "__version__",
+    "BackendNotInstalled",
+    "backends",
+    "available_backends",
+    "require_backend",
+    "is_jpeg",
+    "is_jxl",
+    "sniff",
+    "decode",
+    "decode_header",
+    "encode",
+]
+
+#: backend name -> importable distribution module
+_BACKEND_MODULES = {"simple": "leanjpeg_simple", "xl": "leanjpeg_xl"}
+_INSTALL_HINTS = {
+    "simple": 'pip install "leanjpeg[simple]"  (distribution: leanjpeg-simple)',
+    "xl": 'pip install "leanjpeg[xl]"  (distribution: leanjpeg-xl)',
+}
+
+JPEG_SOI = b"\xff\xd8"
+JPEG_EOI = b"\xff\xd9"
+JXL_CODESTREAM_SIGNATURE = b"\xff\x0a"
+JXL_CONTAINER_SIGNATURE = b"\x00\x00\x00\x0cJXL \x0d\x0a\x87\x0a"
+
+
+class BackendNotInstalled(ImportError):
+    """Raised when a leanjpeg backend is used but its distribution is missing."""
+
+    def __init__(self, backend: str, cause: BaseException | None = None):
+        hint = _INSTALL_HINTS.get(backend, f"pip install leanjpeg-{backend}")
+        msg = f"leanjpeg.{backend} is not installed. Install it with: {hint}"
+        if cause is not None:
+            msg += f" (import failed with: {cause!r})"
+        super().__init__(msg)
+        self.backend = backend
+
+
+def backends() -> dict[str, bool]:
+    """Return ``{'simple': bool, 'xl': bool}`` describing installed backends.
+
+    Only checks importability of the distribution modules (cheap, no import).
+    """
+    return {
+        name: importlib.util.find_spec(module) is not None
+        for name, module in _BACKEND_MODULES.items()
+    }
+
+
+def available_backends() -> list[str]:
+    """Names of the installed backends, in preference order (``simple`` first)."""
+    return [name for name, ok in backends().items() if ok]
+
+
+def require_backend(name: str):
+    """Import and return the backend module ``leanjpeg.<name>``.
+
+    Raises :class:`BackendNotInstalled` with an install hint when missing.
+    """
+    if name not in _BACKEND_MODULES:
+        raise ValueError(f"unknown backend {name!r}; expected one of {sorted(_BACKEND_MODULES)}")
+    try:
+        return importlib.import_module(f"leanjpeg.{name}")
+    except ImportError as e:  # pragma: no cover - depends on installation
+        if isinstance(e, BackendNotInstalled):
+            raise
+        raise BackendNotInstalled(name, e) from e
+
+
+def _head_tail(data, n: int = 12) -> tuple[bytes, bytes]:
+    """First ``n`` and last 2 bytes of any bytes-like / buffer-protocol object."""
+    if isinstance(data, (bytes, bytearray)):
+        return bytes(data[:n]), bytes(data[-2:])
+    mv = memoryview(data)
+    if mv.ndim != 1 or mv.itemsize != 1:
+        mv = mv.cast("B")
+    return bytes(mv[:n]), bytes(mv[-2:])
+
+
+def is_jpeg(data) -> bool:
+    """True if ``data`` looks like a complete JPEG (JFIF/Exif) file.
+
+    Mirrors ``simplejpeg.is_jpeg``: checks the SOI marker at the start and
+    the EOI marker at the end, so truncated files return False.
+    """
+    try:
+        head, tail = _head_tail(data)
+    except TypeError:
+        return False
+    return head[:2] == JPEG_SOI and tail == JPEG_EOI
+
+
+def is_jxl(data) -> bool:
+    """True if ``data`` starts with a JPEG XL codestream or container signature."""
+    try:
+        head, _ = _head_tail(data)
+    except TypeError:
+        return False
+    return head.startswith(JXL_CODESTREAM_SIGNATURE) or head.startswith(JXL_CONTAINER_SIGNATURE)
+
+
+def sniff(data) -> str | None:
+    """Return ``'jpeg'``, ``'jxl'`` or ``None`` based on the signature bytes."""
+    try:
+        head, _ = _head_tail(data)
+    except TypeError:
+        return None
+    if head[:2] == JPEG_SOI:
+        return "jpeg"
+    if head.startswith(JXL_CODESTREAM_SIGNATURE) or head.startswith(JXL_CONTAINER_SIGNATURE):
+        return "jxl"
+    return None
+
+
+def decode(data, colorspace: str = "RGB", **kwargs):
+    """Decode JPEG or JPEG XL bytes to a ``(height, width, channels)`` array.
+
+    The format is sniffed from the signature and dispatched to
+    ``leanjpeg.simple.decode_jpeg`` or ``leanjpeg.xl.decode_jxl``.
+    Keyword arguments are passed through to the backend function.
+    """
+    kind = sniff(data)
+    if kind == "jpeg":
+        return require_backend("simple").decode_jpeg(data, colorspace, **kwargs)
+    if kind == "jxl":
+        return require_backend("xl").decode_jxl(data, colorspace, **kwargs)
+    raise ValueError("data is neither JPEG nor JPEG XL (unknown signature)")
+
+
+def decode_header(data, **kwargs):
+    """Header-only decode; returns ``(height, width, colorspace, ...)`` tuples.
+
+    Dispatches to ``decode_jpeg_header`` / ``decode_jxl_header``. The first
+    three tuple elements have the same meaning for both backends.
+    """
+    kind = sniff(data)
+    if kind == "jpeg":
+        return require_backend("simple").decode_jpeg_header(data, **kwargs)
+    if kind == "jxl":
+        return require_backend("xl").decode_jxl_header(data, **kwargs)
+    raise ValueError("data is neither JPEG nor JPEG XL (unknown signature)")
+
+
+def encode(image, format: str = "jpeg", **kwargs) -> bytes:
+    """Encode an array with the backend selected by ``format`` (``'jpeg'``/``'jxl'``)."""
+    fmt = format.lower()
+    if fmt in ("jpeg", "jpg"):
+        return require_backend("simple").encode_jpeg(image, **kwargs)
+    if fmt in ("jxl", "jpegxl", "jpeg-xl", "jpeg xl"):
+        return require_backend("xl").encode_jxl(image, **kwargs)
+    raise ValueError(f"unknown format {format!r}; expected 'jpeg' or 'jxl'")
+
+
+def __getattr__(name: str):
+    # Lazy access: ``import leanjpeg; leanjpeg.simple`` / ``leanjpeg.xl``
+    if name in _BACKEND_MODULES:
+        return require_backend(name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_BACKEND_MODULES))

leanjpeg/__pyinstaller/__init__.py

@@ -0,0 +1,13 @@
+"""PyInstaller hooks shipped with the ``leanjpeg`` distribution.
+
+PyInstaller finds this directory through the ``pyinstaller40`` entry point in
+``pyproject.toml``, so freezing an application that uses leanjpeg needs no
+configuration and no hook from pyinstaller-hooks-contrib.
+
+Nothing here is imported at runtime; it only runs inside PyInstaller.
+"""
+import os.path as pt
+
+
+def get_hook_dirs():
+    return [pt.dirname(__file__)]

leanjpeg/__pyinstaller/hook-leanjpeg.py

@@ -0,0 +1,29 @@
+"""PyInstaller hook for the ``leanjpeg`` root package.
+
+The root package resolves its backends dynamically: ``backends()`` asks
+``importlib.util.find_spec`` and ``require_backend()`` calls
+``importlib.import_module('leanjpeg.<name>')``. Neither spelling is visible to
+a static analysis, so an unhooked build collects neither shim, every backend
+reports as missing, and the first call raises ``BackendNotInstalled`` -- on a
+machine where both backends are installed.
+
+Only installed backends are added. A hidden import for a distribution that is
+not there is a build warning, and a frozen app reporting ``{'xl': False}`` for
+a backend the developer never installed is the right answer rather than a bug.
+To leave an installed backend out of a bundle on purpose, exclude its shim:
+
+    pyinstaller --exclude-module leanjpeg.xl app.py
+
+The backends' own hooks (shipped with ``leanjpeg-simple`` / ``leanjpeg-xl``)
+take it from there.
+"""
+from PyInstaller.utils.hooks import can_import_module
+
+hiddenimports = [
+    shim
+    for shim, distribution in (
+        ('leanjpeg.simple', 'leanjpeg_simple'),
+        ('leanjpeg.xl', 'leanjpeg_xl'),
+    )
+    if can_import_module(distribution)
+]

leanjpeg/simple/__init__.py

@@ -0,0 +1,16 @@
+"""leanjpeg.simple: the fast path (libjpeg-turbo via the simplejpeg fork).
+
+This module re-exports everything from the ``leanjpeg_simple`` distribution.
+Install it with ``pip install "leanjpeg[simple]"``.
+"""
+try:
+    import leanjpeg_simple as _backend
+except ImportError as _e:  # pragma: no cover - depends on installation
+    from leanjpeg import BackendNotInstalled as _BackendNotInstalled
+
+    raise _BackendNotInstalled("simple", _e) from _e
+
+from leanjpeg_simple import *  # noqa: F401,F403
+from leanjpeg_simple import __all__, __version__, __upstream_version__  # noqa: F401
+
+__backend__ = _backend

leanjpeg/xl/__init__.py

@@ -0,0 +1,16 @@
+"""leanjpeg.xl: the offline path (JPEG XL via libjxl).
+
+This module re-exports everything from the ``leanjpeg_xl`` distribution.
+Install it with ``pip install "leanjpeg[xl]"``.
+"""
+try:
+    import leanjpeg_xl as _backend
+except ImportError as _e:  # pragma: no cover - depends on installation
+    from leanjpeg import BackendNotInstalled as _BackendNotInstalled
+
+    raise _BackendNotInstalled("xl", _e) from _e
+
+from leanjpeg_xl import *  # noqa: F401,F403
+from leanjpeg_xl import __all__, __version__, __libjxl_version__  # noqa: F401
+
+__backend__ = _backend

leanjpeg-0.1.0.dist-info/METADATA

@@ -0,0 +1,549 @@
+Metadata-Version: 2.4
+Name: leanjpeg
+Version: 0.1.0
+Summary: Lean, allocation-conscious JPEG and JPEG XL encoding/decoding for NumPy: a simplejpeg fork (fast path) and a libjxl binding (offline path), free-threading ready.
+Author: leanjpeg contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vxlk/leanjpeg
+Project-URL: Source, https://github.com/vxlk/leanjpeg
+Project-URL: Issues, https://github.com/vxlk/leanjpeg/issues
+Project-URL: Changelog, https://github.com/vxlk/leanjpeg/blob/main/CHANGELOG.md
+Keywords: jpeg,jpeg xl,jxl,libjpeg-turbo,libjxl,numpy,free-threading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: simple
+Requires-Dist: leanjpeg-simple==0.1.0; extra == "simple"
+Provides-Extra: xl
+Requires-Dist: leanjpeg-xl==0.1.0; extra == "xl"
+Provides-Extra: all
+Requires-Dist: leanjpeg-simple==0.1.0; extra == "all"
+Requires-Dist: leanjpeg-xl==0.1.0; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: numpy>=2.1; extra == "test"
+Requires-Dist: pillow>=11; extra == "test"
+Provides-Extra: bench
+Requires-Dist: numpy>=2.1; extra == "bench"
+Requires-Dist: pillow>=11; extra == "bench"
+Requires-Dist: matplotlib>=3.9; extra == "bench"
+Provides-Extra: dev
+Requires-Dist: leanjpeg[bench,test]; extra == "dev"
+Requires-Dist: cython>=3.1; extra == "dev"
+Requires-Dist: setuptools>=77; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: cibuildwheel>=3.2; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Requires-Dist: validate-pyproject[all]; extra == "dev"
+Dynamic: license-file
+
+# leanjpeg
+
+JPEG and JPEG XL for NumPy arrays, in two independently installable backends:
+a **fast path** for real-time work and an **offline path** for archival.
+
+| backend | codec | distribution | built for |
+|---|---|---|---|
+| `leanjpeg.simple` | libjpeg-turbo 3.2.0 | `leanjpeg-simple` | decode/encode in the hot loop: video frames, dataloaders, servers |
+| `leanjpeg.xl` | libjxl 0.12.0 | `leanjpeg-xl` | smaller files offline: lossy at higher quality-per-byte, lossless, and **bit-exact JPEG recompression** |
+
+`leanjpeg.simple` is a fork of [simplejpeg](https://github.com/jfolz/simplejpeg)
+with two changes and nothing else: it supports **free-threaded CPython**
+(3.13t / 3.14t), and it **stops allocating** in steady state by pooling codec
+handles and output buffers. `leanjpeg.xl` is a new binding that mirrors the
+same API over libjxl. Both statically link their codec, release the GIL around
+all codec work, and are free-threading safe.
+
+```python
+import leanjpeg
+
+leanjpeg.available_backends()          # ['simple', 'xl']
+img = leanjpeg.decode(data)            # sniffs JPEG vs JPEG XL, dispatches
+```
+
+---
+
+## Install
+
+```bash
+pip install "leanjpeg[simple]"    # fast path only
+pip install "leanjpeg[xl]"        # offline path only
+pip install "leanjpeg[all]"       # both
+```
+
+`leanjpeg` itself is pure Python (backend discovery, format sniffing, a small
+dispatcher); the extras pull in the compiled distributions. Each backend also
+installs on its own as `leanjpeg-simple` / `leanjpeg-xl` and imports as
+`leanjpeg_simple` / `leanjpeg_xl` without the umbrella package.
+
+Wheels are built for **CPython 3.13+**, free-threaded builds included, on
+manylinux and musllinux (x86_64, aarch64), macOS (x86_64, arm64) and Windows
+(AMD64, ARM64) - `cp313`, `cp313t`, `cp314` and `cp314t` for each. Nothing is
+dynamically linked beyond libc, so there is no codec to install alongside.
+Building from source needs CMake >= 3.16, a C/C++17 compiler, and NASM for
+libjpeg-turbo's x86 SIMD kernels; the codecs are git submodules, compiled and
+linked statically. See
+[docs/PACKAGING.md](https://github.com/vxlk/leanjpeg/blob/main/docs/PACKAGING.md)
+for the full matrix and for building or releasing it yourself.
+
+A missing backend fails with an actionable error rather than an ImportError
+traceback:
+
+```python
+>>> leanjpeg.xl.encode_jxl(img)
+leanjpeg.BackendNotInstalled: leanjpeg.xl is not installed.
+Install it with: pip install "leanjpeg[xl]"  (distribution: leanjpeg-xl)
+```
+
+## Quick start
+
+```python
+import numpy as np
+from leanjpeg import simple as sj, xl
+
+img = np.zeros((1080, 1920, 3), np.uint8)
+
+# --- fast path -----------------------------------------------------------
+jpg = sj.encode_jpeg(img, quality=85, colorsubsampling='420')
+out = sj.decode_jpeg(jpg, colorspace='RGB')
+h, w, colorspace, subsampling = sj.decode_jpeg_header(jpg)   # ~3 us
+sj.decode_jpeg(jpg, buffer=out)                              # decode into your array
+
+# --- offline path --------------------------------------------------------
+jxl_lossy = xl.encode_jxl(img, quality=90)          # -> distance 1.0
+jxl_lossy = xl.encode_jxl(img, distance=1.5, effort=7)
+jxl_exact = xl.encode_jxl(img, lossless=True)
+out = xl.decode_jxl(jxl_lossy, colorspace='RGB', num_threads=4)
+hdr = xl.decode_jxl_header(jxl_lossy)               # height, width, colorspace, ...
+
+# --- recompress an existing JPEG, reversibly -----------------------------
+smaller = xl.recompress_jpeg(jpg)                   # ~20-30 % smaller
+assert xl.reconstruct_jpeg(smaller) == jpg          # byte for byte
+```
+
+The format-agnostic helpers on the root package sniff the signature and
+dispatch: `leanjpeg.decode`, `leanjpeg.decode_header`, `leanjpeg.encode(img,
+format='jxl')`, `leanjpeg.is_jpeg`, `leanjpeg.is_jxl`, `leanjpeg.sniff`.
+
+## API
+
+`leanjpeg.simple` is API-identical to simplejpeg 1.9.0 — `decode_jpeg`,
+`decode_jpeg_header`, `encode_jpeg`, `encode_jpeg_yuv_planes`, `is_jpeg`, with
+the same arguments, defaults, return types and error messages — so it is a
+drop-in replacement. The fork adds `handle_pool_stats()`,
+`get_handle_pool_size()`, `set_handle_pool_size(n)`, `clear_handle_pool()` and
+`libjpeg_turbo_version()`, and fixes two upstream error paths (an unnamed
+subsampling and empty input both used to raise the wrong thing — see
+[UPSTREAM.md](https://github.com/vxlk/leanjpeg/blob/main/packages/leanjpeg-simple/UPSTREAM.md)).
+
+`leanjpeg.xl` mirrors that shape:
+
+| `leanjpeg.simple` | `leanjpeg.xl` | differences |
+|---|---|---|
+| `decode_jpeg(data, colorspace, fastdct, fastupsample, min_height, min_width, min_factor, buffer, strict)` | `decode_jxl(data, colorspace, *, dtype, num_threads, buffer, keep_orientation, unpremultiply_alpha, unscaled)` | same colorspace names and `buffer=` semantics; no DCT-scaled decoding (that is a JPEG-only trick) |
+| `decode_jpeg_header(data)` -> `(h, w, colorspace, subsampling)` | `decode_jxl_header(data)` -> `JxlHeader(height, width, colorspace, bit_depth, has_alpha, has_jpeg_reconstruction, has_container, has_animation, orientation)` | first three fields agree |
+| `encode_jpeg(image, quality, colorspace, colorsubsampling, fastdct)` | `encode_jxl(image, quality, *, distance, lossless, effort, colorspace, decoding_speed, num_threads, use_container, modular, premultiplied_alpha, bits_per_sample)` | `quality` is translated to a libjxl distance (90 -> 1.0); `uint8`, `uint16` and `float32` input |
+| `encode_jpeg_yuv_planes(Y, U, V, ...)` | — | libjxl takes interleaved RGB/gray only |
+| `is_jpeg(data)` | `is_jxl(data)` | |
+| — | `recompress_jpeg`, `reconstruct_jpeg`, `jpeg_dimensions` | lossless JPEG transcoding |
+
+Colorspaces on both sides: `RGB`, `BGR`, `RGBX`, `BGRX`, `XBGR`, `XRGB`,
+`RGBA`, `BGRA`, `ABGR`, `ARGB`, `GRAY`, and `GRAYA` on the JPEG XL side.
+
+## JPEG XL feature coverage
+
+The scope right now is encode/decode parity with the fast path, plus lossless
+and JPEG recompression. Everything below the line is a deliberate omission,
+not a limitation of the design — each is a small addition to
+`_jxl_core.cpp` plus arguments on the existing functions.
+
+| feature | status | notes |
+|---|---|---|
+| Lossy encode (`distance` / `quality`, `effort` 1-10) | **yes** | `JxlEncoderDistanceFromQuality`; effort maps to `JXL_ENC_FRAME_SETTING_EFFORT` |
+| Lossless encode | **yes** | `lossless=True`, modular mode |
+| Lossless JPEG recompression + bit-exact reconstruction | **yes** | `recompress_jpeg` / `reconstruct_jpeg`, `jbrd` box |
+| Decode to RGB/BGR/RGBA/.../GRAY | **yes** | in-place swizzle, Rec.601 luma for `GRAY` |
+| `uint8` / `uint16` / `float32` samples | **yes** | `dtype=` on decode, dtype-driven on encode |
+| Custom bit depth (10/12/16-bit) | **yes** | `bits_per_sample=` on encode, `unscaled=` on decode |
+| Alpha, premultiplied alpha | **yes** | `premultiplied_alpha=`, `unpremultiply_alpha=` |
+| Output buffer reuse (`buffer=`) | **yes** | zero-allocation decode into your array |
+| Container vs bare codestream | **yes** | `use_container=`; header reports `has_container` |
+| EXIF orientation | **yes** | applied by default, `keep_orientation=True` to skip |
+| Decoding-speed tier, modular toggle | **yes** | `decoding_speed=0..4`, `modular=` |
+| Explicit thread control | **yes** | see [Threading](#threading) |
+| — | | |
+| Progressive / responsive decoding | *not yet* | `JxlDecoderSetProgressiveDetail` + `JxlDecoderFlushImage`; would add a callback or DC-preview API |
+| Downscaled / DC-only decode | *not yet* | 1:8 preview from the DC groups |
+| Region-of-interest decode | *not yet* | `JxlDecoderSetImageOutBuffer` on a crop |
+| Animation (multi-frame) | *not yet* | header already reports `has_animation`; decoding one frame of an animation is unsupported |
+| Extra channels (depth, spot, thermal) | *not yet* | `JxlEncoderSetExtraChannelInfo` |
+| ICC profiles / colour management | *not yet* | currently sRGB in, sRGB out; `JxlEncoderSetICCProfile` / `JxlDecoderGetColorAsICCProfile` |
+| HDR transfer functions (PQ / HLG), gain maps | *not yet* | needs the colour-encoding plumbing above |
+| EXIF / XMP / JUMBF metadata passthrough | *not yet* | boxes are compiled in (`JPEGXL_ENABLE_BOXES=ON`), just not exposed |
+| Streaming / chunked encode | *not yet* | `JXL_ENC_FRAME_SETTING_BUFFERING`, output-mode knobs |
+| CMYK, >4 channels | *not yet* | |
+
+JPEG (fast path) is feature-complete against simplejpeg; there is no roadmap
+gap there.
+
+## Performance
+
+All numbers below come from `bench/` on **Python 3.14.3t (free-threaded)**,
+Windows 10, a 4-core / 8-thread Intel mobile CPU, frames decoded from the
+video fixtures with ffmpeg (nothing vendored). This is a thermally limited
+laptop: read the *ratios*, not the absolute frame rates, and expect run-to-run
+spread of a few tens of percent on the multi-second measurements. See
+[bench/README.md](https://github.com/vxlk/leanjpeg/blob/main/bench/README.md) to reproduce.
+
+### Fast path vs offline path
+
+![Fast path vs offline path](https://raw.githubusercontent.com/vxlk/leanjpeg/main/docs/charts/fast_vs_offline.png)
+
+The two paths are two orders of magnitude apart in encode throughput, which is
+the whole reason there are two of them. At 1080p the fast path encodes at
+**120 fps** and decodes at **81 fps**; libjxl at its cheapest effort encodes at
+**6.6 fps** and decodes at **20 fps**, and buys 0.74-0.81 bpp against JPEG's
+0.78 bpp at the same nominal quality — i.e. at *equal effort settings* the
+sizes are close, and JPEG XL's real advantage shows up as quality per byte
+(below) rather than as raw compression at a fixed quality number.
+
+| 1080p, single call | encode | decode | header |
+|---|---|---|---|
+| `leanjpeg.simple`, q85 4:2:0 | 120 fps | 81 fps (96 fps into a reused buffer) | 3.4 µs |
+| `leanjpeg.xl`, effort 1 | 6.6 fps | 20.2 fps | — |
+| `leanjpeg.xl`, effort 3 | 8.5 fps | 19.3 fps | — |
+| `leanjpeg.xl`, effort 5 | 2.4 fps | 20.5 fps | — |
+| `leanjpeg.xl`, effort 7 | 1.2 fps | 18.1 fps | — |
+| `leanjpeg.xl`, lossless effort 5 | 1.4 fps | 5.7 fps | — |
+
+![JPEG XL encoder effort](https://raw.githubusercontent.com/vxlk/leanjpeg/main/docs/charts/jxl_effort.png)
+
+Effort 3 is the best default for batch work: 7-9 % smaller than effort 1 for
+about 20 % more encode time. Above that the returns stop: effort 5 is another
+0.2-2 % smaller for three to four times the time, and at a *fixed distance*
+effort 7 produced **larger** files than effort 5 on every image tested here —
++9 to +10 % on the fixtures, +0.4 to +4 % on photographic test images.
+`distance` is a quality target rather than a size target, so this is not
+"effort 7 compresses worse"; a slower encode can spend its bits differently at
+the same nominal quality. It does mean the usual assumption that higher effort
+is strictly smaller does not hold, so measure efforts on your own content
+before paying for them.
+
+### The fork against upstream simplejpeg
+
+Comparing two separate benchmark processes on a laptop is meaningless — the
+run-to-run spread is larger than the effect. `bench/ab_fork_vs_upstream.py`
+therefore loads **both libraries into one process** and interleaves them pass
+by pass, so drift hits both equally:
+
+![JPEG throughput, single thread](https://raw.githubusercontent.com/vxlk/leanjpeg/main/docs/charts/jpeg_single_thread.png)
+
+| single thread | encode | decode |
+|---|---|---|
+| 64×64 | **+30 %** (12063 vs 9276 fps) | **+20 %** (15106 vs 12610 fps) |
+| 256×256 | **+13 %** (1218 vs 1075 fps) | +6 % (1172 vs 1105 fps) |
+| 720p | +9 % (108 vs 99 fps) | −2 % (88 vs 91 fps) |
+| 1080p | +21 % (37 vs 30 fps) | −7 % (25 vs 27 fps) |
+| 2160p | +7 % (12.2 vs 11.4 fps) | +6 % (10.2 vs 9.6 fps) |
+
+That is exactly the shape the change predicts. Upstream creates and destroys a
+TurboJPEG handle on *every* call and lets TurboJPEG allocate and free the
+output buffer on every encode; the fork keeps both in a pool. The saving is a
+fixed per-call cost, so it dominates on small images (+30 % at 64×64, where
+thumbnails, tiles and patch pipelines live) and fades into the pixel work on
+large ones. Decode saves only the handle, so it sits at parity within noise.
+
+Multi-threaded, both scale the same way — the codec releases the GIL either
+way:
+
+![JPEG throughput vs Python threads](https://raw.githubusercontent.com/vxlk/leanjpeg/main/docs/charts/jpeg_threads.png)
+
+The difference on a free-threaded build is not throughput, it is that
+**importing upstream simplejpeg re-enables the GIL for the entire process**:
+
+```
+RuntimeWarning: The global interpreter lock (GIL) has been enabled to load
+module 'simplejpeg._jpeg', which has not declared that it can run safely
+without the GIL.
+```
+
+Your JPEG calls still scale, because they release the GIL. Everything *else*
+in your program stops scaling. leanjpeg's backends declare
+`Py_MOD_GIL_NOT_USED` and leave the GIL disabled.
+
+### Threading
+
+`leanjpeg.simple` has no threading of its own: libjpeg-turbo is single
+threaded per call, and you scale by calling it from several Python threads
+(above) or processes.
+
+`leanjpeg.xl` drives libjxl's `JxlResizableParallelRunner` and exposes one
+argument, `num_threads`, on every call:
+
+| `num_threads` | behaviour |
+|---|---|
+| `None` / `0` (default) | automatic: `min(SuggestThreads(w, h), get_max_threads())`, at least 1. libjxl suggests about one thread per 256×256 group, capped by the hardware concurrency |
+| `1` | no worker threads at all; everything runs on the calling thread |
+| `N` | exactly `N` threads *including* the caller (`N-1` workers) |
+
+![JPEG XL threading](https://raw.githubusercontent.com/vxlk/leanjpeg/main/docs/charts/jxl_threads.png)
+
+Encoding scales well inside one call (0.73 → 2.27 fps from 1 to 8 threads at
+1080p, effort 5). Decoding saturates around 4 threads inside one call
+(6.3 → 17.2 fps), and past that you get more from **Python-level** parallelism:
+8 Python threads each calling with `num_threads=1` reach 27.8 fps aggregate
+versus 18.3 fps for one call with `num_threads=8`. The rule of thumb:
+
+* one image at a time (interactive, a single large file) → leave `num_threads`
+  automatic;
+* many images (a batch, a dataloader, a server) → `num_threads=1` and
+  parallelise in Python, otherwise `N` Python threads × `M` libjxl workers
+  oversubscribes the machine.
+
+`set_max_threads(n)` caps the automatic mode process-wide;
+`suggest_num_threads(h, w)` and `effective_num_threads(h, w, n)` report what
+the decision would be. Encoded bytes never depend on the thread count (there
+is a test for that), so this is purely a performance knob.
+
+Related knobs that interact with threading: `effort` (higher efforts add
+sequential phases and gain less from threads) and `modular` (lossless mode
+parallelises per modular group). Deliberately not exposed yet:
+`MODULAR_GROUP_SIZE`, the buffering/output-mode streaming settings, and
+`JxlThreadParallelRunner` (no advantage over the resizable runner here).
+
+### Reduced allocations
+
+Both backends pool their codec state, so a steady-state call allocates only
+the object it returns. The counters are public — this is from the 1080p
+benchmark run:
+
+```python
+>>> leanjpeg_simple.handle_pool_stats()
+{'acquired': 2904, 'created': 16, 'destroyed': 0, 'scratch_reallocs': 10,
+ 'cached_compress': 8, 'cached_decompress': 8, 'max_cached': 16,
+ 'scratch_bytes': 68767744}
+```
+
+2904 encode/decode calls created **16** TurboJPEG handles (one per concurrent
+caller, then reused) and grew the encoder's output buffer **10** times, after
+which the high-water mark held. `created` and `scratch_reallocs` going flat
+while `acquired` keeps climbing is the property the tests assert.
+`leanjpeg_xl.codec_pool_stats()` reports the same for the JPEG XL codecs
+(encoder + decoder + thread pool + buffers per pooled entry).
+
+Pool sizes are tunable — `set_handle_pool_size(n)` / `set_codec_pool_size(n)`,
+and `clear_handle_pool()` / `clear_codec_pool()` to release everything (for
+example before forking or when a long-lived process goes idle).
+
+## Image quality
+
+Same frame, encoded to the *same file size* by both codecs, so the comparison
+is quality-at-a-budget rather than two different points. libjxl's distance is
+found by bisection until it matches the JPEG's byte count (±2 %); PSNR is on
+RGB, SSIM on luma. Full-resolution originals and the other clips are in
+[`docs/quality/`](https://github.com/vxlk/leanjpeg/tree/main/docs/quality/).
+
+![JPEG vs JPEG XL crops](https://raw.githubusercontent.com/vxlk/leanjpeg/main/docs/quality/broadcast_news_720p_crops.png)
+
+| clip | JPEG quality | JPEG size | JPEG PSNR / SSIM | JPEG XL distance (same size) | JPEG XL PSNR / SSIM |
+|---|---|---|---|---|---|
+| broadcast_news_720p | 50 | 57.8 KiB (0.51 bpp) | 28.5 dB / 0.976 | 3.00 (57.5 KiB) | **30.4 dB / 0.984** |
+| broadcast_news_720p | 75 | 85.1 KiB (0.76 bpp) | 31.1 dB / 0.987 | 1.67 (85.1 KiB) | **32.6 dB / 0.990** |
+| broadcast_news_720p | 90 | 141.8 KiB (1.26 bpp) | 33.0 dB / 0.994 | 0.76 (139.0 KiB) | **36.5 dB / 0.994** |
+| dense_text_1080p | 50 | 136.8 KiB (0.54 bpp) | 28.0 dB / 0.974 | 3.22 (135.2 KiB) | **29.8 dB / 0.982** |
+| dense_text_1080p | 75 | 202.6 KiB (0.80 bpp) | 30.6 dB / 0.986 | 1.75 (204.5 KiB) | **32.3 dB / 0.990** |
+| dense_text_1080p | 90 | 335.9 KiB (1.33 bpp) | 32.6 dB / 0.994 | 0.79 (335.7 KiB) | **36.3 dB / 0.994** |
+| dashcam_720p | 50 | 58.2 KiB (0.52 bpp) | 28.7 dB / 0.975 | 2.93 (58.1 KiB) | **30.3 dB / 0.984** |
+| dashcam_720p | 75 | 85.9 KiB (0.76 bpp) | 31.2 dB / 0.987 | 1.60 (86.6 KiB) | **32.4 dB / 0.990** |
+| dashcam_720p | 90 | 145.4 KiB (1.29 bpp) | 33.3 dB / 0.994 | 0.69 (144.1 KiB) | **36.2 dB / 0.994** |
+
+JPEG XL wins everywhere here, by 1.5-3.5 dB PSNR at the same bytes, with the
+gap widest at high quality. Read that with one caveat: **the fixtures are
+synthetic**. They are OCR test clips — a Mandelbrot render under broadcast,
+dashcam and telemetry text overlays — so they are all hard edges, saturated
+colours and smooth gradients, which is friendly territory for JPEG XL's
+modular tools and hostile to 4:2:0 chroma subsampling. The margin on your
+content will be different.
+
+There is no photographic corpus with true (non-JPEG) originals in this
+repository to quote instead, and re-encoding existing JPEGs is not a valid
+substitute: re-encoding a JPEG with JPEG at a matching quality is close to an
+identity operation — measured that way, JPEG scores 54-72 dB PSNR on several
+of simplejpeg's test photos, for reasons that have nothing to do with codec
+quality. Compare on your own originals:
+
+```bash
+python bench/quality_compare.py --images a.png,b.png --out docs/quality
+```
+
+### Lossless
+
+| clip | frame | PNG (Pillow, optimised) | JPEG XL lossless e7 | JPEG q90 | JPEG q90 → JPEG XL |
+|---|---|---|---|---|---|
+| broadcast_news_720p | 1280×720 | 622.1 KiB | 372.9 KiB (60 % of PNG) | 141.8 KiB | 113.9 KiB (**19.6 % smaller**) |
+| dense_text_1080p | 1920×1080 | 1.40 MiB | 863.2 KiB (60 % of PNG) | 335.9 KiB | 269.9 KiB (**19.6 % smaller**) |
+| dashcam_720p | 1280×720 | 709.0 KiB | 408.7 KiB (58 % of PNG) | 145.4 KiB | 116.8 KiB (**19.7 % smaller**) |
+
+## Lossless JPEG recompression
+
+The last column above is the feature to reach for if you have a JPEG archive.
+`recompress_jpeg` re-entropy-codes the existing DCT coefficients — the image
+is never decoded to pixels and never re-quantised — and stores a `jbrd` box
+with everything needed to rebuild the original container. `reconstruct_jpeg`
+returns the original file, byte for byte.
+
+![JPEG to JPEG XL recompression](https://raw.githubusercontent.com/vxlk/leanjpeg/main/docs/charts/jpeg_recompress.png)
+
+On 720p MJPEG frames (ffmpeg `-q:v 20`): **32.4 % smaller**, 41 fps to
+recompress, 126 fps to reconstruct, and 128 fps to decode straight to pixels
+without materialising the JPEG. Savings depend on how the original was
+encoded — 32 % on those MJPEG frames, ~20 % on Pillow's q90 stills above.
+
+```python
+jxl = xl.recompress_jpeg(jpeg_bytes)
+assert xl.reconstruct_jpeg(jxl) == jpeg_bytes            # bit-exact
+assert xl.decode_jxl_header(jxl).has_jpeg_reconstruction # tells you it is reversible
+pixels = xl.decode_jxl(jxl)                              # or go straight to pixels
+```
+
+Round trips are verified bit-exact in the test suite for progressive,
+optimised, 4:4:4 / 4:2:2 / 4:2:0 and grayscale JPEGs, for ffmpeg's MJPEG
+output, and for the 21 photos in simplejpeg's own test corpus when that
+submodule is checked out.
+
+## Freezing with PyInstaller
+
+All three distributions ship their own PyInstaller hook and advertise it
+through the `pyinstaller40` entry point, so `pyinstaller app.py` just works --
+no `--hidden-import`, no `--collect-all`, nothing from
+pyinstaller-hooks-contrib.
+
+The hooks earn their place. Backends are resolved through `importlib`, which
+static analysis cannot follow, so an unhooked bundle silently reports every
+backend as missing:
+
+```python
+>>> leanjpeg.backends()                  # frozen without the hook
+{'simple': False, 'xl': False}
+```
+
+and the compiled extensions import NumPy from machine code, which PyInstaller
+only notices today because it parses the type stub sitting next to each
+extension. The hooks state both outright.
+
+To leave an installed backend out of a bundle, exclude its shim -- `backends()`
+then honestly reports it as absent and `BackendNotInstalled` names it:
+
+```bash
+pyinstaller --exclude-module leanjpeg.xl app.py
+```
+
+`tests/test_pyinstaller.py` freezes and runs an application for each entry
+point; it is marked `slow` and skips itself when PyInstaller is absent.
+
+## Free-threaded CPython
+
+Both extensions declare `Py_MOD_GIL_NOT_USED` (Cython's
+`freethreading_compatible=True`), hold no unprotected global state — the pools
+are lock-protected free lists — and release the GIL around every codec call.
+Importing them on 3.13t / 3.14t leaves `sys._is_gil_enabled()` `False`.
+
+```python
+import sys, leanjpeg_simple, leanjpeg_xl
+assert not sys._is_gil_enabled()          # on a free-threaded build
+```
+
+The test suite runs on both build kinds; the free-threading-specific tests
+(concurrent encode/decode from many threads, pool behaviour under contention)
+skip themselves on a GIL build.
+
+## Building from source
+
+```bash
+git clone --recurse-submodules https://github.com/vxlk/leanjpeg
+cd leanjpeg
+pip install -e packages/leanjpeg-simple    # needs CMake, a C compiler, NASM
+pip install -e packages/leanjpeg-xl        # needs CMake >= 3.16, C++17
+pip install -e .
+pytest
+```
+
+Each package builds its codec out of tree into
+`packages/<name>/build/<codec>_<os>_<arch>/prefix` and links it statically, so
+a rebuild of the Python extension does not rebuild the codec. Source
+distributions carry the vendored codec sources, so `pip install` from an sdist
+needs no network and no git checkout; if the submodule is missing from a git
+tree, `leanjpeg-simple` falls back to downloading a pinned, checksummed
+libjpeg-turbo tarball. On Windows, build from a short path - past 260
+characters cmake fails to detect the compiler.
+
+`python tools/build_dists.py --all` builds every distribution for the current
+platform; `.github/workflows/wheels.yml` builds all 64 wheels.
+
+## Keeping up with upstream
+
+Both codecs are pinned git submodules, and the simplejpeg fork is kept
+mergeable on purpose. `packages/leanjpeg-simple/UPSTREAM.json` records the
+upstream commit and a file-by-file map; `UPSTREAM.md` lists every intentional
+difference. The helper does the routine work:
+
+```bash
+python tools/upstream_sync.py status     # are we behind upstream?
+python tools/upstream_sync.py diff       # what did we change, per file?
+python tools/upstream_sync.py merge      # 3-way merge upstream changes into the fork
+python tools/upstream_sync.py pin        # record a new upstream commit
+```
+
+Files the fork did not touch (`_color.c`, `_color.h`, the custom build
+backend) are reported as identical, so a sync is only ever about the handful
+of files that carry the two changes. Upgrading libjpeg-turbo or libjxl is a
+submodule bump plus a version constant.
+
+## Tests
+
+```bash
+pytest                       # everything that is installed
+pytest -m "not ffmpeg"       # skip the tests that shell out to ffmpeg
+```
+
+| suite | covers |
+|---|---|
+| `packages/leanjpeg-simple/tests` | simplejpeg's own decode/encode/YUV/util tests, ported unchanged |
+| `packages/leanjpeg-xl/tests` | codec round trips across colorspaces, dtypes, bit depths, alpha; JPEG recompression; threading invariants |
+| `tests/` | backend discovery and error messages, cross-backend parity, threading, ffmpeg-driven workflows, packaging metadata, PyInstaller freezes |
+
+Suites skip themselves when their backend is not installed, so a
+`leanjpeg[simple]`-only install still has a green run. The PyInstaller tests
+build and run real executables, so they are marked `slow` and skip themselves
+where PyInstaller is absent (`pytest -m "not slow"` skips them explicitly). The ffmpeg-marked tests
+locate ffmpeg and the video fixtures via `LEANJPEG_FFMPEG` and
+`LEANJPEG_VIDEOS`, a sibling `video-overlay-ocr` checkout, or `PATH`, and skip
+when none is found.
+
+CI runs that suite on Linux, macOS and Windows for 3.13, 3.13t, 3.14 and 3.14t,
+and the release workflow re-runs each backend's suite against every built wheel
+and against both source distributions unpacked outside the git checkout.
+
+## Licences
+
+leanjpeg is MIT. `leanjpeg-simple` also carries simplejpeg's MIT licence
+(`LICENSE.simplejpeg`) and libjpeg-turbo's two BSD-style licences;
+`leanjpeg-xl` statically links libjxl (BSD-3-Clause) and its dependencies —
+highway (Apache-2.0), brotli (MIT) and skcms (BSD-3-Clause). ffmpeg is **not** vendored — the benchmarks call whatever
+ffmpeg you point them at.

leanjpeg-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+leanjpeg/__init__.py,sha256=Idg4z1n6elmOo_2-dIOLqLk4cV2dnFFgvwdWnNG02UI,6703
+leanjpeg/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+leanjpeg/__pyinstaller/__init__.py,sha256=78ZF3kg7XsNUofdnQfgnIev8MH1GHNm6PZUuJ41lqNk,430
+leanjpeg/__pyinstaller/hook-leanjpeg.py,sha256=z6LfqT2N4STmQqVN98GF3ArpdWv4pW5ARNDTL69a_ow,1183
+leanjpeg/simple/__init__.py,sha256=mbL1QpsinG5yIsKPiH67kurnkNaj8eZci2pzeaBsvJM,607
+leanjpeg/xl/__init__.py,sha256=7cf_2SJdW7-eyTSUdyqOBlurd4csmh5v2wh2UXJYqwM,561
+leanjpeg-0.1.0.dist-info/licenses/LICENSE,sha256=27SbVUnd2DwRPMFi-IBHBIuZ4aqab2kaRdvcEAFr6-I,1703
+leanjpeg-0.1.0.dist-info/METADATA,sha256=z--OLnN1n0rkmeubIQmvWI3ZzFyr3596IF8khLntvqk,28053
+leanjpeg-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+leanjpeg-0.1.0.dist-info/entry_points.txt,sha256=_u6JVer4A5G6NRzmNgMc9nhxmi7NTUf4vYmCa2CTowI,65
+leanjpeg-0.1.0.dist-info/top_level.txt,sha256=WCtsTq_kPcgN_4XciKychpysEE6BCMxNGedJ-J3ok1w,9
+leanjpeg-0.1.0.dist-info/RECORD,,

leanjpeg-0.1.0.dist-info/WHEEL

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

leanjpeg-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pyinstaller40]
+hook-dirs = leanjpeg.__pyinstaller:get_hook_dirs

leanjpeg-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,33 @@
+MIT License
+
+Copyright (c) 2026 leanjpeg contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+Third-party components
+--------------------------------------------------------------------------------
+
+leanjpeg-simple is a fork of simplejpeg (MIT License, Copyright (c) 2019
+Joachim Folz) and statically links libjpeg-turbo (IJG License, Modified BSD
+License, and zlib License). See packages/leanjpeg-simple/LICENSE.
+
+leanjpeg-xl statically links libjxl (BSD 3-Clause License, Copyright (c) the
+JPEG XL Project Authors), highway (Apache License 2.0), brotli (MIT License)
+and skcms (BSD 3-Clause License). See packages/leanjpeg-xl/LICENSE.

leanjpeg-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+leanjpeg