Visual Quickstart: Color Detection

The fastest way to see Retriever work. One command builds a three-Flow perception graph — camera, color detector, display — and runs it on synthetic frames. No camera, no GUI, no Rerun, no robot backend.

What you’ll get: a deterministic detection run in stdout, and a graph you can then step, render, record, and replay.

Step 1: Run it

From a source checkout with the environment built (install):

pixi run demo-webcam-detection-mock

Stripped of INFO log lines, the output is:

============================================================
Perception Demo - Live or Mock Camera to Detection

Building perception pipeline:
  Camera @ Rate(20Hz) -> ColorDetector @ Trigger -> Display @ Rate

✓ Graph created: 3 nodes, 5 edges

Running for 0.1 seconds...
Tip: This run is using mock frames. Use --camera-mode real to require a live webcam path.
------------------------------------------------------------
  Frame 1: 2 objects - [('red_object', '0.95'), ('blue_object', '0.95')]
------------------------------------------------------------

============================================================
Pipeline Summary

Camera Input:
  • Uses mock test pattern when mock mode is selected or auto fallback triggers

Detection:
  • Red objects: RGB(255, <100, <100)
  • Blue objects: RGB(<100, <100, 255)

Tip: Use red or blue paper/objects in front of camera!
============================================================

Success criterion: you see ✓ Graph created: 3 nodes, 5 edges and at least one Frame N: … objects line. The mock run is short (0.1s) and deterministic, so the same frame result appears every time.

What just ran:

• CameraSource @ Rate(20Hz) emitted a synthetic frame,
• ColorDetector @ Trigger sampled the latest frame when its trigger fired,
• the display Flow printed the detections,
• the graph ran to a fixed duration and stopped — no camera permission, GUI window, Rerun viewer, or backend setup.

Step 2: Switch to a live webcam and Rerun

pixi run demo-webcam-detection

Same graph, real camera input. This target uses --visualize auto: on a machine with a working viewer, Rerun shows frames and detections over time; otherwise it falls back to stdout so runtime correctness stays separate from viewer setup. It needs a webcam — if you have none, stay on -mock.

Step 3: Pick the right variant

Need	Command
Reliable first smoke, no hardware	pixi run demo-webcam-detection-mock
Live webcam, automatic Rerun/stdout fallback	pixi run demo-webcam-detection
Live webcam, multiprocessing backend, forced Rerun	pixi run demo-webcam-detection-mp-rerun
Step the detector deterministically, no camera	pixi run demo-perception-stepper
Portable recording for replay	pixi run demo-webcam-record

Step 4: If it looks wrong

Symptom	Try first	Why
No camera or a permission prompt	pixi run demo-webcam-detection-mock	Removes hardware from the question.
Rerun viewer does not open	pixi run demo-perception-stepper	Keeps runtime verification separate from viewer setup.
Graph wiring is unclear	pixi run docs-tutorial-perception-html	Shows Flow nodes, ports, clocks, and sync policies.
Detection output is surprising	pixi run demo-perception-stepper	Steps the detector one frame at a time on deterministic mock frames.
Behavior changes between runs	pixi run demo-webcam-record then replay	Saves the input stream as a reusable artifact.

Why this demo is first

The color-detection path is small but complete: sensor input, typed Flow outputs, asynchronous timing, and an immediate debugging story. The mock run proves the graph without hardware; the webcam run proves the live path. Because the same input trace produces the same output trace, this exact graph can then be stepped, rendered, recorded, and replayed without changing a line — which is the rest of the tutorial path.

See more example outputsFlow, stepping, perception, graph render, and replay — each with real output.Debug this graphRender it, step it, record events, and replay them.Understand the timingWhy Retriever uses clocks and per-edge sync policies instead of one global loop.Run the first GoldenRetriever proofMove from the core demo to a maintained Hub-loaded robot payload.