"""Sharpness-aware frame sampling for SfM (spec M2, lane B).

STUB — lane B fills the bodies; the public signatures below are frozen (``sfm.py`` calls
these). Sample candidate frames ~2/s per video; within each 0.5 s window keep the sharpest
frame (variance of Laplacian via OpenCV). Write JPEGs named ``{video_id}_{frame_idx}.jpg``
into ``config.FRAMES_DIR`` (one subfolder per video for COLMAP's single-camera-per-folder).
"""

from __future__ import annotations

import logging
from pathlib import Path

log = logging.getLogger("festival4d.frames")


def sharpness(image) -> float:
    """Variance of the Laplacian of a grayscale image (OpenCV) — higher is sharper."""
    raise NotImplementedError("lane B (M2): implement sharpness")


def sample_frames(video_path: Path, video_id: int, out_dir: Path,
                  target_fps: float = 2.0, window_s: float = 0.5) -> list[Path]:
    """Sample the sharpest frame per ``window_s`` window from ``video_path`` (spec M2).

    Returns the written JPEG paths (named ``{video_id}_{frame_idx}.jpg``).
    """
    raise NotImplementedError("lane B (M2): implement sample_frames")