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

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

From an installed package, no source checkout is required:

python -m pip install "retriever-core[demo]" rerun-sdk && retriever demo webcam --seconds 60 --visualize rerun --refresh

From a source checkout, the equivalent Pixi-backed task is:

retriever run webcam

Both paths run the same shape of graph on real camera input. Rerun shows frames and Boxes2D detection overlays over time; stdout remains available through --visualize stdout or the source-checkout fallback. 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	retriever run webcam-mock
No-clone live webcam with Rerun boxes	retriever demo webcam --seconds 60 --visualize rerun --refresh
Source-checkout live webcam, automatic Rerun/stdout fallback	retriever run webcam
Live webcam, multiprocessing backend, forced Rerun	retriever run webcam-rerun
Step the detector deterministically, no camera	retriever run perception-stepper
Portable recording for replay	retriever run record

Step 4: If it looks wrong

Symptom	Try first	Why
No camera or a permission prompt	retriever run webcam-mock	Removes hardware from the question.
Rerun viewer does not open	retriever run perception-stepper	Keeps runtime verification separate from viewer setup.
Graph wiring is unclear	retriever run graph	Shows Flow nodes, ports, clocks, and sync policies.
Detection output is surprising	retriever run perception-stepper	Steps the detector one frame at a time on deterministic mock frames.
Behavior changes between runs	retriever run record then 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. The fixed mock input trace produces the same output trace, while a recorded webcam trace can be replayed through the same graph — 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.