Initial commit: scorebug

.gitattributes

@@ -0,0 +1 @@
+*.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,25 @@
+# Video files (too large for git)
+full_videos/
+
+# Local configuration
+AGENTS.md
+
+# Generated output
+output/
+
+# Ground truth annotations (local testing data)
+tests/test_data/ground_truth_plays.json
+
+# Python
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+

README.md

@@ -0,0 +1,105 @@
+# CFB40 - College Football Play Detection System
+
+Automatically detect and extract live plays from college football game videos, producing a condensed highlight reel.
+
+## Project Status
+
+**Status:** Fresh start with scorebug detection foundation
+
+## Project Structure
+
+```
+cfb40/
+├── src/
+│   └── detectors/
+│       ├── scorebug_detector.py    # Scorebug detection via template matching
+│       └── __init__.py
+├── data/
+│   └── templates/                  # Scorebug template images (17 templates)
+├── tests/
+│   └── test_data/
+│       └── ground_truth_plays.json # 12 annotated plays (gitignored)
+├── full_videos/                    # Source video files (gitignored)
+├── output/                         # Generated output (gitignored)
+├── .gitignore
+├── pyproject.toml
+└── README.md
+```
+
+## Setup
+
+### Prerequisites
+- Python 3.13+
+- Virtual environment (`.venv`)
+
+### Installation
+
+1. Clone the repository
+
+2. Create and activate virtual environment:
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+3. Install dependencies:
+```bash
+pip install opencv-python numpy pillow
+```
+
+## Scorebug Detector
+
+The scorebug detector identifies the score overlay graphic in video frames using template matching.
+
+### Usage
+
+```python
+from src.detectors import ScorebugDetector
+
+# Initialize with a template
+detector = ScorebugDetector(template_path="data/templates/scorebug_template_main.png")
+
+# Detect scorebug in a frame
+detection = detector.detect(frame)
+
+if detection.detected:
+    print(f"Scorebug found with confidence {detection.confidence:.2f}")
+    print(f"Location: {detection.bbox}")
+```
+
+### Detection Result
+
+The `ScorebugDetection` dataclass contains:
+- `detected`: Whether scorebug was found
+- `confidence`: Match confidence (0.0 to 1.0)
+- `bbox`: Bounding box (x, y, width, height)
+- `method`: Detection method used
+
+## Test Data
+
+### Video Reference
+- **File**: `full_videos/OSU vs Tenn 12.21.24.mkv`
+- **Resolution**: 1920×1080 @ 59.94fps
+
+### Test Segments
+- **Quick test**: 38:40 - 41:40 (3 minutes, ~5 plays)
+- **Extended test**: 38:40 - 48:40 (10 minutes, ~12 plays)
+
+### Ground Truth
+- 12 manually annotated plays in the 10-minute segment
+- Average play duration: ~7 seconds
+
+## Development
+
+### Code Style
+- Use Black formatter with `line-length=180`
+- Add descriptive inline comments
+- Include logging for debugging
+
+```bash
+python -m black src/ --line-length=180
+```
+
+## License
+
+Private project - All rights reserved

pyproject.toml

@@ -0,0 +1,57 @@
+
+[project]
+name = "cfb40"
+version = "0.1.0"
+description = "Process to condense a college football game into a 40-ish minute highlight video."
+readme = "README.md"
+authors = [{ email = "andy.taylor@smg.com" }]
+requires-python = ">=3.13"
+dependencies = [
+    "opencv-python>=4.8.0",
+    "numpy>=1.24.0",
+    "pillow>=10.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "black>=24.0.0",
+]
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+ignore_missing_imports = true
+exclude = ["tests", "scripts", "examples", "static"]
+
+[tool.black]
+line-length = 180
+fast = true
+
+[tool.isort]
+profile = "black"
+
+[tool.pylint.FORMAT]
+ignore-long-lines = "^\\s*(# )?.*['\"]?<?https?://\\S+>?"
+indent-after-paren = 4
+max-line-length = 180
+max-args = 8
+max-positional-arguments = 8
+max-attributes = 15
+max-locals = 20
+
+[tool.pylint.BASIC]
+argument-naming-style = "snake_case"
+attr-naming-style = "snake_case"
+class-attribute-naming-style = "any"
+class-naming-style = "PascalCase"
+const-naming-style = "UPPER_CASE"
+docstring-min-length = -1
+function-naming-style = "snake_case"
+include-naming-hint = "yes"
+
+[tool.pylint.TYPECHECK]
+ignore-none = "yes"

