picam2hdmi 0.1.0__tar.gz

picam2hdmi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serge Rabyking
+
+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.

picam2hdmi-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: picam2hdmi
+Version: 0.1.0
+Summary: Raspberry Pi camera as a raw-Bayer HDMI source, speaking the bayerlink protocol
+Author: Serge Rabyking
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bayerlink/picam2hdmi
+Project-URL: Source, https://github.com/bayerlink/picam2hdmi
+Project-URL: Issues, https://github.com/bayerlink/picam2hdmi/issues
+Keywords: raspberry-pi,picamera2,bayer,raw,hdmi,fpga,camera,libcamera
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video :: Capture
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: bayerlink>=0.1.0
+Provides-Extra: pi
+Requires-Dist: picamera2; extra == "pi"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# picam2hdmi
+
+**A Raspberry Pi camera as a raw-Bayer HDMI source.**
+
+FPGA boards rarely have a camera connector, but nearly all of them have
+HDMI-in. A Raspberry Pi has the opposite: a first-class camera stack — every
+sensor libcamera supports, drivers, modes, controls — and an HDMI output.
+picam2hdmi turns the Pi into a **sensor module with an HDMI plug**: raw
+12-bit Bayer frames, straight from the sensor's CSI-2 output with the ISP
+bypassed, carried over the display link as bytes and self-described by a
+header line.
+
+```
+sensor ──CSI-2──▶ Pi (libcamera raw, zero-copy) ──HDMI──▶ any receiver with HDMI-in
+```
+
+No transcoding, no compression, no per-sensor code in this tool: the Bayer
+order and bit depth travel in the stream itself, so a receiver built once
+works with every camera the Pi supports.
+
+## The protocol: bayerlink
+
+The wire format is **[bayerlink](https://github.com/bayerlink/bayerlink)** —
+the display's active area as a byte container, one header line making the
+stream self-describing. The spec, the reference codec and the conformance
+vectors live in the protocol's own repository, because this tool is one
+encoder among several and should not own the contract receivers implement.
+
+The codec runs on **both ends**: this tool encodes with it on the Pi, and a
+receiver's host software decodes captured frames with the same package —
+
+```python
+import bayerlink
+
+header, raw = bayerlink.decode_frame(captured)    # (H, W, 3) uint8 in
+print(header.bayer_order, header.width, header.height, header.frame_seq)
+# raw: (lines, samples) uint16, exactly what the sensor produced
+```
+
+## Status
+
+| Piece | State |
+| --- | --- |
+| bayerlink v1 protocol, patterns, vectors | **done** — in [bayerlink](https://github.com/bayerlink/bayerlink) |
+| CLI: pattern → container file | **done** |
+| KMS scanout (double-buffered, full-range RGB forced) | next — design in `output.py` |
+| Picamera2 raw capture (zero-copy dmabuf path) | after scanout — design in `capture.py` |
+
+## Usage today
+
+```bash
+pip install picam2hdmi          # numpy only; add [pi] on the Pi itself
+picam2hdmi pattern --mode counting --width 2028 --height 1078 --out frame.npy
+```
+
+That file is bit-for-bit what the HDMI link will carry — receivers can be
+built and tested against it before any cable exists.
+
+## The one integration rule
+
+The link must deliver bytes unmodified: **full-range RGB, no scaling, no
+overscan, RGB 4:4:4**. The most common failure is a limited-range clamp
+(16–235) quietly destroying sample values; the `checker` and `corners`
+patterns exist to catch exactly that on day one. Details and the receiver
+rate rule are in [PROTOCOL.md](PROTOCOL.md).
+
+## Why this exists
+
+Built as the sensor front-end for FPGA image pipelines — for example, as the
+input to hardware generated with [np2hw](https://github.com/lanserge/np2hw)
+— but useful to anyone who wants real sensor data into a board without
+MIPI hardware, deserialisers, or per-sensor bring-up.
+
+## Licence
+
+MIT.

picam2hdmi-0.1.0/README.md

@@ -0,0 +1,76 @@
+# picam2hdmi
+
+**A Raspberry Pi camera as a raw-Bayer HDMI source.**
+
+FPGA boards rarely have a camera connector, but nearly all of them have
+HDMI-in. A Raspberry Pi has the opposite: a first-class camera stack — every
+sensor libcamera supports, drivers, modes, controls — and an HDMI output.
+picam2hdmi turns the Pi into a **sensor module with an HDMI plug**: raw
+12-bit Bayer frames, straight from the sensor's CSI-2 output with the ISP
+bypassed, carried over the display link as bytes and self-described by a
+header line.
+
+```
+sensor ──CSI-2──▶ Pi (libcamera raw, zero-copy) ──HDMI──▶ any receiver with HDMI-in
+```
+
+No transcoding, no compression, no per-sensor code in this tool: the Bayer
+order and bit depth travel in the stream itself, so a receiver built once
+works with every camera the Pi supports.
+
+## The protocol: bayerlink
+
+The wire format is **[bayerlink](https://github.com/bayerlink/bayerlink)** —
+the display's active area as a byte container, one header line making the
+stream self-describing. The spec, the reference codec and the conformance
+vectors live in the protocol's own repository, because this tool is one
+encoder among several and should not own the contract receivers implement.
+
+The codec runs on **both ends**: this tool encodes with it on the Pi, and a
+receiver's host software decodes captured frames with the same package —
+
+```python
+import bayerlink
+
+header, raw = bayerlink.decode_frame(captured)    # (H, W, 3) uint8 in
+print(header.bayer_order, header.width, header.height, header.frame_seq)
+# raw: (lines, samples) uint16, exactly what the sensor produced
+```
+
+## Status
+
+| Piece | State |
+| --- | --- |
+| bayerlink v1 protocol, patterns, vectors | **done** — in [bayerlink](https://github.com/bayerlink/bayerlink) |
+| CLI: pattern → container file | **done** |
+| KMS scanout (double-buffered, full-range RGB forced) | next — design in `output.py` |
+| Picamera2 raw capture (zero-copy dmabuf path) | after scanout — design in `capture.py` |
+
+## Usage today
+
+```bash
+pip install picam2hdmi          # numpy only; add [pi] on the Pi itself
+picam2hdmi pattern --mode counting --width 2028 --height 1078 --out frame.npy
+```
+
+That file is bit-for-bit what the HDMI link will carry — receivers can be
+built and tested against it before any cable exists.
+
+## The one integration rule
+
+The link must deliver bytes unmodified: **full-range RGB, no scaling, no
+overscan, RGB 4:4:4**. The most common failure is a limited-range clamp
+(16–235) quietly destroying sample values; the `checker` and `corners`
+patterns exist to catch exactly that on day one. Details and the receiver
+rate rule are in [PROTOCOL.md](PROTOCOL.md).
+
+## Why this exists
+
+Built as the sensor front-end for FPGA image pipelines — for example, as the
+input to hardware generated with [np2hw](https://github.com/lanserge/np2hw)
+— but useful to anyone who wants real sensor data into a board without
+MIPI hardware, deserialisers, or per-sensor bring-up.
+
+## Licence
+
+MIT.

picam2hdmi-0.1.0/picam2hdmi/__init__.py

@@ -0,0 +1,17 @@
+"""picam2hdmi -- a Raspberry Pi camera as a bayerlink HDMI source.
+
+The wire format is the bayerlink protocol (github.com/bayerlink/bayerlink);
+this tool is its reference ENCODER for the Pi. The protocol package runs on
+both ends of the link, so the container-building lives there and what lives
+here is only what is the Pi's: capture (Picamera2) and scanout (KMS).
+"""
+from bayerlink import (  # noqa: F401  (re-exported for convenience)
+    Header,
+    decode_frame,
+    encode_frame,
+    pattern,
+)
+
+__version__ = "0.1.0"
+
+__all__ = ["Header", "encode_frame", "decode_frame", "pattern"]

picam2hdmi-0.1.0/picam2hdmi/capture.py

@@ -0,0 +1,39 @@
+"""Capture: raw Bayer frames from the camera, via the Linux camera stack.
+
+NOT IMPLEMENTED YET -- this module states the intended design so the work is
+specified before it is written. It only runs on a Pi with a camera attached.
+
+Intended design
+---------------
+
+Picamera2 (libcamera), raw stream only:
+
+- configure the RAW stream at the chosen sensor mode (for the reference
+  setup: the HQ camera's 2028x1080 12-bit mode -- 2028 obeys the 1080p rate
+  rule in PROTOCOL.md);
+- the ISP is NOT in the loop: the raw stream is the sensor's own packed
+  output, DMA-written by the CSI receiver. The Bayer order and bit depth
+  come from libcamera's reported format and go straight into the bayerlink
+  fourcc -- this tool never holds a sensor register table, which is the
+  point: the kernel drivers that know those tables run in THEIR project,
+  under their licence, and every camera libcamera supports works here
+  without this tool learning anything about it;
+- hand each completed buffer to output.stream(), preferably as a dmabuf so
+  the scanout flips the capture buffer itself (zero copies), otherwise via
+  one packed-line copy into the container;
+- stamp frame_seq once per delivered camera frame, so receivers can
+  deduplicate scanout repeats.
+
+Auto-exposure and auto-white-balance are DISABLED by default: a raw source
+should be deterministic unless the operator asks otherwise. Fixed exposure
+and gain are CLI arguments.
+"""
+from __future__ import annotations
+
+
+def frames(mode=None, exposure_us=None, analogue_gain=None):  # pragma: no cover
+    """Yield (raw_frame, bayer_order, frame_seq) from the camera. Pi-only."""
+    raise NotImplementedError(
+        "Picamera2 capture is the milestone after scanout; the module "
+        "docstring is its design. Until then, pattern.generate() supplies "
+        "frames with the same shape and dtype.")

picam2hdmi-0.1.0/picam2hdmi/cli.py

@@ -0,0 +1,72 @@
+"""Command line: `picam2hdmi pattern` works anywhere; `stream` needs a Pi."""
+from __future__ import annotations
+
+import argparse
+import sys
+
+import numpy as np
+
+from bayerlink import pattern, protocol
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="picam2hdmi",
+        description="Raw Bayer over HDMI, speaking bayerlink v1 "
+                    "(github.com/bayerlink/bayerlink).")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    pat = sub.add_parser(
+        "pattern",
+        help="encode a test pattern into a bayerlink container (runs anywhere)")
+    pat.add_argument("--mode", default="counting",
+                     choices=sorted(pattern.PATTERNS))
+    pat.add_argument("--width", type=int, default=2028,
+                     help="samples per line (default: HQ camera 2028)")
+    pat.add_argument("--height", type=int, default=1078,
+                     help="camera lines; a 1080-line display carries at most "
+                          "1079 (one line is the header), 1078 keeps whole "
+                          "CFA rows")
+    pat.add_argument("--display", default="1920x1080",
+                     help="container geometry, WxH (default 1920x1080)")
+    pat.add_argument("--bayer", default="RGGB",
+                     choices=sorted(protocol.BAYER_PHASE))
+    pat.add_argument("--frame-seq", type=int, default=0)
+    pat.add_argument("--out", required=True,
+                     help=".npy for the (H,W,3) container, .bin for raw bytes")
+
+    stream = sub.add_parser(
+        "stream", help="scan out over HDMI (Raspberry Pi only; next milestone)")
+    stream.add_argument("--source", default="pattern",
+                        choices=["pattern", "camera"])
+
+    args = parser.parse_args(argv)
+
+    if args.command == "pattern":
+        width, _, height = args.display.partition("x")
+        display = (int(width), int(height))
+        raw = pattern.generate(args.mode, args.width, args.height)
+        frame = protocol.encode_frame(
+            raw, args.bayer, frame_seq=args.frame_seq, display=display,
+            flags=protocol.FLAG_TEST_PATTERN)
+        if args.out.endswith(".npy"):
+            np.save(args.out, frame)
+        else:
+            frame.tofile(args.out)
+        # Prove the file by decoding it back before claiming success.
+        header, decoded = protocol.decode_frame(frame)
+        assert np.array_equal(decoded, raw)
+        print(f"wrote {args.out}: {args.mode} {args.width}x{args.height} "
+              f"({header.fourcc}, seq {header.frame_seq}) in "
+              f"{display[0]}x{display[1]}, round-trip verified")
+        return 0
+
+    if args.command == "stream":
+        from . import capture, output  # noqa: F401  (their docstrings are the design)
+        output.stream(frames=None)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

picam2hdmi-0.1.0/picam2hdmi/output.py

@@ -0,0 +1,37 @@
+"""Scanout: putting encoded frames on the HDMI connector.
+
+NOT IMPLEMENTED YET -- this module states the intended design so the work is
+specified before it is written. The protocol and patterns are complete and
+tested; this is the next milestone, and it only runs on a Pi.
+
+Intended design
+---------------
+
+DRM/KMS directly (no X, no Wayland, no desktop):
+
+- open the DRM device, pick the connector's mode (1080p30 for the reference
+  setup -- see PROTOCOL.md's rate rule for why not 720p);
+- create TWO dumb buffers in the container format and page-flip between
+  them on vsync: the classic double buffer. A flip replaces the WHOLE frame
+  atomically, so a receiver never sees half an update -- the same reasoning
+  as shadow registers, applied to pixels;
+- force FULL-RANGE RGB on the connector ("Broadcast RGB" property where the
+  driver exposes it, plus the firmware setting), because a limited-range
+  link clamps exactly the values raw data lives on;
+- with a camera attached, import the capture buffer as a dmabuf and flip it
+  directly where stride and format allow -- zero copies from sensor DMA to
+  scanout. Where strides disagree, fall back to one memcpy per line.
+
+The container format is chosen so the MEMORY byte order matches PROTOCOL.md;
+whether that is DRM_FORMAT_RGB888 or BGR888 on a given platform is resolved
+once, in the phase-0 pattern loopback, and recorded in the board notes.
+"""
+from __future__ import annotations
+
+
+def stream(frames, mode=(1920, 1080, 30)):  # pragma: no cover - hardware only
+    """Scan an iterable of encoded frames out over HDMI. Pi-only; see above."""
+    raise NotImplementedError(
+        "KMS scanout is the next milestone; the module docstring is its "
+        "design. Until then, `picam2hdmi pattern --out frame.npy` produces "
+        "the exact bytes this will display.")

picam2hdmi-0.1.0/picam2hdmi.egg-info/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: picam2hdmi
+Version: 0.1.0
+Summary: Raspberry Pi camera as a raw-Bayer HDMI source, speaking the bayerlink protocol
+Author: Serge Rabyking
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bayerlink/picam2hdmi
+Project-URL: Source, https://github.com/bayerlink/picam2hdmi
+Project-URL: Issues, https://github.com/bayerlink/picam2hdmi/issues
+Keywords: raspberry-pi,picamera2,bayer,raw,hdmi,fpga,camera,libcamera
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video :: Capture
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: bayerlink>=0.1.0
+Provides-Extra: pi
+Requires-Dist: picamera2; extra == "pi"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# picam2hdmi
+
+**A Raspberry Pi camera as a raw-Bayer HDMI source.**
+
+FPGA boards rarely have a camera connector, but nearly all of them have
+HDMI-in. A Raspberry Pi has the opposite: a first-class camera stack — every
+sensor libcamera supports, drivers, modes, controls — and an HDMI output.
+picam2hdmi turns the Pi into a **sensor module with an HDMI plug**: raw
+12-bit Bayer frames, straight from the sensor's CSI-2 output with the ISP
+bypassed, carried over the display link as bytes and self-described by a
+header line.
+
+```
+sensor ──CSI-2──▶ Pi (libcamera raw, zero-copy) ──HDMI──▶ any receiver with HDMI-in
+```
+
+No transcoding, no compression, no per-sensor code in this tool: the Bayer
+order and bit depth travel in the stream itself, so a receiver built once
+works with every camera the Pi supports.
+
+## The protocol: bayerlink
+
+The wire format is **[bayerlink](https://github.com/bayerlink/bayerlink)** —
+the display's active area as a byte container, one header line making the
+stream self-describing. The spec, the reference codec and the conformance
+vectors live in the protocol's own repository, because this tool is one
+encoder among several and should not own the contract receivers implement.
+
+The codec runs on **both ends**: this tool encodes with it on the Pi, and a
+receiver's host software decodes captured frames with the same package —
+
+```python
+import bayerlink
+
+header, raw = bayerlink.decode_frame(captured)    # (H, W, 3) uint8 in
+print(header.bayer_order, header.width, header.height, header.frame_seq)
+# raw: (lines, samples) uint16, exactly what the sensor produced
+```
+
+## Status
+
+| Piece | State |
+| --- | --- |
+| bayerlink v1 protocol, patterns, vectors | **done** — in [bayerlink](https://github.com/bayerlink/bayerlink) |
+| CLI: pattern → container file | **done** |
+| KMS scanout (double-buffered, full-range RGB forced) | next — design in `output.py` |
+| Picamera2 raw capture (zero-copy dmabuf path) | after scanout — design in `capture.py` |
+
+## Usage today
+
+```bash
+pip install picam2hdmi          # numpy only; add [pi] on the Pi itself
+picam2hdmi pattern --mode counting --width 2028 --height 1078 --out frame.npy
+```
+
+That file is bit-for-bit what the HDMI link will carry — receivers can be
+built and tested against it before any cable exists.
+
+## The one integration rule
+
+The link must deliver bytes unmodified: **full-range RGB, no scaling, no
+overscan, RGB 4:4:4**. The most common failure is a limited-range clamp
+(16–235) quietly destroying sample values; the `checker` and `corners`
+patterns exist to catch exactly that on day one. Details and the receiver
+rate rule are in [PROTOCOL.md](PROTOCOL.md).
+
+## Why this exists
+
+Built as the sensor front-end for FPGA image pipelines — for example, as the
+input to hardware generated with [np2hw](https://github.com/lanserge/np2hw)
+— but useful to anyone who wants real sensor data into a board without
+MIPI hardware, deserialisers, or per-sensor bring-up.
+
+## Licence
+
+MIT.

picam2hdmi-0.1.0/picam2hdmi.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+picam2hdmi/__init__.py
+picam2hdmi/capture.py
+picam2hdmi/cli.py
+picam2hdmi/output.py
+picam2hdmi.egg-info/PKG-INFO
+picam2hdmi.egg-info/SOURCES.txt
+picam2hdmi.egg-info/dependency_links.txt
+picam2hdmi.egg-info/entry_points.txt
+picam2hdmi.egg-info/requires.txt
+picam2hdmi.egg-info/top_level.txt

picam2hdmi-0.1.0/picam2hdmi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

picam2hdmi-0.1.0/picam2hdmi.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+picam2hdmi = picam2hdmi.cli:main

picam2hdmi-0.1.0/picam2hdmi.egg-info/requires.txt

@@ -0,0 +1,8 @@
+numpy
+bayerlink>=0.1.0
+
+[pi]
+picamera2
+
+[test]
+pytest

picam2hdmi-0.1.0/picam2hdmi.egg-info/top_level.txt

@@ -0,0 +1 @@
+picam2hdmi

picam2hdmi-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "picam2hdmi"
+version = "0.1.0"
+description = "Raspberry Pi camera as a raw-Bayer HDMI source, speaking the bayerlink protocol"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Serge Rabyking" }]
+requires-python = ">=3.9"
+keywords = ["raspberry-pi", "picamera2", "bayer", "raw", "hdmi", "fpga", "camera", "libcamera"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video :: Capture",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Topic :: Software Development :: Embedded Systems",
+]
+dependencies = [
+    "numpy",
+    # The wire format. Lives in the protocol's own repository so every
+    # encoder and receiver conforms to one spec; this tool re-exports its
+    # codec and adds only what is the Pi's.
+    "bayerlink>=0.1.0",
+]
+
+[project.optional-dependencies]
+# The capture backend, on the Pi itself. Everything else -- the protocol, the
+# patterns, decoding captured frames on the receiver's host -- needs numpy only.
+pi = ["picamera2"]
+test = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/bayerlink/picam2hdmi"
+Source = "https://github.com/bayerlink/picam2hdmi"
+Issues = "https://github.com/bayerlink/picam2hdmi/issues"
+
+[project.scripts]
+picam2hdmi = "picam2hdmi.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["picam2hdmi*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

picam2hdmi-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+