dora-image-view/AGENTS.md

AGENTS.md

This file provides guidance to AI coding assistants when working with code in this repository.

What this is

A dora-rs Python node that displays a video stream with overlays: it keeps one panel per frame stream (image, depth) plus a bbox set and text string, and every frame event redraws the lot as one side-by-side composite in an OpenCV window. It is a display sink — it produces no outputs. README.md documents the inputs, the encodings and the environment variables; this file covers only what the code and the README do not say.

Everything the example dataflow needs is in this checkout. Do not reintroduce a dependency on another repository — the example must keep running with no camera, no detector and no network.

It is Python on purpose. The node was first written in Rust against the opencv crate; that crate generates its bindings from the OpenCV headers installed on the build machine, so it needs libopencv-dev and libclang-dev on every machine and every architecture and does not cross-compile. Every dependency here ships prebuilt wheels for linux-x86_64, linux-aarch64 and macos-arm64, so uv sync is the whole install. Do not reintroduce a dependency that has to be compiled from source.

Commands

uv sync --group dev                      # deps plus pytest and ruff
uv run pytest && uv run ruff check .     # no camera/dataflow/display needed
dora run dataflow.yml --uv               # the example, in a window
CI=true SOURCE_FRAMES=30 dora run dataflow.yml --uv   # the same, headless

dora build --uv / dora run --uv rewrites each manifest's build: pip install . to uv pip install . and gives the node its own managed venv under .dora/python-envs/<node-id>/, so what it imports at runtime is what was installed at build time.

Architecture

• dora_image_view/main.py — Argument parsing and the dora event loop, nothing else. The env var wins over the CLI flag for VIEW_WIDTH/VIEW_HEIGHT. The upstream node spells these PLOT_WIDTH/PLOT_HEIGHT; they were renamed with the node, so a dataflow copied from upstream needs its env keys changed. Node(args.name) rather than Node() so the node also runs standalone as a dynamic node.
• dora_image_view/decode.py — to_bgr(): every supported encoding to a writable BGR array. Two behaviours are deliberate, not bugs: bgr8 copies (the payload may be a read-only view on shared memory, and the frame is annotated in place), and yuv420 converts with COLOR_YUV420p2RGB rather than ...2BGR — the upstream node converts to RGB and then displays it as BGR, and that channel swap is part of the behaviour callers already see.
• dora_image_view/view.py — View (the panels, the overlay state and the window) and Bboxes. headless (from CI=true) skips only the window: every input is still decoded and composed, which is what makes the node safe in a pipeline test. Panels are tiled in the fixed order in PANELS, not in arrival order, so a panel does not jump when a stream drops a frame. Boxes are drawn on the image panel before scaling, because they are in image pixels; the caption is drawn on the composite, because the panel it would otherwise land on may not be the leftmost one.
• dora_image_view/depth.py — to_millimetres() and colorize(). Decoding normalises to float32 millimetres with 0 for missing, so the colouring only ever sees one representation. Two things are deliberate: as_float32() reinterprets a uint8 payload rather than converting it, because a C++ node sending a raw byte slice produces a UInt8 arrow array despite declaring Float32; and the auto range is the valid pixels' full min/max, not a percentile. Trimming the tails looks safer and breaks the exact scene this node exists for — a small object in front of a large wall is a few percent of the pixels, so both tails land on the wall and the object clips away. A rendered check caught that; do not reintroduce percentile ranging.
• dora_image_view/bbox.py — Parses the bbox struct into xyxy corners. xywh is centre-based (x, y are the box centre). _flat() unwraps the single-element list that pa.array([{...}]) produces around each field, and reads a field stored flat as-is.
• examples/source.py — The synthetic source node: an animated frame, a depth map of the same scene (a flat wall with the square in front of it), the box around the square, and a caption. It exists so the example dataflow exercises all three inputs without a camera or a detector, and so CI can run the dataflow rather than only validate it. SOURCE_FRAMES bounds the run, which is what lets CI wait for a clean exit instead of killing it on a timeout.
• dora-node.yml — Node manifest (apiVersion: 1). dora validate injects these types into any dataflow that reaches the node by path:; a git:-sourced node does not pick it up, which is why the example builds from the checkout. image and text carry type URNs naming the element type because each payload is a raw buffer described by its metadata, not an Arrow struct. bbox is deliberately untyped: senders disagree on whether its numeric fields are 32- or 64-bit, and the node reads either.
• examples/dora-node.yml — Manifest for the source node, and not optional. dora validate matches a manifest to a path: node by entrypoint; with no manifest beside examples/source.py, the root dora-node.yml is tried against it, does not match its entrypoint, and warns — which strict_types: true turns into a failure. Declaring the source's types here rather than as output_types: in dataflow.yml is also what makes them checked: an inline annotation shadows the manifest, so the manifest would be injected but never compared.
• dataflow.yml — The example and the CI gate, with strict_types: true. Both nodes are path: nodes with a manifest, so both contracts are injected and compared against each other; bbox is annotated on neither side, matching the manifests.
• .gitea/workflows/validate.yml — CI: lints, runs the unit tests, validates the dataflow and runs it headless. Needs no camera and no display. One job on purpose — the gates themselves take about a second, and are dwarfed by preparing the runner.

Why CI installs libgl1

opencv-python links against libGL at import time, so import cv2 fails on the bare runner image and CI installs the shared libraries first. At roughly sixteen seconds it is the most expensive step in the job, several times everything else combined.

opencv-python-headless needs none of them, but it also has no imshow, which is this node's whole purpose. Removing the step therefore means making the GUI wheel an optional extra — headless by default, pip install .[gui] for a real window — and that is a change to what a consumer installs, not just to CI. It has not been done.

A caveat on typed optional inputs

dora validate --strict injects a contract type for every typed manifest input and then warns input_types key "..." not found in inputs list for any the dataflow does not wire. So a typed optional input forces the example dataflow to wire it. If a typed input is added to the manifest, either wire it in dataflow.yml or leave it untyped. This is why examples/source.py publishes a depth map at all: depth is typed, so the example has to drive it.

Checking what it draws

The gates prove the node does not crash, not that the picture is right — the colormap-ranging defect found while adding depth rendered as a plausible flat panel and passed every test. Compose a frame offline and look at it:

view = View(headless=True)
view.panels["depth"] = depth.colorize(depth.to_millimetres(storage, metadata))
cv2.imwrite("/tmp/frame.png", view.compose())

compose() is public for exactly this: it returns the composite without needing a window.

Rules

• Do not mention AI tools in commit messages or documentation.