Skip to content

Add latest-frame tracking and health reporting - #4

Merged
PCrnjak merged 1 commit into
mainfrom
codex/latest-frame-health
Nov 5, 2026
Merged

PCrnjak merged 1 commit into
mainfrom
codex/latest-frame-health

Conversation

@PCrnjak

@PCrnjak PCrnjak commented Nov 5, 2026

Copy link
Copy Markdown
Collaborator

A slow consumer of the legacy tracking stream can accumulate seconds of backlog. Add Tracker(mode="latest", max_frame_age=0.1) with a single replaceable unread frame and one thread owning source open/read/close. Reads wait for a distinct fresh frame; expired frames raise StaleFrameError if no replacement arrives by the deadline. The existing sequential default remains available for complete recording.

Expose immutable tracker.health snapshots in both modes: state, recent arrival FPS, local receipt age, frame/skip/duplicate/timeout counts, timestamp resets, hand count, and error details. Add CLI --latest, --max-frame-age, and --health; health JSON uses stderr, preserving frame output and recordings. Include a slow-consumer example and repeatable read-only benchmark.

Validation:

  • The installed b2 wheel passed 107 tests on each Windows CPython 3.10.11, 3.11.9, 3.12.10, 3.13.17, 3.14.10, and 3.15.2. Each received 30 live frames in each mode, replayed the existing real-hand session, closed its worker, and passed pip dependency checks.
  • Tests cover single-slot replacement, duplicate freshness, stale rejection, failures, EOF, source thread ownership, startup cleanup, reconnect, bounded shutdown, a close/read race, and CLI recording/health output.
  • Two 20 Hz consumers ran on the Original Leap Motion Controller for ten seconds: sequential mode ended 7.39 seconds behind latest mode in the same service clock. Latest local receipt age was 6.40 ms median and 12.07 ms p95.
  • A separate minute received 4,749 packets including warmup, with no read timeouts or tracking errors and clean close. Traced Python allocations peaked below 9 KB during measurement; native/service memory is excluded.
  • Ruff, wheel/sdist builds, strict Twine metadata checks, and release artifact checks passed locally. Platform CI runs on this PR.

No hands were visible during the new live measurements; these establish delivery behavior, not full-skeleton CPU cost or absolute camera latency. Linux/macOS controller hardware and clean-Windows driver setup remain pending. See docs/LATEST_FRAMES.md for semantics and evidence.

The source version is 0.1.0b2 for the next release and reuses the immutable b1 engine download. PyPI currently provides 0.1.0b1.

@PCrnjak
PCrnjak merged commit bd16e7e into main Nov 5, 2026
19 checks passed
@PCrnjak
PCrnjak deleted the codex/latest-frame-health branch November 10, 2026 12:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant