Skip to content

Add overexposed_frame_pct to frame stats from the luma values already computed #33

Closed

Description

@kstonekuan

Current behavior

The frame instrument already computes per-frame average luma for every frame (src/hflow/ffmpeg/_instrument.py:151), but only three aggregates are reported (_instrument.py:181-183): luma_avg_mean, luma_avg_min, and luma_avg_max.

Blackout has a dedicated metric (black_frame_pct, _instrument.py:41 and :178), but the symmetric failure (blown highlights from bad exposure, IR flood, or sun in frame) has no counterpart. luma_avg_max alone cannot distinguish one bright frame from a thousand.

Proposed change

  • Add overexposed_frame_pct to the FrameStats dataclass (_instrument.py:34-46), computed as the percentage of frames whose average luma is at or above a threshold.
  • Expose the threshold as a parameter on frame_stats (for example, bright_luma_threshold: float = 235.0), matching the module's rule that thresholds are user-owned.
  • Compute it from the existing luma_avg_values list: no new ffmpeg filter and no second decode pass.
  • Surface the new value as a measurement in camera_frame_stats (src/hflow/checks.py:189), next to black_pct.

Definition of done

  • frame_stats reports overexposed_frame_pct in the 0.0 to 100.0 range with the same denominator as black_frame_pct.
  • camera_frame_stats records the measurement per camera topic.
  • Extend tests/test_ffmpeg.py with a bright-video case (the existing fixtures show how the black-segment case is synthesized).

Validation

uv run pytest -q
uv run ruff check --fix && uv run ruff format
uv run ty check

Activity

  1. Sagar-024 commented on Aug 20, 2026

    @Sagar-024
    Contributor

    I'll take this one. Plan: expose overexposed_frame_pct from the luma values the frame stats already compute, mirroring the black_frame_pct pattern, plus a bright-video test in test_ffmpeg.py. PR shortly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions