Visual Quickstart

Visual Quickstart: Color Detection

Start here if you want to see Retriever do something immediately. The first run is deterministic and hardware-free; the second run uses a real webcam and Rerun when available.

This is a source-checkout demo. The PyPI distribution target is retriever-core, while examples, Rerun, graph rendering, and tutorial assets live in the repository environment.

1. Mock camera -> color detector -> stdoutReliable first smoke for laptops, headless machines, CI, and AI agents.pixi run demo-webcam-detection-mock

2. Webcam -> color detector -> Rerun/stdoutShow a red or blue object to the camera. If Rerun cannot open, the demo falls back to stdout.pixi run demo-webcam-detection

Step 0: Install the Source Environment

git clone https://github.com/openretriever/retriever.git
cd retriever
pixi install

If you only need the library API after release, install the package:

pip install retriever-core

Step 1: Run the Deterministic Smoke

pixi run demo-webcam-detection-mock

Typical output:

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')]

What happened:

a camera Flow emitted synthetic image frames,
a detector Flow sampled the latest frame when triggered,
a display Flow printed detections,
the graph ran without camera permission, GUI windows, or backend setup.

Step 2: Switch to Webcam and Rerun

pixi run demo-webcam-detection

This uses the same tutorial pipeline with real camera input. On a machine with a working viewer, Rerun shows image frames and detections over time. If Rerun is unavailable, the command still emits stdout events so you can separate runtime correctness from viewer setup.

Step 3: Pick the Right Variant

Need	Command
Reliable first smoke, no hardware	`pixi run demo-webcam-detection-mock`
Live webcam with automatic Rerun/stdout fallback	`pixi run demo-webcam-detection`
Live webcam with multiprocessing and forced Rerun	`pixi run demo-webcam-detection-mp-rerun`
Mock frames with forced Rerun	`pixi run python -m examples.tutorial.b_ir_and_execution.06_dora_perception --backend in-process --camera-mode mock --visualize rerun --duration 10`
Portable recording for replay/debugging	`pixi run demo-webcam-record`

Why This Is First

The color-detection path is small but representative: it has sensor input, typed Flow outputs, asynchronous timing, visualization, and an immediate debugging story. The mock run proves the graph without hardware; the webcam run proves the live visual path. After this works, the same graph can be stepped, inspected, recorded, replayed, and moved to another backend.

See more example outputsNotebook-style cells for Flow, stepping, perception, graph render, and replay.Debug this graphRender the graph, step it locally, record events, and replay them.Understand the timingLearn why Retriever uses clocks and per-edge sync policies instead of one global loop.Continue to GoldenMove from the core visual demo to maintained robot-facing examples and Hub-pack proof.