From 15e0b9155a4e7a27a6c67437234d196da3509cb7 Mon Sep 17 00:00:00 2001
From: Cristhian <svarogcl@gmail.com>
Date: Tue, 15 Sep 2026 06:26:10 -0300
Subject: [PATCH] add a worked example wiring dora-webcam into this node

The only dataflow here drove the viewer from a test fixture, so nothing showed
how to consume a real producer. dataflow_webcam.yml wires dora-webcam v0.1.0
into it: the camera publishes std/media/v1/Image and this node draws it, with
depth, camera_info, text and bbox simply unwired, which is what every input
being optional buys.

The dependency points one way only. A consumer naming its producer is an arrow;
dora-webcam names no consumer, so there is no cycle.

Two things are deliberate. The camera's output type is repeated in the dataflow
because a `git:` node's manifest is not read at validate time, only at build, so
without it the two contracts are never compared -- a deliberate mismatch is
caught with the annotation and passes silently without it. And the file carries
no strict_types: a camera publishes an image and nothing else, and strict
validation warns about every typed input a dataflow leaves unwired.

Interoperability was verified directly, feeding dora-webcam's packed payload
into this node's decoder across bgr8, rgb8, jpeg, png and yuv420: the struct
types are identical and the lossless encodings round-trip exactly.

The dataflow validates but was not run: with dora-cli 1.0.1 a `git:` node
pointing at a private repository does not build over either transport, which
the file and the README record.
---
 README.md           | 25 +++++++++++++++++++++++++
 dataflow_webcam.yml | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 65 insertions(+)
 create mode 100644 dataflow_webcam.yml

diff --git a/README.md b/README.md
index d7f4ee3..9c63c1d 100644
--- a/README.md
+++ b/README.md
@@ -66,6 +66,31 @@ CI=true SOURCE_FRAMES=30 dora run dataflow.yml --uv
 
 `SOURCE_WIDTH` and `SOURCE_HEIGHT` (default 640x480) set the frame size.
 
+### With a real camera
+
+[`dataflow_webcam.yml`](dataflow_webcam.yml) wires
+[dora-webcam](https://gitea.liria.cl/liria/dora-webcam) into this node, and is the
+worked example of consuming something that is not a test fixture:
+
+```bash
+dora run dataflow_webcam.yml --uv
+```
+
+The camera publishes `std/media/v1/Image` and this node draws it. `depth`,
+`camera_info`, `text` and `bbox` are simply unwired — every input is optional, so a
+plain viewer is the result.
+
+It carries no `strict_types`, deliberately. A camera publishes an image and nothing
+else, and `dora validate --strict` warns about every *typed* input this node declares
+that a dataflow leaves unwired. The strictness belongs to `dataflow.yml`, which drives
+all of them.
+
+**Known limitation (dora-cli 1.0.1).** A `git:` node pointing at a private repository
+does not build: over `ssh://` on a non-standard port the connection fails, and over
+`https://` libgit2 reports `remote authentication required but no callback set`. The
+dataflow validates and the wiring is the form a consumer should use, but running it
+needs that fixed or the repository made public.
+
 ### Node manifest
 
 [`dora-node.yml`](dora-node.yml) declares the node's inputs with type URNs. No source
diff --git a/dataflow_webcam.yml b/dataflow_webcam.yml
new file mode 100644
index 0000000..4c6604c
--- /dev/null
+++ b/dataflow_webcam.yml
@@ -0,0 +1,40 @@
+# A real camera into the viewer, and the worked example of wiring this node to
+# something that is not a test fixture.
+#
+# Not run by CI: it needs a camera and it fetches dora-webcam over the network.
+# dataflow.yml is the gate, and needs neither.
+#
+# Known limitation, dora-cli 1.0.1: a `git:` node pointing at a *private*
+# repository does not build. Over ssh:// on a non-standard port the connection
+# fails outright, and over https:// libgit2 reports "remote authentication
+# required but no callback set" -- dora has no credential callback, so neither
+# transport authenticates. This file validates, and the wiring below is the form
+# a consumer should use; running it needs that fixed, or the repository public.
+#
+# `strict_types` is deliberately absent. A camera publishes an image and nothing
+# else, and `dora validate --strict` warns about every *typed* input this node
+# declares that a dataflow leaves unwired -- depth, camera_info and text here.
+# The wiring is correct; the strictness is aimed at the self-contained dataflow,
+# which drives all of them.
+
+nodes:
+  - id: camera
+    git: ssh://git@gitea.liria.cl:5001/liria/dora-webcam.git
+    tag: v0.1.0
+    build: uv pip install .
+    path: dora-webcam
+    inputs:
+      tick: dora/timer/millis/33
+    outputs:
+      - image
+    # dora-webcam's own manifest says this, but a `git:` node's manifest is not
+    # read at validate time -- only at build. Repeating it here is what makes
+    # the two contracts checked against each other now rather than at runtime.
+    output_types:
+      image: std/media/v1/Image
+
+  - id: view
+    path: dora-image-view
+    build: uv pip install .
+    inputs:
+      image: camera/image