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):

./scripts/retriever run webcam-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

./scripts/retriever run webcam

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 webcam-mock.

Step 3: Pick the right variant

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

Step 4: If it looks wrong

Symptom	Try first	Why
No camera or a permission prompt	./scripts/retriever run webcam-mock	Removes hardware from the question.
Rerun viewer does not open	./scripts/retriever run perception-stepper	Keeps runtime verification separate from viewer setup.
Graph wiring is unclear	./scripts/retriever run graph	Shows Flow nodes, ports, clocks, and sync policies.
Detection output is surprising	./scripts/retriever run perception-stepper	Steps the detector one frame at a time on deterministic mock frames.
Behavior changes between runs	./scripts/retriever run record then ./scripts/retriever run 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.Try the GoldenRetriever Hub quickstartMove from the core demo to a maintained Hub-loaded robot payload.