Drop RealSense warm-up frames before serving the first frame

[cyrilcaoyang]

Problem

The first RealSense snapshot after the pipeline starts on demand came back dark with a green cast. Auto-exposure and white balance had not settled yet. On the UR5e D435i (serial 050222072123, 1280x720@15), the cold snapshot had mean luma 26, while frames taken a few seconds later had mean luma 87.

Change

• After each pipeline start, the capture loop now drops frames until both conditions are met: at least warmup_frames frames (default 30) and at least warmup_seconds seconds (default 2). This is the same rule the diagnostics path already used. Both values can be set per camera, are clamped to 0-300 frames and 0-10 s, and setting both to 0 disables the warm-up.
• latest() waits through the warm-up on top of frame_timeout_ms, so the first request after idle gets a settled frame instead of a 503 or a dark image. It is about 2 s slower. If the pipeline stops during the wait, it raises RealSenseNotStreaming.
• describe() reports warming_up.
• Two existing capture tests now wait for fps_measured instead of reading it straight after the first frames. The Windows monotonic clock ticks about every 16 ms, so several 2 ms fake frames can share a timestamp; these tests failed 3 of 5 runs on the camera PC before this change.
• README documents the two settings.

Testing

• pytest: 172 tests pass locally, three times on the Windows camera PC, and on both CI runners. New TestWarmup cases cover the defaults, clamping, skipped frame count, waiting longer than the frame timeout, warming up again after a restart, and stopping during warm-up.
• Live on sdl2-pc-05, deployed from this branch: after the camera had been idle, the first snapshot had mean luma 87.7, the same as the following stream and warm frames. The frame counter confirmed it was a fresh pipeline start.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KkFaeNK2BNBMCEx4AWJx6t