pypixelpack 0.2.0__py3-none-any.whl

pypixelpack/__init__.py

@@ -0,0 +1,29 @@
+"""Pixel layouts and wire encodings, device-free (§spec:problem).
+
+numpy is the reference backend and the only import; any other array
+namespace is the caller's to supply (§spec:package-shape).
+"""
+
+from pypixelpack.encoding import MATRICES, decode, encode, encoding_for, legal_codes
+from pypixelpack.layouts import (
+    ENCODINGS,
+    LAYOUTS,
+    SUBSAMPLED_422,
+    pack,
+    row_bytes,
+    unpack,
+)
+
+__all__ = [
+    "ENCODINGS",
+    "LAYOUTS",
+    "MATRICES",
+    "SUBSAMPLED_422",
+    "decode",
+    "encode",
+    "encoding_for",
+    "legal_codes",
+    "pack",
+    "row_bytes",
+    "unpack",
+]

pypixelpack/_backend.py

@@ -0,0 +1,72 @@
+"""Duck-typed helpers over a caller-supplied array namespace (§spec:backend).
+
+The ``xp`` parameter is the backend mechanism: numpy on CPU hosts, torch
+on GPU hosts. Nothing here imports a backend. Only the spellings that
+differ between the two live here; everything both spell the same is
+called raw in ``layouts`` and ``encoding``.
+
+The contract a namespace has to satisfy — recorded here because it is
+the answer to "would backend X work?":
+
+- ``asarray``, and ``zeros`` accepting ``dtype`` and ``device`` (numpy 2
+  takes ``device="cpu"``, and every array carries ``.device``),
+- ``stack``/``concatenate`` taking ``axis``, ``full_like``, and ``flip``
+  taking the axes positionally (torch spells the keyword ``dims``; the
+  one call site is ``layouts._swap_word_bytes``),
+- ``round`` (half to even) and ``clip`` taking scalar bounds, on float
+  arrays, and ``*``, ``/``, ``+``, ``-`` between a float array and a
+  Python float without widening the array (numpy 2 and torch both keep
+  float32),
+- dtype attributes ``int32``, ``int64``, ``uint8``, ``uint16`` and
+  ``float32``,
+- ``astype`` or ``to`` for dtype conversion, and ``ascontiguousarray``
+  on the namespace or ``contiguous`` on the array,
+- ``view(dtype)`` on the array reinterpreting the last axis,
+- ``&``, ``|``, ``<<``, ``>>`` on integer arrays.
+
+**Why every shifted intermediate is int64.** numpy would take uint32,
+but torch's unsigned support stops at uint8 for most kernels, and a
+signed 32-bit word would sign-extend on ``>>``. int64 holds every 32-bit
+word and every shift this library performs; the 8-bit layouts shift
+nothing and stay uint8 throughout.
+
+**Why serialisation is a dtype view.** A 32-bit word becomes four bytes
+by reinterpreting memory, not by four shift-and-mask passes — that is
+what ``view`` is for, and it is the same call on both backends. It
+assumes a little-endian host, which ``layouts`` checks once at import.
+
+**Why the range check is skipped under a compiler.** Comparing a
+reduction against a Python int is control flow on array values, which
+``torch.compile`` cannot trace (§spec:backend fusion). Eager calls keep
+the check; a compiled caller has already accepted the cost of trusting
+its own inputs.
+"""
+
+from typing import Any
+
+
+def astype(array: Any, dtype: Any) -> Any:
+    """``array`` as ``dtype`` — numpy's ``astype`` or torch's ``to``.
+
+    Neither copies when the dtype already matches.
+    """
+    if hasattr(array, "astype"):
+        return array.astype(dtype, copy=False)
+    return array.to(dtype)
+
+
+def contiguous(xp: Any, array: Any) -> Any:
+    """``array`` with a contiguous layout, so ``view(dtype)`` is legal.
+
+    A no-op on both backends when the array already is.
+    """
+    if hasattr(array, "contiguous"):
+        return array.contiguous()
+    return xp.ascontiguousarray(array)
+
+
+def is_compiling(xp: Any) -> bool:
+    """Whether ``xp`` is tracing the caller for compilation; false for a
+    namespace with no compiler (numpy)."""
+    compiler = getattr(xp, "compiler", None)
+    return compiler is not None and bool(compiler.is_compiling())

pypixelpack/encoding.py

