Upload clashcr/core/battle_gating.py with huggingface_hub

clashcr/core/battle_gating.py

@@ -0,0 +1,233 @@
+"""Battle gating: detect lobby/menu vs battle screen.
+
+Never emit card events outside a confirmed battle.
+Reset tracker state between battles.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from pathlib import Path
+from typing import Optional
+
+import cv2
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+class BattleState(Enum):
+    UNKNOWN = auto()
+    MENU = auto()
+    BATTLE = auto()
+    POST_BATTLE = auto()
+
+
+@dataclass
+class BattleGateResult:
+    state: BattleState
+    confidence: float
+    arena_roi: Optional[tuple] = None  # (x, y, w, h) in frame coords
+    own_roi: Optional[tuple] = None
+    opponent_roi: Optional[tuple] = None
+    is_spectator: bool = False
+    mode_hint: str = ""  # 'live', 'spectator', 'replay', 'tv_royale'
+
+
+class BattleGater:
+    """Determines whether the current frame shows an active battle.
+
+    Uses a combination of:
+    - Template matching for VS screen (battle start)
+    - Arena color/texture heuristics (grass/bridge patterns)
+    - HUD element detection (elixir bar, timer)
+    - Temporal consistency (require N consecutive battle frames)
+    """
+
+    def __init__(self,
+                 battle_threshold: float = 0.6,
+                 consecutive_frames: int = 3,
+                 vs_template_path: Optional[str] = None):
+        self.battle_threshold = battle_threshold
+        self.consecutive_frames = consecutive_frames
+        self.vs_template_path = vs_template_path
+        self._vs_template: Optional[np.ndarray] = None
+        self._consecutive_battle = 0
+        self._consecutive_menu = 0
+        self._state = BattleState.UNKNOWN
+        self._last_state_time = 0.0
+
+        if self.vs_template_path and Path(self.vs_template_path).exists():
+            self._vs_template = cv2.imread(self.vs_template_path, cv2.IMREAD_GRAYSCALE)
+
+    def _detect_vs_screen(self, gray: np.ndarray) -> float:
+        if self._vs_template is None:
+            return 0.0
+        best = 0.0
+        for scale in [0.5, 0.75, 1.0, 1.25, 1.5]:
+            resized = cv2.resize(self._vs_template, None, fx=scale, fy=scale)
+            if resized.shape[0] > gray.shape[0] or resized.shape[1] > gray.shape[1]:
+                continue
+            res = cv2.matchTemplate(gray, resized, cv2.TM_CCOEFF_NORMED)
+            _, max_val, _, _ = cv2.minMaxLoc(res)
+            best = max(best, max_val)
+        return best
+
+    def _detect_arena(self, frame: np.ndarray) -> float:
+        """Heuristic: does the central region look like an arena?
+
+        Looks for:
+        - Two tower-like structures near top/bottom center
+        - Bridge-like horizontal line in middle
+        - Green/brown dominant colors
+        """
+        h, w = frame.shape[:2]
+        # Use central crop
+        cx1, cx2 = int(w * 0.15), int(w * 0.85)
+        cy1, cy2 = int(h * 0.1), int(h * 0.9)
+        crop = frame[cy1:cy2, cx1:cx2]
+        if crop.size == 0:
+            return 0.0
+
+        # Convert to HSV for color analysis
+        hsv = cv2.cvtColor(crop, cv2.COLOR_BGR2HSV)
+        # Arena grass: green hue ~35-75, saturation > 40
+        green_mask = cv2.inRange(hsv, (35, 40, 20), (75, 255, 255))
+        green_ratio = np.count_nonzero(green_mask) / crop.size
+
+        # Arena road/bridge: brown/orange hue ~10-25
+        brown_mask = cv2.inRange(hsv, (10, 40, 40), (25, 255, 200))
+        brown_ratio = np.count_nonzero(brown_mask) / crop.size
+
+        # Look for vertical symmetry (two sides)
+        mid = crop.shape[1] // 2
+        left_half = crop[:, :mid]
+        right_half = crop[:, mid:]
+        if left_half.size > 0 and right_half.size > 0:
+            diff = np.mean(cv2.absdiff(left_half, right_half))
+            symmetry_score = 1.0 - min(diff / 100.0, 1.0)
+        else:
+            symmetry_score = 0.0
+
+        # Combine heuristics
+        score = (green_ratio * 0.4) + (brown_ratio * 0.3) + (symmetry_score * 0.3)
+        return min(score * 2.0, 1.0)  # Scale up a bit
+
+    def _detect_hud(self, frame: np.ndarray) -> float:
+        """Look for timer / elixir bar at top center."""
+        h, w = frame.shape[:2]
+        top_bar = frame[0:int(h * 0.12), int(w * 0.3):int(w * 0.7)]
+        if top_bar.size == 0:
+            return 0.0
+        gray = cv2.cvtColor(top_bar, cv2.COLOR_BGR2GRAY)
+        # Timer usually has high contrast digits
+        _, thresh = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+        white_ratio = np.count_nonzero(thresh) / thresh.size
+        # Expect moderate white ratio (digits on dark bg)
+        hud_score = 1.0 - abs(white_ratio - 0.15) / 0.15
+        return max(0.0, hud_score)
+
+    def _compute_rois(self, frame: np.ndarray) -> tuple:
+        """Compute arena, own-side, opponent-side ROIs.
+
+        For standard portrait layout:
+        - Arena: central area excluding top HUD and bottom hand cards
+        - Own side: bottom half of arena
+        - Opponent side: top half of arena
+        """
+        h, w = frame.shape[:2]
+        # Exclude top 10% (HUD) and bottom 15% (own hand cards)
+        arena_y1 = int(h * 0.10)
+        arena_y2 = int(h * 0.85)
+        arena_x1 = int(w * 0.05)
+        arena_x2 = int(w * 0.95)
+
+        arena_roi = (arena_x1, arena_y1, arena_x2 - arena_x1, arena_y2 - arena_y1)
+        mid_y = (arena_y1 + arena_y2) // 2
+        own_roi = (arena_x1, mid_y, arena_x2 - arena_x1, arena_y2 - mid_y)
+        opponent_roi = (arena_x1, arena_y1, arena_x2 - arena_x1, mid_y - arena_y1)
+
+        return arena_roi, own_roi, opponent_roi
+
+    def process(self, frame: np.ndarray) -> BattleGateResult:
+        gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+
+        vs_score = self._detect_vs_screen(gray)
+        arena_score = self._detect_arena(frame)
+        hud_score = self._detect_hud(frame)
+
+        # Combined battle confidence
+        battle_conf = max(arena_score, hud_score, vs_score * 0.5)
+
+        # State machine with hysteresis
+        if battle_conf >= self.battle_threshold:
+            self._consecutive_battle += 1
+            self._consecutive_menu = 0
+        else:
+            self._consecutive_menu += 1
+            self._consecutive_battle = 0
+
+        if self._consecutive_battle >= self.consecutive_frames and self._state != BattleState.BATTLE:
+            self._state = BattleState.BATTLE
+            self._last_state_time = time.monotonic()
+            logger.info("Battle detected (conf=%.2f)", battle_conf)
+        elif self._consecutive_menu >= self.consecutive_frames and self._state == BattleState.BATTLE:
+            self._state = BattleState.POST_BATTLE
+            self._last_state_time = time.monotonic()
+            logger.info("Battle ended")
+        elif self._consecutive_menu >= self.consecutive_frames and self._state != BattleState.MENU:
+            self._state = BattleState.MENU
+
+        arena_roi, own_roi, opponent_roi = self._compute_rois(frame)
+
+        # Spectator hint: if card icons visible on right side (spectator UI)
+        is_spectator = self._detect_spectator_ui(frame)
+
+        mode_hint = "live"
+        if is_spectator:
+            mode_hint = "spectator"
+        elif vs_score > 0.7:
+            mode_hint = "vs_screen"
+
+        return BattleGateResult(
+            state=self._state,
+            confidence=battle_conf,
+            arena_roi=arena_roi,
+            own_roi=own_roi,
+            opponent_roi=opponent_roi,
+            is_spectator=is_spectator,
+            mode_hint=mode_hint,
+        )
+
+    def _detect_spectator_ui(self, frame: np.ndarray) -> bool:
+        """Detect spectator/replay UI: small card icons on the right edge."""
+        h, w = frame.shape[:2]
+        right_strip = frame[int(h * 0.2):int(h * 0.8), int(w * 0.85):int(w * 0.98)]
+        if right_strip.size == 0:
+            return False
+        gray = cv2.cvtColor(right_strip, cv2.COLOR_BGR2GRAY)
+        # Look for many small high-contrast rectangles (card icons)
+        edges = cv2.Canny(gray, 50, 150)
+        contours, _ = cv2.findContours(edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+        small_rects = 0
+        for cnt in contours:
+            x, y, cw, ch = cv2.boundingRect(cnt)
+            aspect = cw / max(ch, 1)
+            if 0.6 < aspect < 1.4 and 15 < cw < 60 and 15 < ch < 60:
+                small_rects += 1
+        return small_rects >= 4
+
+    def reset(self) -> None:
+        self._consecutive_battle = 0
+        self._consecutive_menu = 0
+        self._state = BattleState.UNKNOWN
+        self._last_state_time = 0.0
+
+    @property
+    def state(self) -> BattleState:
+        return self._state
+
+    def is_battle(self) -> bool:
+        return self._state == BattleState.BATTLE