framesig 0.1.0__py3-none-any.whl

framesig/detectors.py

@@ -0,0 +1,256 @@
+"""Pixel-signature detectors.
+
+A detector turns the pixels of a cropped region into a single score in
+``[0, 1]``. Higher means "the event looks more present in this frame". Detectors
+are deliberately dumb and stateless-per-frame (except :class:`SceneChange`,
+which remembers the previous region); turning a stream of scores into discrete
+events is the job of :mod:`framesig.events`.
+
+Everything is game- and source-agnostic: a detector only ever sees a numpy BGR
+crop, never any knowledge of what produced it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping
+
+import cv2
+import numpy as np
+
+from ._coerce import as_bool
+from .errors import ConfigError
+
+# BGR channel indices, matching OpenCV's default byte order.
+_CHANNEL_INDEX = {"blue": 0, "green": 1, "red": 2}
+
+
+class Detector:
+    """Base class. Subclasses implement :meth:`score`.
+
+    A detector instance is created once per signature and reused for every
+    sampled frame, so it may cache small amounts of state between calls (see
+    :class:`SceneChange`).
+    """
+
+    #: Registry key used in YAML ``detector:`` fields.
+    type_name: str = "base"
+
+    def score(self, roi: np.ndarray) -> float:
+        """Return a score in ``[0, 1]`` for a single BGR region crop."""
+        raise NotImplementedError
+
+    def reset(self) -> None:
+        """Forget any per-video state. Called once before each scan."""
+
+    def fingerprint(self) -> dict[str, Any]:
+        """Return the parameters that affect the score, for cache keying."""
+        return {"type": self.type_name}
+
+    @staticmethod
+    def _clamp(value: float) -> float:
+        return float(max(0.0, min(1.0, value)))
+
+
+class Brightness(Detector):
+    """Mean luminance of the region.
+
+    Great for full-screen white flashes (explosions, flashbangs) with
+    ``invert=False``, or for fades to black / death screens with ``invert=True``.
+    """
+
+    type_name = "brightness"
+
+    def __init__(self, *, invert: bool = False) -> None:
+        self.invert = bool(invert)
+
+    def score(self, roi: np.ndarray) -> float:
+        gray = cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY)
+        value = float(gray.mean()) / 255.0
+        return self._clamp(1.0 - value if self.invert else value)
+
+    def fingerprint(self) -> dict[str, Any]:
+        return {"type": self.type_name, "invert": self.invert}
+
+
+class ChannelDominance(Detector):
+    """How strongly one BGR channel dominates the other two, region-averaged.
+
+    This is the "relative red" signature: a red kill/death flash pushes the mean
+    red far above mean green and blue, even under compression, without caring
+    about absolute brightness. ``gain`` scales the raw dominance (in 0..255)
+    into the ``[0, 1]`` score before clamping.
+    """
+
+    type_name = "channel_dominance"
+
+    def __init__(self, *, channel: str = "red", gain: float = 1.0) -> None:
+        if channel not in _CHANNEL_INDEX:
+            raise ConfigError(
+                f"channel_dominance: channel must be one of "
+                f"{sorted(_CHANNEL_INDEX)}, got {channel!r}"
+            )
+        if gain <= 0:
+            raise ConfigError("channel_dominance: gain must be positive")
+        self.channel = channel
+        self.gain = float(gain)
+
+    def score(self, roi: np.ndarray) -> float:
+        means = roi.reshape(-1, 3).mean(axis=0)  # [B, G, R]
+        idx = _CHANNEL_INDEX[self.channel]
+        others = float(max(means[i] for i in range(3) if i != idx))
+        dominance = (float(means[idx]) - others) / 255.0
+        return self._clamp(dominance * self.gain)
+
+    def fingerprint(self) -> dict[str, Any]:
+        return {"type": self.type_name, "channel": self.channel, "gain": self.gain}
+
+
+class ColorFraction(Detector):
+    """Fraction of region pixels that fall inside one or more HSV colour ranges.
+
+    Ideal for a coloured HUD element that occupies a known band of the frame
+    (a red kill-feed row, a blue objective banner). Because red wraps around the
+    hue circle, you may pass a second range via ``hsv_low2`` / ``hsv_high2``.
+
+    HSV bounds follow OpenCV's conventions: H in ``[0, 179]``, S and V in
+    ``[0, 255]``.
+    """
+
+    type_name = "color_fraction"
+
+    def __init__(
+        self,
+        *,
+        hsv_low: list[int],
+        hsv_high: list[int],
+        hsv_low2: list[int] | None = None,
+        hsv_high2: list[int] | None = None,
+    ) -> None:
+        self._ranges = [self._as_bound("hsv_low", hsv_low), self._as_bound("hsv_high", hsv_high)]
+        self.ranges = [(self._ranges[0], self._ranges[1])]
+        if (hsv_low2 is None) != (hsv_high2 is None):
+            raise ConfigError(
+                "color_fraction: hsv_low2 and hsv_high2 must be provided together"
+            )
+        if hsv_low2 is not None and hsv_high2 is not None:
+            self.ranges.append(
+                (self._as_bound("hsv_low2", hsv_low2), self._as_bound("hsv_high2", hsv_high2))
+            )
+
+    @staticmethod
+    def _as_bound(field: str, value: list[int]) -> np.ndarray:
+        try:
+            length = len(value)
+        except TypeError:
+            length = -1
+        if length != 3:
+            raise ConfigError(f"color_fraction: {field} must be a list of 3 integers [H, S, V]")
+        try:
+            h, s, v = (int(item) for item in value)
+        except (ValueError, TypeError) as exc:
+            raise ConfigError(
+                f"color_fraction: {field} must be a list of 3 integers [H, S, V], "
+                f"got {value!r}"
+            ) from exc
+        # Range-check before the uint8 cast: numpy 2.x raises OverflowError while
+        # numpy 1.x silently wraps (256 -> 0), and both are inside our pin.
+        if not (0 <= h <= 179 and 0 <= s <= 255 and 0 <= v <= 255):
+            raise ConfigError(
+                f"color_fraction: {field} out of range; H in [0, 179], "
+                f"S and V in [0, 255], got {value}"
+            )
+        return np.array([h, s, v], dtype=np.uint8)
+
+    def score(self, roi: np.ndarray) -> float:
+        hsv = cv2.cvtColor(roi, cv2.COLOR_BGR2HSV)
+        mask = None
+        for low, high in self.ranges:
+            part = cv2.inRange(hsv, low, high)
+            mask = part if mask is None else cv2.bitwise_or(mask, part)
+        assert mask is not None  # at least one range always exists
+        return self._clamp(float(np.count_nonzero(mask)) / mask.size)
+
+    def fingerprint(self) -> dict[str, Any]:
+        return {
+            "type": self.type_name,
+            "ranges": [[low.tolist(), high.tolist()] for low, high in self.ranges],
+        }
+
+
+class SceneChange(Detector):
+    """Mean absolute difference from the previously sampled region.
+
+    Fires on hard cuts and big visual transitions. It is stateful: the first
+    sampled frame of a scan always scores ``0`` because there is nothing to
+    compare against yet.
+    """
+
+    type_name = "scene_change"
+
+    def __init__(self) -> None:
+        self._prev: np.ndarray | None = None
+
+    def reset(self) -> None:
+        self._prev = None
+
+    def score(self, roi: np.ndarray) -> float:
+        gray = cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY)
+        if self._prev is None or self._prev.shape != gray.shape:
+            self._prev = gray
+            return 0.0
+        diff = cv2.absdiff(gray, self._prev)
+        self._prev = gray
+        return self._clamp(float(diff.mean()) / 255.0)
+
+
+# --- registry ---------------------------------------------------------------
+
+_FACTORIES: dict[str, Callable[[Mapping[str, Any]], Detector]] = {
+    Brightness.type_name: lambda p: Brightness(
+        invert=as_bool("brightness: invert", p.get("invert", False))
+    ),
+    ChannelDominance.type_name: lambda p: ChannelDominance(
+        channel=str(p.get("channel", "red")), gain=float(p.get("gain", 1.0))
+    ),
+    ColorFraction.type_name: lambda p: ColorFraction(
+        hsv_low=p["hsv_low"],
+        hsv_high=p["hsv_high"],
+        hsv_low2=p.get("hsv_low2"),
+        hsv_high2=p.get("hsv_high2"),
+    ),
+    SceneChange.type_name: lambda p: SceneChange(),
+}
+
+
+def available_detectors() -> list[str]:
+    """Return the sorted list of detector type names known to framesig."""
+    return sorted(_FACTORIES)
+
+
+def build_detector(type_name: str, params: Mapping[str, Any] | None = None) -> Detector:
+    """Instantiate a detector from its type name and a params mapping.
+
+    Raises:
+        ConfigError: If ``type_name`` is unknown or the params are invalid.
+    """
+    params = params or {}
+    if not isinstance(params, Mapping):
+        raise ConfigError(
+            f"detector {type_name!r}: params must be a mapping, "
+            f"got {type(params).__name__}"
+        )
+    try:
+        factory = _FACTORIES[type_name]
+    except KeyError:
+        raise ConfigError(
+            f"unknown detector type {type_name!r}; "
+            f"available: {available_detectors()}"
+        ) from None
+    try:
+        return factory(params)
+    except KeyError as exc:
+        raise ConfigError(
+            f"detector {type_name!r}: missing required param {exc.args[0]!r}"
+        ) from exc
+    except (ValueError, TypeError, OverflowError) as exc:
+        raise ConfigError(f"detector {type_name!r}: invalid params: {exc}") from exc

framesig/errors.py

@@ -0,0 +1,29 @@
+"""Exception hierarchy for framesig.
+
+Every error raised by the library inherits from :class:`FramesigError`, so
+callers can catch the whole family with a single ``except`` while still being
+able to distinguish the interesting cases.
+"""
+
+from __future__ import annotations
+
+
+class FramesigError(Exception):
+    """Base class for every error raised by framesig."""
+
+
+class ConfigError(FramesigError):
+    """Raised when a configuration file is malformed or inconsistent.
+
+    For example: an unknown detector type, a signature that references a region
+    that was never declared, or a region whose fractional bounds fall outside
+    the ``[0, 1]`` range.
+    """
+
+
+class VideoError(FramesigError):
+    """Raised when a video file cannot be opened or decoded."""
+
+
+class DependencyError(FramesigError):
+    """Raised when an external dependency (e.g. the ``ffmpeg`` binary) is missing."""

framesig/events.py

@@ -0,0 +1,150 @@
+"""Turning score timelines into discrete events.
+
+The scanner produces, for each signature, a score at every sampled timestamp.
+This module thresholds that timeline, merges nearby hits, drops blips that are
+too short, and reports one :class:`Event` per surviving run.
+
+Detection is intentionally separated from scanning: because the (expensive)
+scores are cached, you can re-run :func:`detect_events` with different
+thresholds as many times as you like for free.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any, Sequence
+
+
+@dataclass(frozen=True)
+class Event:
+    """A single detected occurrence of a signature.
+
+    Attributes:
+        signature: Name of the signature that fired.
+        start: Timestamp (seconds) of the first sample in the run.
+        end: Timestamp (seconds) of the last sample in the run.
+        duration: ``end - start`` plus one sample period, so a single-sample
+            spike still reports a non-zero duration. The period is measured
+            from the timeline itself unless the caller supplies it; a timeline
+            of fewer than two samples has no measurable period, so pass
+            ``period=`` explicitly for one to be used.
+        peak_t: Timestamp of the highest-scoring sample in the run.
+        peak_score: The highest score in the run.
+        mean_score: Mean score across the run's samples.
+        samples: Number of sampled frames in the run.
+    """
+
+    signature: str
+    start: float
+    end: float
+    duration: float
+    peak_t: float
+    peak_score: float
+    mean_score: float
+    samples: int
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serialisable dict, with floats rounded for tidy output."""
+        d = asdict(self)
+        for key in ("start", "end", "duration", "peak_t", "peak_score", "mean_score"):
+            d[key] = round(float(d[key]), 4)
+        return d
+
+
+def _sample_period(timestamps: Sequence[float]) -> float:
+    """Estimate the spacing between samples (median of successive deltas)."""
+    if len(timestamps) < 2:
+        return 0.0
+    deltas = sorted(timestamps[i + 1] - timestamps[i] for i in range(len(timestamps) - 1))
+    return deltas[len(deltas) // 2]
+
+
+def detect_events(
+    signature: str,
+    timestamps: Sequence[float],
+    scores: Sequence[float],
+    *,
+    threshold: float,
+    min_duration: float = 0.0,
+    merge_gap: float = 0.0,
+    period: float | None = None,
+) -> list[Event]:
+    """Detect events in a single signature's score timeline.
+
+    Args:
+        signature: Name attached to every returned event.
+        timestamps: Sample timestamps in seconds, ascending.
+        scores: Scores aligned with ``timestamps``.
+        threshold: A sample is "active" when ``score >= threshold``.
+        min_duration: Runs shorter than this (seconds) are discarded, filtering
+            out single-frame noise.
+        merge_gap: Active runs separated by a gap no larger than this (seconds)
+            are merged into one event. Useful when an effect flickers.
+        period: The spacing between samples, in seconds, added to every event's
+            duration so a single-sample spike is not zero-length. Defaults to
+            the median gap in ``timestamps``, which is ``0.0`` when fewer than
+            two samples were taken; :func:`framesig.scanner.detect_all` passes
+            the scan's own ``sample_period`` so that case is covered.
+
+    Returns:
+        A list of :class:`Event`, ordered by start time.
+    """
+    if len(timestamps) != len(scores):
+        raise ValueError("timestamps and scores must have equal length")
+    if not timestamps:
+        return []
+
+    if period is None:
+        period = _sample_period(timestamps)
+    period = float(period)
+
+    # 1. Collect maximal runs of consecutive active samples as index ranges.
+    runs: list[tuple[int, int]] = []
+    start: int | None = None
+    for i, s in enumerate(scores):
+        if s >= threshold:
+            if start is None:
+                start = i
+        else:
+            if start is not None:
+                runs.append((start, i - 1))
+                start = None
+    if start is not None:
+        runs.append((start, len(scores) - 1))
+
+    if not runs:
+        return []
+
+    # 2. Merge runs whose time gap is within merge_gap.
+    merged: list[tuple[int, int]] = [runs[0]]
+    for a, b in runs[1:]:
+        prev_a, prev_b = merged[-1]
+        gap = timestamps[a] - timestamps[prev_b]
+        if gap <= merge_gap:
+            merged[-1] = (prev_a, b)
+        else:
+            merged.append((a, b))
+
+    # 3. Build events, applying the minimum-duration filter.
+    events: list[Event] = []
+    for a, b in merged:
+        start_t = float(timestamps[a])
+        end_t = float(timestamps[b])
+        duration = end_t - start_t + period
+        if duration < min_duration:
+            continue
+        run_scores = scores[a : b + 1]
+        peak_local = max(range(len(run_scores)), key=lambda k: run_scores[k])
+        events.append(
+            Event(
+                signature=signature,
+                start=start_t,
+                end=end_t,
+                duration=duration,
+                peak_t=float(timestamps[a + peak_local]),
+                peak_score=float(run_scores[peak_local]),
+                mean_score=float(sum(run_scores) / len(run_scores)),
+                samples=b - a + 1,
+            )
+        )
+    return events

framesig/regions.py

@@ -0,0 +1,121 @@
+"""Regions of interest (ROIs).
+
+A :class:`Region` describes a rectangular slice of the frame. Bounds may be
+given either as fractions of the frame size (the default, resolution
+independent) or as absolute pixels. The scanner resolves each region to an
+integer pixel box once per video and then crops every sampled frame with it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+import numpy as np
+
+from ._coerce import as_number
+from .errors import ConfigError
+
+Box = tuple[int, int, int, int]  # (x0, y0, x1, y1) in pixels
+
+
+@dataclass(frozen=True)
+class Region:
+    """A rectangular region of interest.
+
+    Attributes:
+        name: Identifier used by signatures to reference this region.
+        x: Left edge.
+        y: Top edge.
+        w: Width.
+        h: Height.
+        unit: ``"fraction"`` (default) interprets the bounds as fractions of the
+            frame size, so the same region works at any resolution.
+            ``"pixels"`` interprets them as absolute integers.
+    """
+
+    name: str
+    x: float
+    y: float
+    w: float
+    h: float
+    unit: str = "fraction"
+
+    def __post_init__(self) -> None:
+        if self.unit not in ("fraction", "pixels"):
+            raise ConfigError(
+                f"region {self.name!r}: unit must be 'fraction' or 'pixels', "
+                f"got {self.unit!r}"
+            )
+        if self.w <= 0 or self.h <= 0:
+            raise ConfigError(f"region {self.name!r}: width and height must be positive")
+        if self.unit == "fraction":
+            if not (0.0 <= self.x <= 1.0 and 0.0 <= self.y <= 1.0):
+                raise ConfigError(
+                    f"region {self.name!r}: fractional x/y must be within [0, 1]"
+                )
+            if self.x + self.w > 1.0 + 1e-9 or self.y + self.h > 1.0 + 1e-9:
+                raise ConfigError(
+                    f"region {self.name!r}: fractional box extends past the frame edge"
+                )
+
+    @classmethod
+    def from_mapping(cls, name: str, data: Mapping[str, Any]) -> "Region":
+        """Build a region from a parsed YAML mapping."""
+        if not isinstance(data, Mapping):
+            raise ConfigError(
+                f"region {name!r}: must be a mapping with x, y, w, h, "
+                f"got {type(data).__name__}"
+            )
+        allowed = {"x", "y", "w", "h", "unit"}
+        unknown = set(data) - allowed
+        if unknown:
+            raise ConfigError(
+                f"region {name!r}: unknown keys {sorted(unknown)}; "
+                f"allowed keys are {sorted(allowed)}"
+            )
+        try:
+            raw_x, raw_y, raw_w, raw_h = (data[key] for key in ("x", "y", "w", "h"))
+        except KeyError as exc:
+            raise ConfigError(
+                f"region {name!r}: missing required key {exc.args[0]!r}"
+            ) from exc
+        return cls(
+            name=name,
+            x=as_number(f"region {name!r}: x", raw_x),
+            y=as_number(f"region {name!r}: y", raw_y),
+            w=as_number(f"region {name!r}: w", raw_w),
+            h=as_number(f"region {name!r}: h", raw_h),
+            unit=str(data.get("unit", "fraction")),
+        )
+
+    def resolve(self, frame_w: int, frame_h: int) -> Box:
+        """Return the integer pixel box ``(x0, y0, x1, y1)`` for a given frame size.
+
+        The box is always at least one pixel wide and tall, and is clamped to
+        the frame bounds so cropping can never raise.
+        """
+        if self.unit == "fraction":
+            x0 = int(round(self.x * frame_w))
+            y0 = int(round(self.y * frame_h))
+            x1 = int(round((self.x + self.w) * frame_w))
+            y1 = int(round((self.y + self.h) * frame_h))
+        else:
+            x0, y0 = int(round(self.x)), int(round(self.y))
+            x1, y1 = int(round(self.x + self.w)), int(round(self.y + self.h))
+
+        x0 = max(0, min(x0, frame_w - 1))
+        y0 = max(0, min(y0, frame_h - 1))
+        x1 = max(x0 + 1, min(x1, frame_w))
+        y1 = max(y0 + 1, min(y1, frame_h))
+        return x0, y0, x1, y1
+
+    def crop(self, frame: np.ndarray) -> np.ndarray:
+        """Crop ``frame`` (an ``H x W x 3`` BGR array) to this region."""
+        h, w = frame.shape[:2]
+        x0, y0, x1, y1 = self.resolve(w, h)
+        return frame[y0:y1, x0:x1]
+
+    def fingerprint(self) -> dict[str, Any]:
+        """Return the score-relevant fields for cache keying."""
+        return {"x": self.x, "y": self.y, "w": self.w, "h": self.h, "unit": self.unit}