@@ -0,0 +1,287 @@
+"""RGB to component samples and back (§spec:encoding).
+
+``encode(rgb)`` takes ``(height, width, 3)`` float RGB in [0, 1] and
+returns ``(height, width, 3)`` ``uint16`` ``[Y, Cb, Cr]`` codes;
+``decode(ycbcr)`` returns ``float32`` RGB clamped to [0, 1]. An encoding
+is a colour matrix, a level range (``narrow``, ``full``), a chroma
+subsampling (``444``, or ``422`` by pair average) and a bit depth; a
+layout name selects the depth and subsampling a wire format expects.
+Both directions take the array namespace as ``xp`` (§spec:backend), and
+every array operation is whole-array, so the torch path traces under
+``torch.compile``.
+
+Rounding is half to even and the arithmetic is float32 on both
+backends, so host and device produce the same codes; the operation
+order is the GPU render pipeline's this was seeded from, which a
+byte-identity check pins.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NamedTuple
+
+import numpy as np
+
+from pypixelpack._backend import astype
+from pypixelpack.layouts import ENCODINGS
+
+__all__ = [
+    "MATRICES",
+    "LegalCodes",
+    "decode",
+    "encode",
+    "encoding_for",
+    "legal_codes",
+]
+
+# Luma coefficients (KR, KB) per matrix; KG is what remains.
+MATRICES: dict[str, tuple[float, float]] = {
+    "bt709": (0.2126, 0.0722),  # ITU-R BT.709-6 Table 3
+    "bt2020": (0.2627, 0.0593),  # ITU-R BT.2020-2 Table 4
+}
+
+# Narrow range is defined from 8 bits up (BT.709-6 section 4.4: luma 16
+# to 235, chroma 16 to 240 about 128), shifted up by ``bits - 8``. Full
+# range is every code, chroma about ``2^(bits-1)`` (H.273 with
+# VideoFullRangeFlag set). Codes are carried as uint16.
+_MIN_BITS, _MAX_BITS = 8, 16
+_NARROW_8BIT = {"luma": (16, 235), "chroma": (16, 240), "chroma_mid": 128}
+_LEVELS = ("narrow", "full")
+_DEFAULT_BITS, _DEFAULT_SUBSAMPLING = 10, "444"
+
+
+class LegalCodes(NamedTuple):
+    """The integer codes a level range can represent at a depth."""
+
+    luma: range
+    chroma: range
+    chroma_mid: int
+    """The code carrying no colour difference — a neutral patch's Cb and Cr.
+
+    Exposed because it cannot be derived from `chroma` alone: narrow
+    10-bit chroma runs 64..960, whose midpoint is 512 rather than the 512
+    a caller would get from the range's own bounds. A consumer driving
+    neutral codes onto the wire needs it, and re-deriving `1 << (bits - 1)`
+    outside this library puts the wire's arithmetic somewhere that does
+    not own it.
+    """
+
+
+class _Span(NamedTuple):
+    """Legal luma and chroma codes, and the achromatic chroma code."""
+
+    luma: range
+    chroma: range
+    chroma_mid: int
+
+
+def _matrix(name: str) -> tuple[float, float, float]:
+    coefficients = MATRICES.get(name)
+    if coefficients is None:
+        raise ValueError(f"unknown matrix: {name!r}")
+    kr, kb = coefficients
+    return kr, 1.0 - kr - kb, kb
+
+
+def _span(levels: str, bits: int) -> _Span:
+    if levels not in _LEVELS:
+        raise ValueError(f"unknown levels: {levels!r}")
+    if not _MIN_BITS <= bits <= _MAX_BITS:
+        raise ValueError(f"bits must be within {_MIN_BITS}..{_MAX_BITS}, got {bits}")
+    if levels == "narrow":
+        shift = bits - _MIN_BITS
+        (y_lo, y_hi), (c_lo, c_hi) = _NARROW_8BIT["luma"], _NARROW_8BIT["chroma"]
+        return _Span(
+            range(y_lo << shift, (y_hi << shift) + 1),
+            range(c_lo << shift, (c_hi << shift) + 1),
+            _NARROW_8BIT["chroma_mid"] << shift,
+        )
+    every = range(1 << bits)
+    return _Span(every, every, 1 << (bits - 1))
+
+
+def legal_codes(*, levels: str = "narrow", bits: int = _DEFAULT_BITS) -> LegalCodes:
+    """The luma and chroma codes ``levels`` represents at ``bits``.
+
+    ``len(legal_codes().luma)`` is 877: narrow range cannot represent
+    every 10-bit code, and a caller driving exact values needs to know
+    which ones survive.
+    """
+    span = _span(levels, bits)
+    return LegalCodes(span.luma, span.chroma, span.chroma_mid)
+
+
+def encoding_for(layout: str) -> tuple[int, str]:
+    """The ``(bits, subsampling)`` a component layout carries."""
+    encoding = ENCODINGS.get(layout)
+    if encoding is None:
+        raise ValueError(f"{layout!r} carries no component encoding")
+    return encoding
+
+
+def _resolve(
+    layout: str | None, bits: int | None, subsampling: str | None
+) -> tuple[int, str]:
+    """Depth and subsampling from a layout, explicit keywords, or defaults.
+
+    A layout names what the wire expects; a keyword that contradicts it
+    is refused rather than silently overridden.
+    """
+    if layout is not None:
+        l_bits, l_sub = encoding_for(layout)
+        if bits not in (None, l_bits) or subsampling not in (None, l_sub):
+            raise ValueError(
+                f"{layout!r} carries {l_bits}-bit {l_sub}; "
+                f"bits={bits!r}, subsampling={subsampling!r} contradict it"
+            )
+        return l_bits, l_sub
+    return (
+        _DEFAULT_BITS if bits is None else bits,
+        _DEFAULT_SUBSAMPLING if subsampling is None else subsampling,
+    )
+
+
+def _channels(xp: Any, pixels: Any) -> tuple[Any, Any, Any]:
+    arr = xp.asarray(pixels)
+    if arr.ndim != 3 or arr.shape[2] != 3:
+        raise ValueError(
+            f"pixels must have shape (height, width, 3), got {tuple(arr.shape)}"
+        )
+    arr = astype(arr, xp.float32)
+    return arr[..., 0], arr[..., 1], arr[..., 2]
+
+
+def _quantise(xp: Any, normalised: Any, span: range, offset: int) -> Any:
+    """A normalised component to its code: scale, offset, round, clamp.
+
+    In place after the first product — four full-frame temporaries
+    become one, and the operation order is unchanged.
+    """
+    t = normalised * (len(span) - 1)
+    t += offset
+    xp.round(t, out=t)
+    xp.clip(t, span.start, span[-1], out=t)
+    return t
+
+
+def _chroma(component: Any, y_n: Any, k: float) -> Any:
+    """``0.5 * (component - y) / (1 - k)`` in bm's operation order, in place."""
+    t = component - y_n
+    t *= 0.5
+    t /= 1.0 - k
+    return t
+
+
+def _codes_444(xp: Any, y: Any, cb: Any, cr: Any, span: _Span) -> Any:
+    return xp.stack(
+        (
+            _quantise(xp, y, span.luma, span.luma.start),
+            _quantise(xp, cb, span.chroma, span.chroma_mid),
+            _quantise(xp, cr, span.chroma, span.chroma_mid),
+        ),
+        axis=-1,
+    )
+
+
+def _codes_422(xp: Any, y: Any, cb: Any, cr: Any, span: _Span) -> Any:
+    """Chroma averaged over each horizontal pair and written to both pixels.
+
+    Averaged on the normalised value, quantised at half width, then
+    broadcast into pair space beside per-pixel luma, so the chroma
+    arithmetic runs once per pair rather than once per pixel. An odd
+    trailing column is its own pair.
+    """
+    height, width = y.shape
+    if width % 2:
+        y, cb, cr = (xp.concatenate((p, p[:, -1:]), axis=1) for p in (y, cb, cr))
+    pairs = y.shape[1] // 2
+
+    def halve(plane: Any) -> Any:
+        p = plane.reshape(height, pairs, 2)
+        return (p[..., 0] + p[..., 1]) * 0.5
+
+    y_q = _quantise(xp, y, span.luma, span.luma.start).reshape(height, pairs, 2)
+    cb_q = _quantise(xp, halve(cb), span.chroma, span.chroma_mid)
+    cr_q = _quantise(xp, halve(cr), span.chroma, span.chroma_mid)
+    shape = (height, pairs, 2)
+    codes = xp.stack(
+        (
+            y_q,
+            xp.broadcast_to(cb_q[..., None], shape),
+            xp.broadcast_to(cr_q[..., None], shape),
+        ),
+        axis=-1,
+    )
+    return codes.reshape(height, pairs * 2, 3)[:, :width]
+
+
+_ASSEMBLE = {"444": _codes_444, "422": _codes_422}
+
+
+def encode(
+    rgb: Any,
+    *,
+    matrix: str = "bt709",
+    levels: str = "narrow",
+    layout: str | None = None,
+    bits: int | None = None,
+    subsampling: str | None = None,
+    xp: Any = np,
+) -> Any:
+    """``(height, width, 3)`` float RGB in [0, 1] to ``uint16`` ``[Y, Cb, Cr]``.
+
+    ``layout`` selects the depth and subsampling a wire format expects
+    (``"v210"`` is 10-bit 4:2:2, ``"2vuy"`` 8-bit 4:2:2); otherwise
+    ``bits`` and ``subsampling`` default to 10 and ``"444"``. Codes clamp to the level range's span.
+    On ``xp``, on the input's device.
+    """
+    kr, kg, kb = _matrix(matrix)
+    bits, subsampling = _resolve(layout, bits, subsampling)
+    span = _span(levels, bits)
+    assemble = _ASSEMBLE.get(subsampling)
+    if assemble is None:
+        raise ValueError(f"unknown subsampling: {subsampling!r}")
+    r, g, b = _channels(xp, rgb)
+
+    y_n = kr * r + kg * g + kb * b
+    codes = assemble(xp, y_n, _chroma(b, y_n, kb), _chroma(r, y_n, kr), span)
+    return astype(codes, xp.uint16)
+
+
+def decode(
+    ycbcr: Any,
+    *,
+    matrix: str = "bt709",
+    levels: str = "narrow",
+    layout: str | None = None,
+    bits: int | None = None,
+    xp: Any = np,
+) -> Any:
+    """``(height, width, 3)`` integer ``[Y, Cb, Cr]`` to ``float32`` RGB in [0, 1].
+
+    Inverse of :func:`encode` to within half a code per component. Per
+    pixel: a 4:2:2 array as ``unpack`` or ``encode`` produce already has
+    its chroma in both pixels of each pair. Any integer dtype is accepted.
+    """
+    kr, kg, kb = _matrix(matrix)
+    bits, _ = _resolve(layout, bits, None)
+    span = _span(levels, bits)
+    y, cb, cr = _channels(xp, ycbcr)
+
+    y_n = (y - span.luma.start) / (len(span.luma) - 1)
+    cb_n = (cb - span.chroma_mid) / (len(span.chroma) - 1)
+    cr_n = (cr - span.chroma_mid) / (len(span.chroma) - 1)
+
+    # Inverse matrix coefficients, YCbCr -> RGB; accumulated in place
+    # with the addition order kept.
+    red = (2.0 * (1.0 - kr)) * cr_n
+    red += y_n
+    green = (-2.0 * kb * (1.0 - kb) / kg) * cb_n
+    green += y_n
+    green += (-2.0 * kr * (1.0 - kr) / kg) * cr_n
+    blue = (2.0 * (1.0 - kb)) * cb_n
+    blue += y_n
+
+    rgb = xp.stack((red, green, blue), axis=-1)
+    xp.clip(rgb, 0.0, 1.0, out=rgb)
+    return rgb

