pypixelpack 0.2.0__tar.gz

pypixelpack-0.2.0/.flywheel.yml

@@ -0,0 +1,7 @@
+flywheel:
+  streams:
+    - name: main-line
+      branches:
+        - name: main
+          release: production
+          auto_merge: [fix, chore, docs]

pypixelpack-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  # ruff and pyright are pinned to py312 in pyproject.toml, so one leg
+  # carries the full lint signal; only pytest is version-sensitive.
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: "3.12"
+      - run: uv sync
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run pyright
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run pytest
+
+  # Prove the numpy-only core: install the built wheel into a clean
+  # environment and run the core probe (§spec:package-shape).
+  core-install:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # hatch-vcs derives the version from tag history
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - run: uv run --isolated --no-project --with dist/*.whl python tools/check_core_install.py

pypixelpack-0.2.0/.github/workflows/flywheel-pr.yml

@@ -0,0 +1,26 @@
+name: Flywheel — PR
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, edited]
+concurrency:
+  group: flywheel-pr-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+jobs:
+  conduct:
+    # Skip drafts; ignore `edited` events from bots (only a human editing the
+    # title/body should retrigger the conventional-commit rewrite). Skips
+    # cleanly until the flywheel GitHub App is installed on the org and its
+    # credentials are configured.
+    if: |
+      vars.FLYWHEEL_GH_APP_ID != '' &&
+      github.event.pull_request.draft == false &&
+      (github.event.action != 'edited' || github.event.sender.type == 'User')
+    runs-on: ubuntu-latest
+    steps:
+      # SHA-pinned (no floating tags for third-party actions); the trailing
+      # # vX.Y.Z comment is for human review. Mirrors pydecklink's setup.
+      - uses: point-source/flywheel@59758d1940ebe054ce9fdd4b7a7dc79a0cf235e0 # v2.1.0
+        with:
+          event: pull_request
+          app-id: ${{ vars.FLYWHEEL_GH_APP_ID }}
+          app-private-key: ${{ secrets.FLYWHEEL_GH_APP_PRIVATE_KEY }}

pypixelpack-0.2.0/.github/workflows/flywheel-push.yml

@@ -0,0 +1,22 @@
+name: Flywheel — Push
+on:
+  push:
+    branches: ["**"]
+concurrency:
+  group: flywheel-push-${{ github.ref_name }}
+  cancel-in-progress: false
+jobs:
+  release:
+    # Skips cleanly until the flywheel GitHub App is installed on the org
+    # and its credentials are configured (vars.FLYWHEEL_GH_APP_ID,
+    # secrets.FLYWHEEL_GH_APP_PRIVATE_KEY).
+    if: vars.FLYWHEEL_GH_APP_ID != ''
+    runs-on: ubuntu-latest
+    steps:
+      # SHA-pinned (no floating tags for third-party actions); the trailing
+      # # vX.Y.Z comment is for human review. Mirrors pydecklink's setup.
+      - uses: point-source/flywheel@59758d1940ebe054ce9fdd4b7a7dc79a0cf235e0 # v2.1.0
+        with:
+          event: push
+          app-id: ${{ vars.FLYWHEEL_GH_APP_ID }}
+          app-private-key: ${{ secrets.FLYWHEEL_GH_APP_PRIVATE_KEY }}

pypixelpack-0.2.0/.github/workflows/governance-lint.yml

@@ -0,0 +1,11 @@
+name: Governance Lint
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  governance:
+    uses: repentsinner/symphonize/.github/workflows/governance-lint.yml@notation--v0
+    with:
+      readme-type: "library"

pypixelpack-0.2.0/.github/workflows/quality.yml

@@ -0,0 +1,55 @@
+name: quality
+
+# The two checks the `Flywheel - review` ruleset requires by name —
+# `markdownlint` and `shellcheck` — and which nothing in this repository
+# emitted, so every pull request into the default branch sat at "Expected —
+# Waiting for status to be reported" and could not merge. The job keys below
+# ARE the check names the ruleset matches; renaming one silently re-blocks
+# the branch.
+#
+# Neither ran here under those names: markdownlint only as a step inside the
+# reusable governance-lint workflow, and shellcheck not at all — this
+# repository ships no shell scripts, so that job passes on an empty set and
+# exists to satisfy the context. A step's name is not a check's name, which is
+# why the ruleset never saw them.
+on:
+  pull_request:
+  merge_group:
+
+permissions:
+  contents: read
+
+jobs:
+  # Skip on Flywheel's own release and back-merge commits, which carry
+  # generated content rather than reviewable changes. The guard is per job so
+  # each required check still resolves rather than hanging — a skipped job
+  # satisfies a required context, an absent one does not.
+  markdownlint:
+    if: >-
+      !contains(github.event.pull_request.title || '', ': promote ') &&
+      !startsWith(github.event.merge_group.head_commit.message || '', 'chore(release):') &&
+      !startsWith(github.event.merge_group.head_commit.message || '', 'chore: back-merge')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      # Root governance and landing documents, matching the sibling
+      # repositories. Config is .markdownlint.json plus the ignore list in
+      # .markdownlint-cli2.jsonc.
+      - uses: DavidAnson/markdownlint-cli2-action@21c1be1b93ad9ed58fa840aacc3f279cde2a72ff # v24
+        with:
+          globs: "*.md"
+
+  shellcheck:
+    if: >-
+      !contains(github.event.pull_request.title || '', ': promote ') &&
+      !startsWith(github.event.merge_group.head_commit.message || '', 'chore(release):') &&
+      !startsWith(github.event.merge_group.head_commit.message || '', 'chore: back-merge')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      # `severity: error` is the enforced baseline, as in the sibling
+      # repositories: the floor keeps an info-level finding — SC1091 from a
+      # source this action does not follow, say — out of a required gate.
+      - uses: ludeeus/action-shellcheck@00cae500b08a931fb5698e11e79bfbd38e612a38 # v2.0.0
+        with:
+          severity: error

pypixelpack-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+# Agent worktrees and session state
+.claude/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/

pypixelpack-0.2.0/.markdownlint-cli2.jsonc

@@ -0,0 +1,21 @@
+{
+  // CHANGELOG.md is generated by Flywheel/semantic-release in
+  // conventional-changelog format, which opens each release with an h1 and
+  // then jumps to h3 for the section headings — MD001, and not ours to fix:
+  // the file is rewritten from the commit history on every release, so a
+  // correction would be overwritten by the next one and a release would be
+  // able to fail the branch's own required checks.
+  //
+  // The rest are directories a local `markdownlint-cli2` run would otherwise
+  // walk: .venv/ is the environment uv creates and .claude/ the worktrees this
+  // repository's own workflow makes. CI lints the root *.md alone
+  // (.github/workflows/quality.yml), so these matter only to a developer
+  // running the tool by hand — which is exactly when an ignore list earns its
+  // place.
+  "ignores": [
+    "CHANGELOG.md",
+    "node_modules/**",
+    ".venv/**",
+    ".claude/**"
+  ]
+}

pypixelpack-0.2.0/.markdownlint.json

@@ -0,0 +1 @@
+{"MD013": false, "MD024": false, "MD036": false}

pypixelpack-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

pypixelpack-0.2.0/.vale.ini

@@ -0,0 +1,8 @@
+StylesPath = styles
+MinAlertLevel = warning
+
+[SPEC.md]
+BasedOnStyles = Requirements
+
+[REQUIREMENTS.md]
+BasedOnStyles = Requirements

pypixelpack-0.2.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# [0.2.0](https://github.com/Fuse-Technical-Group/pypixelpack/compare/v0.1.0...v0.2.0) (2026-08-30)
+
+
+### Features
+
+* **encoding:** expose the achromatic chroma code ([b39317c](https://github.com/Fuse-Technical-Group/pypixelpack/commit/b39317cad4034e78ae7bda17905e10ed27f6b15f))

pypixelpack-0.2.0/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.

pypixelpack-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,111 @@
+# 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/REQUIREMENTS.md

@@ -0,0 +1,96 @@
+# Requirements
+
+Problem-space document for pypixelpack: pixel layouts and wire encodings
+as a device-free library. Extracted from
+[pydecklink](https://github.com/Fuse-Technical-Group/pydecklink)
+(`§spec:pixel-packing` there) and a GPU render pipeline that outputs to
+SDI and ST 2110.
+
+## Problem statement §req:problem-statement
+
+Target users are the maintainers of video I/O tools in this organization
+and the display-measurement tools that drive them: a DeckLink binding, a
+GPU render pipeline that outputs to SDI and ST 2110, a signal generator,
+and a measurement session that puts exact code values on a wire.
+
+The same v210 layout exists twice. pydecklink packs it in numpy on the
+host for a DMA buffer; a GPU render pipeline packs it in torch on the
+device and DMAs the result, because a round trip through host memory costs a full
+uncompressed frame across PCIe every frame. Each is correct for its
+caller and neither serves the other, so the next wire format — r210 for
+RGB 4:4:4 over SDI — recurs the same way.
+
+The colour encoding between RGB and those samples lives in one of the two
+and is hard-bound to one matrix. A measurement session on SDI has to
+declare that encoding and cannot implement it without a second copy,
+and a wrong matrix or range offsets every code in a way nothing
+downstream can detect.
+
+## Success criteria §req:success-criteria
+
+- pydecklink consumes this library for its layouts, keeps only the map
+  from its SDK enum to a layout name, and `pack`/`unpack` output is
+  byte-identical before and after.
+- The GPU render pipeline consumes this library on torch, on the
+  device, with no host round trip, and a test proves the compiled path is taken.
+- The same source packs a frame on numpy and on torch to identical
+  bytes.
+- Every layout round-trips: `unpack(pack(x)) == x`.
+- display-measure declares an SDI encoding by name and matrix and never
+  carries a conversion of its own.
+
+## User stories §req:user-stories
+
+- As the pydecklink maintainer, I delete the layout implementations and
+  keep the enum map, so the transport binding holds nothing but the
+  vendor's surface.
+- As a render-pipeline developer, I pack v210 and r210 on the GPU and
+  DMA the bytes, so the frame never crosses the bus uncompressed.
+- As a measurement-session author, I declare "10-bit BT.709 narrow-range
+  4:2:2 in v210" and drive RGB patches through it, so the encoding on
+  the wire is the one the artifact records.
+- As a UHD integrator, I select BT.2020, so the encoding follows the
+  signal rather than a constant.
+
+## Quality attributes §req:quality-attributes
+
+- **Exactness.** Layouts are bit-exact against the format's own
+  reference tables; encodings state their rounding and honor it.
+- **Determinism.** Same inputs, same bytes, on every backend.
+- **Footprint.** numpy is the only dependency; torch is supplied by the
+  caller.
+- **Device residency.** No function forces a transfer to host memory.
+- **Fusion.** The torch path stays traceable by `torch.compile`; a
+  change that silently drops it to eager fails a test.
+
+## Constraints §req:constraints
+
+- Public repository under Fuse-Technical-Group; BSD-3-Clause;
+  published to PyPI as `pypixelpack`.
+- Seeded by extraction: pydecklink's layouts and the GPU pipeline's
+  encoding move verbatim before any reshaping; adoption is behind one
+  release each.
+- No transport and no device: what a byte buffer is *for* — a DeckLink
+  frame, an RTP payload — belongs to the consumer.
+- No resizing, no colour management beyond the stated matrix and range:
+  the library encodes what it is given.
+- Renders into a caller-supplied array namespace on the same contract
+  display-patterns established.
+
+## Priorities §req:priorities
+
+Essential, in adoption order:
+
+1. The eight layouts pydecklink holds, namespace-generic, with
+   reference vectors and numpy/torch byte-identity.
+2. pydecklink adoption; first release.
+3. BT.709 and BT.2020 encoding at narrow and full range, chroma
+   subsampling by pair average.
+4. GPU render pipeline adoption on the device, with fusion asserted.
+
+Nice-to-have, after adoption:
+
+- `2vuy`, which no current implementation packs.
+- Provenance for `r10b`, `r10l`, `r12b`, `r12l` against FFmpeg's
+  format list.
+- The ST 2110-20 pgroup, if a second consumer appears.

pypixelpack-0.2.0/ROADMAP.md

@@ -0,0 +1,7 @@
+# Roadmap
+
+Work remaining to reach [SPEC.md](SPEC.md). Sections in build order;
+completed work leaves from the head. A slug in backticks resolves in the
+named repository.
+
+No work remains; every section here has shipped.