Tuning

Tuning Helios is config work, not code work: iterate until it works on the machine in front of you, then record the winning values in that machine's profile. The target is ≥ 20–30 FPS with legible, stable boxes.

Temporal smoothing

PPE and danger-zone state is decided by a rolling-window majority vote per track ID, so a violation or intrusion reads cleanly instead of strobing. Three knobs control it:

[default]
smoothing_window      = 8     # frames in the rolling vote (~a quarter-second at 30fps)
smoothing_min_ratio   = 0.6   # fraction of the window that must agree to hold a state
smoothing_evict_after = 15    # frames a vanished track survives before its history is dropped

How the vote behaves:

• Majority vote. A key is reported True when its true-count divided by its window length is at least min_ratio.
• Fast onset. A brand-new key with a single sample reports that sample immediately — the window is effectively length 1 — so a violation flashes without waiting for the window to fill.
• Anti-strobe. Once the window is full, flipping an established state takes ceil(window * (1 - min_ratio)) + 1 consecutive dissenting frames. With window = 4 and min_ratio = 0.6, three True frames followed by one False still yields True (3/4 = 0.75 ≥ 0.6).
• Bounded memory. A key absent for more than evict_after consecutive frames is dropped, so long sessions do not accumulate state.

Tune it by symptom:

Record the winning values in the machine's [profiles.<hostname>] table.

FPS versus box quality

All of these are config knobs; none requires a code change.

The measured FPS shown next to the feed is smoothed over the full loop iteration, after throttling to target_fps — so a value pinned near your target means the loop has headroom, not that it is struggling.

The one-time costs — the AMP check and the model-weight downloads — happen on first run only. Pre-warm them before you need the demo; see Quickstart.

Small-object recall (imgsz)

Small items — especially safety glasses — are the hardest to detect. The first lever is imgsz: a larger inference size improves small-object recall at an FPS cost.

If hard hat or vest recall is weak, raise imgsz (for example 640 to 896) and re-measure FPS, then record the winning value in that machine's profile. Hard hat and vest are the reliable items to lean on; do not promise glasses.

The tiling toggle

Tiling is the second small-object-recall lever. Instead of one full-frame inference, the frame is sliced into overlapping tiles that are inferred independently and merged.

• It is exposed as a Tiling button in the UI and flips live on the server — no restart, no code change. The tooltip states the trade-off plainly: "Tiling improves small-object recall but disables tracking-based counting while on."
• It ships off by default, so the default path is byte-for-byte the tracked full-frame path.
• tiling_enabled in helios.toml seeds the startup default only; the live toggle is authoritative afterward.
• tile_size (default 640) and tile_overlap (default 128) are config-only — there are no UI sliders.