Camera preview¶

Audience: operators with one or more cameras on the rig (USB webcam, FLIR IR, or both). Scope: what the live preview tile shows, how it relates to recording, what the cadence indicator and border colors mean, the pop-out window, and the per-camera controls.

The mental model¶

The preview tile and the recording stream are separate consumers of the same camera frames. The preview is always live; recording only happens between Run → Start and Run → Stop.

                     +----+
   Camera frame ---> | pump | --(every frame, while recording)--> encoder → .mkv / .csq
                     |      | --(every 500 ms, always)-----------> preview tile
                     +----+

What follows from this:

• The tile shows a live image even when no run is active. This is on purpose. The pump opens the camera once at config-load and keeps it open across runs — the Windows DirectShow filter graph hold-time used to freeze the tile for several seconds after every run-stop; the open-once design removed that.
• A live tile does not mean recording is happening. The recording badge on the Run tab is the only reliable signal. Trust the badge, not the moving image.
• A frozen tile during a run means the pump stopped feeding both consumers. If the tile is live and the badge is on, recording is happening.

Cadence indicator¶

Each tile has a small cadence indicator that flips between three states based on how recently a preview JPEG arrived:

A stale indicator during an active run is the operator's first signal that something is wrong with the camera path. Check the diagnostics dock and the per-tile drop counter.

Tile border colors¶

The border is sticky — once it changes, it does not auto-revert. A new color is shown until the dock is rebuilt at the next config-load. This is on purpose: a transient camera fault that auto-cleared would hide a bug.

The visible-webcam path used to trip pump_warning at t ≈ 23 s into a recipe and silently lose the run; the adapter now drops the bad frame, logs the event, and keeps recording — the yellow border exists so the operator sees that something was lost.

Pop-out window¶

The tile is a 320 px thumbnail, too small to judge focus. Click Pop out on a tile (or double-click the tile) to open that camera in its own window:

• Drag the window to any size, or press F11 or double-click the image for full screen. Esc leaves full screen; pressed again it closes the window.
• While the window is open the webcam sends full-size frames — the camera's own capture resolution, not an enlarged thumbnail — at 10 Hz, so you can watch focus settle after each Apply on the manual card.
• The window is for between runs. Starting a run closes it, and Pop out stays disabled until the run ends. The webcam also ignores the full-size request while recording, so a recording costs exactly what it did before the pop-out existed.
• The footer gives the frame size in pixels and says no new frames if the feed stops, so a frozen image isn't mistaken for a focus change that did nothing.
• Closing the window puts the camera back on thumbnails.

The window stays in front of the main window, so you can keep the webcam's manual card visible beside it: set Auto focus off, then step Focus value and Apply while you watch the window.

FLIR and simulated IR cameras have no full-size mode; their window shows the usual preview, scaled up.

Cameras without LIVE_PREVIEW¶

If an adapter does not declare CameraCapability.LIVE_PREVIEW, the tile shows a static placeholder and never receives frames. The runtime short-circuits at CameraDeviceAdapter.start_preview_channel so the preview bridge stays empty rather than burning CPU pulling frames nobody will draw.

This is rare in production — every shipping camera adapter (webcam, FLIR, IR sim) declares LIVE_PREVIEW.

Per-camera controls¶

The manual card renders every control section for its camera kind. Once the camera has been read, rows for controls it lacks are greyed out — a fixed-focus laptop webcam shows its focus row disabled.

Webcam (visible)¶

UVC controls are Windows-only and require the duvc-ctl wheel. On Linux/macOS the rows are greyed out and the card's header says why. Each control's range, step, value and auto mode are read from the camera when the card is built, when the pool opens, after each Apply and after an experiment's device settings are applied.

The dshow list_options probe (Windows) enumerates the device's supported (width, height) pairs and per-resolution max fps — those populate the resolution spinbox so it can't request a mode the camera doesn't have.

See USB webcams for the adapter implementation.

FLIR IR¶

The FLIR adapter has the richest camera-side command surface. The preview tile exposes the operator-facing subset; the rest is available from the manual-control card or via procedures.

See FLIR IR cameras for the full command list and the Atlas SDK requirements.

Preview throttling and CPU impact¶

Preview is capped at 2 Hz (PREVIEW_INTERVAL_NS = 500_000_000). JPEG width is capped at 320 px (aspect preserved) at quality 70 — well under 30 kB even for high-detail frames.

While a pop-out window is open between runs, the webcam sends full-size JPEGs at quality 85 instead, at 10 Hz (PREVIEW_DETAIL_INTERVAL_NS). Closing the window, or starting a run, drops it back to thumbnails; while recording, previews are always the 2 Hz thumbnails.

For the webcam adapter, encoding the preview JPEG runs on the same worker thread as the H.264 encoder — the dominant cost is the recording encoder, not the preview. For the FLIR adapter, the Atlas callback fires on its own thread and the JPEG conversion happens downstream of FramePump.

If the sat (saturation) pill goes yellow on a rig with cameras active, the recording encoder is the suspect — not the preview. See saturation deadline and the saturation triage flow.

Confirming the camera is being recorded¶

The preview is never blank between runs — so "I see a live tile" is not proof of recording. The Run tab's per-camera status badge is the authoritative signal:

For the bundle-side question — "did the recording actually land in the manifest?" — see reviewing a run and the manifest's cameras block (bundles → manifest and schema).

See also¶

• USB webcams — visible-camera adapter.
• FLIR IR cameras — IR adapter.
• Status bar guide — the sat pill and other live indicators.
• Saturation deadline — what triggers the yellow/red state.
• The Run tab — where the recording badge lives.
• Reviewing a run — confirming the recording made it into the bundle.