src/detectors/__init__.py

@@ -0,0 +1,5 @@
+"""Detector modules for identifying game elements."""
+
+from .scorebug_detector import ScorebugDetector, ScorebugDetection, create_template_from_frame
+
+__all__ = ["ScorebugDetector", "ScorebugDetection", "create_template_from_frame"]

src/detectors/scorebug_detector.py

@@ -0,0 +1,212 @@
+"""
+Scorebug detector module.
+
+This module provides functions to detect the presence and location of the scorebug
+(score overlay) in video frames.
+"""
+
+import cv2
+import numpy as np
+import logging
+from typing import Optional, Tuple, Dict
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ScorebugDetection:
+    """Results from scorebug detection."""
+
+    detected: bool  # Whether scorebug was detected
+    confidence: float  # Confidence score (0.0 to 1.0)
+    bbox: Optional[Tuple[int, int, int, int]] = None  # Bounding box (x, y, width, height)
+    method: str = "unknown"  # Detection method used
+
+
+class ScorebugDetector:
+    """
+    Detects the scorebug in video frames.
+
+    The detector uses multiple strategies to identify the scorebug:
+    1. Template matching
+    2. Color-based detection
+    3. Position-based heuristics
+    """
+
+    def __init__(self, template_path: Optional[str] = None, expected_region: Optional[Tuple[int, int, int, int]] = None):
+        """
+        Initialize the scorebug detector.
+
+        Args:
+            template_path: Path to a template image of the scorebug (optional)
+            expected_region: Expected region where scorebug appears (x, y, w, h) (optional)
+        """
+        self.template = None
+        self.template_path = template_path
+        self.expected_region = expected_region
+
+        if template_path:
+            self.load_template(template_path)
+
+        logger.info(f"ScorebugDetector initialized (template: {template_path is not None}, region: {expected_region is not None})")
+
+    def load_template(self, template_path: str) -> None:
+        """
+        Load a template image for matching.
+
+        Args:
+            template_path: Path to the template image
+        """
+        self.template = cv2.imread(template_path)
+        if self.template is None:
+            raise ValueError(f"Could not load template image: {template_path}")
+
+        self.template_path = template_path
+        logger.info(f"Loaded template: {template_path} (size: {self.template.shape[1]}x{self.template.shape[0]})")
+
+    def detect(self, frame: np.ndarray) -> ScorebugDetection:
+        """
+        Detect scorebug in a frame.
+
+        Args:
+            frame: Input frame (BGR format)
+
+        Returns:
+            ScorebugDetection object with detection results
+        """
+        # Only use template matching - position alone is not sufficient
+        # The scorebug is NOT present during replays/timeouts even though
+        # the position may have other graphics
+
+        if self.template is not None:
+            detection = self._detect_by_template(frame)
+            if detection.detected:
+                logger.debug(f"Scorebug detected with confidence {detection.confidence:.2f} using {detection.method}")
+                return detection
+
+        # If template matching fails, scorebug is NOT present
+        logger.debug("No scorebug detected")
+        return ScorebugDetection(detected=False, confidence=0.0, method="none")
+
+    def _detect_by_template(self, frame: np.ndarray) -> ScorebugDetection:
+        """
+        Detect scorebug using template matching.
+
+        Args:
+            frame: Input frame
+
+        Returns:
+            Detection result
+        """
+        if self.template is None:
+            return ScorebugDetection(detected=False, confidence=0.0, method="template")
+
+        # Perform template matching
+        result = cv2.matchTemplate(frame, self.template, cv2.TM_CCOEFF_NORMED)
+        min_val, max_val, min_loc, max_loc = cv2.minMaxLoc(result)
+
+        # Use strict threshold - only detect when scorebug graphic is actually present
+        # Low matches indicate replays, timeouts, or other non-live-play moments
+        threshold = 0.8  # High threshold to avoid false positives
+
+        if max_val >= threshold:
+            # Get bounding box
+            h, w = self.template.shape[:2]
+            bbox = (max_loc[0], max_loc[1], w, h)
+
+            return ScorebugDetection(detected=True, confidence=float(max_val), bbox=bbox, method="template")
+        else:
+            return ScorebugDetection(detected=False, confidence=float(max_val), method="template")
+
+    def _detect_by_position(self, frame: np.ndarray) -> ScorebugDetection:
+        """
+        Detect scorebug by checking expected position.
+
+        This method assumes the scorebug is at a known location and verifies
+        that something is present there (e.g., by checking for non-zero content).
+
+        Args:
+            frame: Input frame
+
+        Returns:
+            Detection result
+        """
+        if self.expected_region is None:
+            return ScorebugDetection(detected=False, confidence=0.0, method="position")
+
+        x, y, w, h = self.expected_region
+
+        # Extract region
+        region = frame[y : y + h, x : x + w]
+
+        # TODO: Implement actual verification logic after analysis
+        # For now, just check if region is not completely black
+        mean_intensity = np.mean(region)
+
+        # Simple heuristic: if mean intensity is above threshold, assume scorebug is present
+        threshold = 30  # TODO: Tune this after analysis
+
+        if mean_intensity >= threshold:
+            confidence = min(mean_intensity / 255.0, 1.0)
+            return ScorebugDetection(detected=True, confidence=confidence, bbox=(x, y, w, h), method="position")
+        else:
+            return ScorebugDetection(detected=False, confidence=0.0, method="position")
+
+    def _detect_by_color(self, frame: np.ndarray) -> ScorebugDetection:
+        """
+        Detect scorebug by color characteristics.
+
+        This method looks for unique color patterns in the scorebug.
+
+        Args:
+            frame: Input frame
+
+        Returns:
+            Detection result
+
+        TODO: Implement after manual analysis identifies unique colors
+        """
+        # Placeholder for color-based detection
+        return ScorebugDetection(detected=False, confidence=0.0, method="color")
+
+    def visualize_detection(self, frame: np.ndarray, detection: ScorebugDetection) -> np.ndarray:
+        """
+        Draw detection results on frame for visualization.
+
+        Args:
+            frame: Input frame
+            detection: Detection result
+
+        Returns:
+            Frame with visualization overlay
+        """
+        vis_frame = frame.copy()
+
+        if detection.detected and detection.bbox:
+            x, y, w, h = detection.bbox
+
+            # Draw bounding box
+            color = (0, 255, 0)  # Green for detected
+            cv2.rectangle(vis_frame, (x, y), (x + w, y + h), color, 2)
+
+            # Add confidence text
+            text = f"{detection.method}: {detection.confidence:.2f}"
+            cv2.putText(vis_frame, text, (x, y - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.6, color, 2)
+
+        return vis_frame
+
+
+def create_template_from_frame(frame: np.ndarray, bbox: Tuple[int, int, int, int], output_path: str) -> None:
+    """
+    Extract a region from a frame to use as a template.
+
+    Args:
+        frame: Source frame
+        bbox: Bounding box (x, y, width, height)
+        output_path: Path to save the template image
+    """
+    x, y, w, h = bbox
+    template = frame[y : y + h, x : x + w]
+    cv2.imwrite(output_path, template)
+    logger.info(f"Created template: {output_path} (size: {w}x{h})")