pypixelpack/layouts.py

@@ -0,0 +1,333 @@
+"""Pack integer RGB/YUV pixel values into wire layouts (§spec:layouts).
+
+``pack(pixels, layout, row_bytes)`` returns a 1-D ``uint8`` buffer of
+``height * row_bytes``. ``unpack(data, layout, width, height, row_bytes)``
+recovers pixel values from such a buffer. ``unpack(pack(x)) == x`` for
+every layout.
+
+Pixel arrays are ``(height, width, 3)`` integer arrays. For RGB layouts
+the channels are ``[R, G, B]``; the alpha channel of ARGB/BGRA is written
+at peak on pack and dropped on unpack. For the 4:2:2 YUV layouts v210
+and 2vuy the channels are ``[Y, Cb, Cr]``; chroma is sampled from even
+columns on pack and replicated across each pair on unpack, so round-trip
+identity holds when chroma is equal within each horizontal pair.
+
+Both functions take the array namespace as ``xp`` — numpy by default,
+torch for a frame that stays on its device — and every array operation
+is whole-array: no branch reads a pixel, so the torch path traces under
+``torch.compile`` (§spec:backend).
+
+Each layout is data: its geometry in ``LAYOUTS``, and one bit map that
+both ``pack`` and ``unpack`` read, so the two directions cannot disagree.
+Layouts follow the DeckLink SDK 15.3 manual section 3.4.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import numpy as np
+
+from pypixelpack._backend import astype, contiguous, is_compiling
+
+__all__ = ["ENCODINGS", "LAYOUTS", "SUBSAMPLED_422", "pack", "row_bytes", "unpack"]
+
+if sys.byteorder != "little":  # pragma: no cover
+    raise ImportError(
+        "pypixelpack serialises words by memory view on little-endian hosts"
+    )
+
+# Channel indices within a pixel triple.
+_R, _G, _B = 0, 1, 2
+
+# (group_pixels, group_bytes, bit_depth) per layout. bit_depth is not
+# derivable from the group size (argb and r210 share (1, 4) but pack 8 vs
+# 10 bits), so it is carried explicitly.
+LAYOUTS: dict[str, tuple[int, int, int]] = {
+    "argb": (1, 4, 8),
+    "bgra": (1, 4, 8),
+    "r210": (1, 4, 10),
+    "r10b": (1, 4, 10),
+    "r10l": (1, 4, 10),
+    "v210": (6, 16, 10),
+    "2vuy": (2, 4, 8),
+    "r12b": (8, 36, 12),
+    "r12l": (8, 36, 12),
+}
+
+# The component encoding a layout carries — (bits, subsampling) — for the
+# layouts that carry one; RGB layouts take code values as given.
+ENCODINGS: dict[str, tuple[int, str]] = {
+    "v210": (10, "422"),
+    "2vuy": (8, "422"),
+}
+
+# Layouts whose chroma is shared across each horizontal pair.
+SUBSAMPLED_422: frozenset[str] = frozenset(
+    name for name, (_, subsampling) in ENCODINGS.items() if subsampling == "422"
+)
+
+# Memory order of a group's bytes for the 8-bit layouts: (pixel in
+# group, channel), or ``None`` for the alpha byte. On unpack a component
+# with no byte of its own reads pixel 0's, which is the 4:2:2 rule.
+_Y, _CB, _CR = 0, 1, 2
+_BYTE_ORDER: dict[str, tuple[tuple[int, int] | None, ...]] = {
+    "argb": (None, (0, _R), (0, _G), (0, _B)),
+    "bgra": ((0, _B), (0, _G), (0, _R), None),
+    "2vuy": ((0, _CB), (0, _Y), (0, _CR), (1, _Y)),
+}
+
+# Bit offset of R, G, B within the 32-bit word, and whether the word is
+# stored big-endian. r210 packs 2:10:10:10; r10b/r10l pack 10:10:10:2.
+_RGB10: dict[str, tuple[tuple[int, int, int], bool]] = {
+    "r210": ((20, 10, 0), True),
+    "r10b": ((22, 12, 2), True),
+    "r10l": ((22, 12, 2), False),
+}
+
+# 12-bit RGB is a plain 12-bit little-endian bitstream of R0 G0 B0 R1 …,
+# three bytes per pair of components; r12b stores each 32-bit word
+# byte-swapped. Component pairs per 8-pixel group.
+_R12_PAIRS = 12
+
+
+def _layout(layout: str) -> tuple[int, int, int]:
+    spec = LAYOUTS.get(layout)
+    if spec is None:
+        raise ValueError(f"unknown layout: {layout!r}")
+    return spec
+
+
+def row_bytes(layout: str, width: int) -> int:
+    """The smallest ``row_bytes`` that holds ``width`` pixels of ``layout``."""
+    group_px, group_bytes, _ = _layout(layout)
+    return ((width + group_px - 1) // group_px) * group_bytes
+
+
+_min_row_bytes = row_bytes  # `row_bytes` is also a parameter name below
+
+
+def pack(pixels: Any, layout: str, row_bytes: int, *, xp: Any = np) -> Any:
+    """Pack ``(height, width, 3)`` integer pixel values into ``layout``.
+
+    Returns a 1-D ``uint8`` array of length ``height * row_bytes`` on
+    ``xp``, on the input's device. ``row_bytes`` must be at least the
+    packed active-line size; extra bytes are zero padding.
+    """
+    group_px, _, bits = _layout(layout)
+    arr = xp.asarray(pixels)
+    if arr.ndim != 3 or arr.shape[2] != 3:
+        raise ValueError(
+            f"pixels must have shape (height, width, 3), got {tuple(arr.shape)}"
+        )
+    height, width, _ = arr.shape
+
+    min_row = _min_row_bytes(layout, width)
+    if row_bytes < min_row:
+        raise ValueError(
+            f"row_bytes={row_bytes} too small for width={width} "
+            f"({layout!r} needs at least {min_row})"
+        )
+
+    # A host-side assertion on the unwidened input: a compiler cannot
+    # trace it (see _backend). torch has no uint16 reduction, so that
+    # one dtype widens to int32 for the read.
+    if not is_compiling(xp) and height and width:
+        probe = astype(arr, xp.int32) if arr.dtype == xp.uint16 else arr
+        if int(probe.max()) > (1 << bits) - 1:
+            raise ValueError(f"pixel value exceeds {bits}-bit range for {layout!r}")
+
+    # 8-bit layouts shuffle bytes and never shift; the rest work in int64.
+    src = astype(arr, xp.uint8 if bits == 8 else xp.int64)
+
+    padded_w = -(-width // group_px) * group_px
+    if padded_w != width:
+        pad = xp.zeros(
+            (height, padded_w - width, 3), dtype=src.dtype, device=src.device
+        )
+        src = xp.concatenate([src, pad], axis=1)
+
+    packer, _ = _CODECS[layout]
+    group_data = packer(xp, layout, src)  # (height, min_row)
+
+    if row_bytes != min_row:
+        pad = xp.zeros((height, row_bytes - min_row), dtype=xp.uint8, device=src.device)
+        group_data = xp.concatenate([group_data, pad], axis=1)
+    # A DMA consumer reads from the raw pointer, so the buffer is
+    # contiguous by contract, not by the luck of a copy having happened
+    # upstream: a one-word big-endian frame reaches here as a flipped view.
+    return contiguous(xp, group_data.reshape(-1))
+
+
+def unpack(
+    data: Any,
+    layout: str,
+    width: int,
+    height: int,
+    row_bytes: int,
+    *,
+    xp: Any = np,
+) -> Any:
+    """Recover ``(height, width, 3)`` pixel values from a ``layout`` buffer.
+
+    Inverse of :func:`pack`. Returns ``uint8`` values for 8-bit layouts and
+    ``uint16`` for 10/12-bit layouts, on ``xp``, on the input's device.
+    """
+    buf = astype(xp.asarray(data), xp.uint8).reshape(-1)
+    if buf.shape[0] < height * row_bytes:
+        raise ValueError(
+            f"data too small: got {buf.shape[0]} bytes, need {height * row_bytes}"
+        )
+    rows = buf[: height * row_bytes].reshape(height, row_bytes)
+    group_data = rows[:, : _min_row_bytes(layout, width)]
+
+    _, unpacker = _CODECS[layout]
+    return unpacker(xp, layout, group_data)[:, :width, :]
+
+
+# --- word serialisation -----------------------------------------------------
+
+
+def _swap_word_bytes(xp: Any, b: Any) -> Any:
+    """Reverse the four bytes of every 32-bit word in a byte array."""
+    words = b.reshape(*b.shape[:-1], -1, 4)
+    return xp.flip(words, (-1,)).reshape(b.shape)
+
+
+def _words_to_bytes(xp: Any, words: Any, big_endian: bool) -> Any:
+    """(..., N) int64 words -> (..., N*4) uint8, by memory view."""
+    w32 = astype(words, xp.int32)  # wraps bit 31 identically on both backends
+    out = w32.reshape(*w32.shape, 1).view(xp.uint8).reshape(*w32.shape[:-1], -1)
+    return _swap_word_bytes(xp, out) if big_endian else out
+
+
+def _bytes_to_words(xp: Any, data: Any, big_endian: bool) -> Any:
+    """(..., N*4) uint8 -> (..., N) int64 words, by memory view."""
+    b = _swap_word_bytes(xp, data) if big_endian else data
+    quads = contiguous(xp, b.reshape(*b.shape[:-1], -1, 4))
+    w32 = quads.view(xp.int32).reshape(quads.shape[:-1])
+    return astype(w32, xp.int64) & 0xFFFFFFFF  # undo the sign extension
+
+
+# --- per-layout codecs ------------------------------------------------------
+# Every packer takes (xp, layout, src) with src (height, padded_width, 3)
+# and returns (height, min_row) uint8; every unpacker is its inverse on
+# (height, min_row) and returns (height, padded_width, 3).
+
+
+def _pack_bytes(xp: Any, layout: str, src: Any) -> Any:
+    """Every 8-bit layout is a byte shuffle read straight off the order table."""
+    height = src.shape[0]
+    g = src.reshape(height, -1, LAYOUTS[layout][0], 3)
+    alpha = xp.full_like(g[..., 0, 0], 0xFF)
+    planes = [alpha if e is None else g[..., e[0], e[1]] for e in _BYTE_ORDER[layout]]
+    return xp.stack(planes, axis=-1).reshape(height, -1)
+
+
+def _unpack_bytes(xp: Any, layout: str, data: Any) -> Any:
+    height = data.shape[0]
+    group_px, group_bytes, _ = LAYOUTS[layout]
+    order = _BYTE_ORDER[layout]
+    q = data.reshape(height, -1, group_bytes)
+    # One stack of views, (pixel, channel) in raster order, each read from
+    # its own byte or, for shared chroma, from pixel 0's.
+    planes = [
+        q[..., order.index((p, c) if (p, c) in order else (0, c))]
+        for p in range(group_px)
+        for c in (_R, _G, _B)
+    ]
+    return xp.stack(planes, axis=-1).reshape(height, -1, 3)
+
+
+def _pack_10bit_rgb(xp: Any, layout: str, src: Any) -> Any:
+    (r_lo, g_lo, b_lo), big_endian = _RGB10[layout]
+    words = (src[..., _R] << r_lo) | (src[..., _G] << g_lo) | (src[..., _B] << b_lo)
+    return _words_to_bytes(xp, words, big_endian)
+
+
+def _unpack_10bit_rgb(xp: Any, layout: str, data: Any) -> Any:
+    shifts, big_endian = _RGB10[layout]
+    words = _bytes_to_words(xp, data, big_endian)
+    return xp.stack(
+        [astype((words >> lo) & 0x3FF, xp.uint16) for lo in shifts], axis=-1
+    )
+
+
+def _pack_v210(xp: Any, layout: str, src: Any) -> Any:  # noqa: ARG001 — one codec signature
+    height = src.shape[0]
+    g = src.reshape(height, -1, 6, 3)
+    y, cb, cr = g[..., 0], g[..., 1], g[..., 2]  # chroma read at even pixels
+    words = xp.stack(
+        (
+            cb[..., 0] | (y[..., 0] << 10) | (cr[..., 0] << 20),
+            y[..., 1] | (cb[..., 2] << 10) | (y[..., 2] << 20),
+            cr[..., 2] | (y[..., 3] << 10) | (cb[..., 4] << 20),
+            y[..., 4] | (cr[..., 4] << 10) | (y[..., 5] << 20),
+        ),
+        axis=-1,
+    )
+    return _words_to_bytes(xp, words, False).reshape(height, -1)
+
+
+def _unpack_v210(xp: Any, layout: str, data: Any) -> Any:  # noqa: ARG001 — one codec signature
+    height = data.shape[0]
+    words = _bytes_to_words(xp, data.reshape(height, -1, 16), False)
+    w0, w1, w2, w3 = words[..., 0], words[..., 1], words[..., 2], words[..., 3]
+
+    def field(word: Any, lo: int) -> Any:
+        return astype((word >> lo) & 0x3FF, xp.uint16)
+
+    cb0, cb2, cb4 = field(w0, 0), field(w1, 10), field(w2, 20)
+    cr0, cr2, cr4 = field(w0, 20), field(w2, 0), field(w3, 10)
+    # (pixel, channel) in raster order with chroma shared per pair: one
+    # stack of eighteen views rather than a stack of stacks, which copies
+    # every plane twice.
+    out = xp.stack(
+        (
+            field(w0, 10), cb0, cr0, field(w1, 0), cb0, cr0,
+            field(w1, 20), cb2, cr2, field(w2, 10), cb2, cr2,
+            field(w3, 0), cb4, cr4, field(w3, 20), cb4, cr4,
+        ),
+        axis=-1,
+    )  # fmt: skip
+    return out.reshape(height, -1, 3)
+
+
+def _pack_12bit(xp: Any, layout: str, src: Any) -> Any:
+    height = src.shape[0]
+    pairs = src.reshape(height, -1, _R12_PAIRS, 2)
+    c0, c1 = pairs[..., 0], pairs[..., 1]
+    out = xp.stack(
+        (
+            astype(c0 & 0xFF, xp.uint8),
+            astype(((c0 >> 8) & 0xF) | ((c1 & 0xF) << 4), xp.uint8),
+            astype(c1 >> 4, xp.uint8),
+        ),
+        axis=-1,
+    ).reshape(height, -1)
+    return _swap_word_bytes(xp, out) if layout == "r12b" else out
+
+
+def _unpack_12bit(xp: Any, layout: str, data: Any) -> Any:
+    height = data.shape[0]
+    b = _swap_word_bytes(xp, data) if layout == "r12b" else data
+    triples = astype(b.reshape(height, -1, _R12_PAIRS, 3), xp.int64)
+    b0, b1, b2 = triples[..., 0], triples[..., 1], triples[..., 2]
+    c0 = astype(b0 | ((b1 & 0xF) << 8), xp.uint16)
+    c1 = astype((b1 >> 4) | (b2 << 4), xp.uint16)
+    return xp.stack((c0, c1), axis=-1).reshape(height, -1, 3)
+
+
+_CODECS: dict[str, tuple[Any, Any]] = {
+    "argb": (_pack_bytes, _unpack_bytes),
+    "bgra": (_pack_bytes, _unpack_bytes),
+    "r210": (_pack_10bit_rgb, _unpack_10bit_rgb),
+    "r10b": (_pack_10bit_rgb, _unpack_10bit_rgb),
+    "r10l": (_pack_10bit_rgb, _unpack_10bit_rgb),
+    "v210": (_pack_v210, _unpack_v210),
+    "2vuy": (_pack_bytes, _unpack_bytes),
+    "r12b": (_pack_12bit, _unpack_12bit),
+    "r12l": (_pack_12bit, _unpack_12bit),
+}
+assert set(_CODECS) == set(LAYOUTS)

pypixelpack-0.2.0.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.5
+Name: pypixelpack
+Version: 0.2.0
+Summary: Pixel layouts and wire encodings for video I/O, device-free
+Project-URL: Homepage, https://github.com/Fuse-Technical-Group/pypixelpack
+Project-URL: Repository, https://github.com/Fuse-Technical-Group/pypixelpack.git
+Project-URL: Issues, https://github.com/Fuse-Technical-Group/pypixelpack/issues
+Project-URL: Changelog, https://github.com/Fuse-Technical-Group/pypixelpack/blob/main/CHANGELOG.md
+Author-email: Ritchie Argue <4462072+repentsinner@users.noreply.github.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: decklink,pixel-format,r210,sdi,st2110,v210,ycbcr
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: numpy>=2.3.1
+Description-Content-Type: text/markdown
+
+# pypixelpack
+
+**Pixel layouts and wire encodings for video I/O, device-free.**
+
+The bytes a video frame becomes on a wire — v210, r210, the ST 2110-20
+pgroup — and the encoding between a frame's RGB and those bytes: colour
+matrix, range, chroma subsampling. Written once against a caller-supplied
+array namespace, so the same source packs on numpy for a host frame and
+on torch for a frame that never leaves a GPU.
+
+Extracted from [pydecklink](https://github.com/Fuse-Technical-Group/pydecklink)'s
+packing module and a GPU render pipeline's colorspace node, which held
+the same layout twice. This repository's [SPEC.md](SPEC.md) and
+[ROADMAP.md](ROADMAP.md) govern the package.
+
+## Installation
+
+```sh
+uv add pypixelpack
+```
+
+numpy is the only dependency. torch is a namespace the caller supplies,
+never a dependency of this package (`§spec:backend`).
+
+## Usage
+
+```python
+import numpy as np
+from pypixelpack import decode, encode, pack, unpack
+
+rgb = np.zeros((1080, 1920, 3), dtype=np.float32)  # [R, G, B] in [0, 1]
+codes = encode(rgb, subsampling="422")  # (H, W, 3) uint16 [Y, Cb, Cr]
+data = pack(codes, "v210", row_bytes=5120)  # 1-D uint8, DMA-ready
+back = unpack(data, "v210", width=1920, height=1080, row_bytes=5120)
+rgb_again = decode(back, subsampling="422")  # float32 [R, G, B] in [0, 1]
+```
+
+On a GPU host, pass the namespace and the arrays stay resident:
+
+```python
+import torch
+
+codes = encode(rgb_on_cuda, subsampling="422", xp=torch)
+data = pack(codes, "v210", row_bytes=5120, xp=torch)
+```
+
+## API
+
+- `pack(pixels, layout, row_bytes, *, xp=numpy)` — `(H, W, 3)` integer
+  samples to a 1-D `uint8` buffer of `H × row_bytes` in `layout`, on the
+  input's device (`§spec:layouts`). RGB layouts take `[R, G, B]`; `v210`
+  and `2vuy` take `[Y, Cb, Cr]` with chroma read from even columns.
+- `unpack(data, layout, width, height, row_bytes, *, xp=numpy)` — the
+  inverse; `unpack(pack(x)) == x` for every layout. Returns `uint8` for
+  8-bit layouts and `uint16` otherwise.
+- `row_bytes(layout, width)` — the smallest `row_bytes` that holds a line.
+- `LAYOUTS` — the layout table, `name → (pixels per group, bytes per
+  group, bit depth)`: `argb`, `bgra`, `r210`, `r10b`, `r10l`, `v210`,
+  `2vuy`, `r12b`, `r12l`.
+
+`pack` raises `ValueError` for an unknown layout, a `row_bytes` shorter
+than the packed line, or a sample above the layout's bit depth; the
+last check is skipped under `torch.compile`, where a compiled caller
+trusts its own inputs (`§spec:backend`).
+
+### Encoding
+
+- `encode(rgb, *, matrix="bt709", levels="narrow", layout=None,
+  bits=None, subsampling=None, xp=numpy)` — `(H, W, 3)` float RGB in
+  `[0, 1]` to `(H, W, 3)` `uint16` `[Y, Cb, Cr]` (`§spec:encoding`).
+  `matrix` is `bt709` or `bt2020`; `levels` is `narrow` (luma 16–235,
+  chroma 16–240 at 8 bits, shifted up by `bits - 8`) or `full`.
+  `layout="v210"` selects the depth and subsampling that wire format
+  expects — 10-bit 4:2:2; `2vuy` is 8-bit 4:2:2 — and a `bits` or
+  `subsampling` that contradicts it is refused; without a layout they
+  default to 10 and `444`. `422` averages chroma over each horizontal
+  pair and writes it to both pixels, the shape `pack` reads. Rounding is
+  half to even, arithmetic is float32 on every backend, and codes clamp
+  to the level range's span.
+- `decode(ycbcr, *, matrix, levels, layout=None, bits=None, xp=numpy)`
+  — the inverse, per pixel, to within half a code per component;
+  returns `float32` RGB clamped to `[0, 1]`.
+- `encoding_for(layout)` — the `(bits, subsampling)` a layout carries;
+  `ENCODINGS` is the table behind it.
+- `legal_codes(*, levels="narrow", bits=10)` — the `(luma, chroma)` code
+  spans as `range` objects; `len(legal_codes().luma)` is 877, the levels
+  10-bit narrow range can represent.
+- `MATRICES` — `name → (KR, KB)`: `bt709`, `bt2020`.
+
+`encode` and `decode` raise `ValueError` for an unknown matrix, levels or
+subsampling, a `bits` outside 8–16, or a layout with no component
+encoding.
+
+## Development
+
+```sh
+uv sync
+uv run ruff format --check . && uv run ruff check . && uv run pyright && uv run pytest
+```
+
+`uv sync` installs torch (CPU) into the dev group so the parity suite
+runs; without it those tests skip. To prove the wheel on numpy alone:
+
+```sh
+uv build
+uv run --isolated --no-project --with dist/*.whl python tools/check_core_install.py
+```
+
+## License
+
+BSD-3-Clause. See [LICENSE](LICENSE).

pypixelpack-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pypixelpack/__init__.py,sha256=t4y8JU7JAOLVPfffaQcM92AIei27oKSKdtuDYGaw8f8,602
+pypixelpack/_backend.py,sha256=Xi2f6TJtNEX_CKNTUXbKvFCFMborpssKd8sfVoIiV8s,3080
+pypixelpack/encoding.py,sha256=duUfERv4aet7HpwEhMmW7-899cilhl5Hk3UG6IvXpdw,9751
+pypixelpack/layouts.py,sha256=3tDL5jwk67wuwZOcYRhWBQrKyjc2y1B2YMKlK44fFY8,12783
+pypixelpack/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pypixelpack-0.2.0.dist-info/METADATA,sha256=0AwwCHvJcqwKAuLnF9MUZ4ekhtLg3y05n58FJ1g5t0c,5700
+pypixelpack-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pypixelpack-0.2.0.dist-info/licenses/LICENSE,sha256=efHrtfAxjNNuAuqQJA3cQyzVgXu_p5oEzr6jI70XjFU,1506
+pypixelpack-0.2.0.dist-info/RECORD,,

pypixelpack-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pypixelpack-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026 Fuse Technical Group
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.