refactoring ui dir

README.md

@@ -43,7 +43,10 @@ cfb40/
 ├── main.py                           # Minimal pipeline entry point
 ├── src/
 │   ├── ui/                           # User interface modules
-│   │   ├── region_selector.py        # Interactive region selection (OpenCV)
+│   │   ├── models.py                 # Pydantic models (BBox, SelectionState, etc.)
+│   │   ├── selector.py               # RegionSelector class for mouse callbacks
+│   │   ├── sessions.py               # Interactive selection session classes
+│   │   ├── api.py                    # Public API functions
 │   │   └── __init__.py
 │   ├── video/                        # Video processing modules
 │   │   ├── ffmpeg_ops.py             # FFmpeg clip extraction/concatenation
@@ -216,7 +219,8 @@ The codebase is organized into modular components under `src/`:
 
 ### Key Classes
 
-- **`RegionSelector`** (`ui/region_selector.py`) - Interactive region selection with two-click or drag modes
+- **`RegionSelector`** (`ui/selector.py`) - Interactive region selection with two-click or drag modes
+- **`BBox`** (`ui/models.py`) - Pydantic model for bounding box coordinates
 - **`SessionConfig`** (`config/session.py`) - Dataclass holding all session configuration
 - **`PlayDetector`** (`pipeline/play_detector.py`) - Main detection pipeline
 - **`PlayStateMachine`** (`detectors/play_state_machine.py`) - Play boundary detection logic

main.py

@@ -49,7 +49,7 @@ from ui import (
     select_timeout_region,
     get_video_path_from_user,
 )
-from ui.region_selector import extract_sample_frames_for_selection
+from ui.api import extract_sample_frames_for_selection
 from video import generate_clips
 from pipeline import run_detection, print_results_summary
 

src/detectors/scorebug_detector.py

@@ -126,6 +126,8 @@ class ScorebugDetector:
         Detect scorebug in a frame.
 
         Uses fixed-region mode if configured (much faster), otherwise searches entire frame.
+        If a fixed region is set but no template is loaded, assumes scorebug is present
+        at the fixed location (useful when coordinates come from user selection).
 
         Args:
             frame: Input frame (BGR format)
@@ -133,14 +135,22 @@ class ScorebugDetector:
         Returns:
             ScorebugDetection object with detection results
         """
-        if self.template is None:
-            logger.debug("No template loaded, cannot detect scorebug")
-            return ScorebugDetection(detected=False, confidence=0.0, method="none")
-
         # Use fixed-region mode if configured (much faster - only checks known location)
         if self._use_fixed_region and self.fixed_region is not None:
+            # If no template loaded, assume scorebug is present at fixed location
+            # This is used when coordinates are provided via fixed config (no verification needed)
+            if self.template is None:
+                x, y, w, h = self.fixed_region
+                logger.debug("Fixed region mode without template - assuming scorebug present at %s", self.fixed_region)
+                return ScorebugDetection(detected=True, confidence=1.0, bbox=(x, y, w, h), method="fixed_region_assumed")
+
             detection = self._detect_in_fixed_region(frame)
         else:
+            # Need template for full-frame search
+            if self.template is None:
+                logger.debug("No template loaded, cannot detect scorebug")
+                return ScorebugDetection(detected=False, confidence=0.0, method="none")
+
             # Full-frame template matching (slower, searches entire frame)
             detection = self._detect_by_template_fullsearch(frame)
 

src/pipeline/play_detector.py

@@ -26,7 +26,7 @@ import numpy as np
 from detectors import ScorebugDetector, ScorebugDetection, PlayClockReader, PlayStateMachine, PlayEvent, PlayClockReading, TimeoutTracker
 from detectors.play_clock_reader import _get_easyocr_reader
 from detectors.digit_template_reader import DigitTemplateBuilder, DigitTemplateLibrary, TemplatePlayClockReader
-from config.session import MIN_PLAY_DURATION
+from detectors.models import PlayClockRegionConfig
 from .models import DetectionConfig, FrameOCRTask, FrameTemplateTask, DetectionResult, VideoContext, Pass1Results
 
 logger = logging.getLogger(__name__)
@@ -95,7 +95,8 @@ class PlayDetector:
         if not video_path.exists():
             raise FileNotFoundError(f"Video not found: {self.config.video_path}")
 
-        # In fixed coordinates mode, scorebug template is not needed
+        # In fixed coordinates mode, template and clock config paths are not required
+        # since we derive the regions from the fixed coordinates
         if not self.config.fixed_playclock_coords:
             template_path = Path(self.config.template_path)
             if not template_path.exists():
@@ -109,17 +110,46 @@ class PlayDetector:
         """Initialize detection components."""
         logger.info("Initializing play detector components...")
 
-        # In fixed coordinates mode, skip scorebug detector (not needed)
-        if self.config.fixed_playclock_coords:
-            self.scorebug_detector = None
-            self.clock_reader = None
-            logger.info("Fixed coordinates mode - scorebug detection disabled")
+        # Determine if we're using fixed coordinates mode
+        # In this mode, we still use the same detection logic but with pre-set regions
+        use_fixed_coords = self.config.fixed_playclock_coords is not None
+
+        if use_fixed_coords:
+            # Fixed coordinates mode: derive play clock offset from absolute coords
+            # We still create scorebug_detector and clock_reader for unified processing
+            logger.info("Fixed coordinates mode - regions pre-configured")
+
+            # Compute play clock offset relative to scorebug from absolute coordinates
+            pc_x, pc_y, pc_w, pc_h = self.config.fixed_playclock_coords
+            if self.config.fixed_scorebug_coords:
+                sb_x, sb_y, _, _ = self.config.fixed_scorebug_coords
+                x_offset = pc_x - sb_x
+                y_offset = pc_y - sb_y
+            else:
+                # If no scorebug coords provided, treat play clock coords as offset from (0,0)
+                x_offset, y_offset = pc_x, pc_y
+
+            # Create a minimal PlayClockRegionConfig for the clock reader
+            playclock_config = PlayClockRegionConfig(x_offset=x_offset, y_offset=y_offset, width=pc_w, height=pc_h, source_video="", scorebug_template="", samples_used=0)
+
+            # Initialize scorebug detector (will set fixed region below)
+            # Use empty template path with a dummy - we'll set fixed region immediately
+            self.scorebug_detector = ScorebugDetector(template_path=None, use_split_detection=self.config.use_split_detection)
+
+            # Set the fixed region immediately so no template matching is needed
+            if self.config.fixed_scorebug_coords:
+                self.scorebug_detector.set_fixed_region(self.config.fixed_scorebug_coords)
+                logger.info("Scorebug fixed region set: %s", self.config.fixed_scorebug_coords)
+
+            # Initialize play clock reader with the derived config
+            self.clock_reader = PlayClockReader(region_config=playclock_config)
+            logger.info("Play clock reader initialized with offset=(%d, %d), size=(%d, %d)", x_offset, y_offset, pc_w, pc_h)
         else:
-            # Initialize scorebug detector with split detection setting
+            # Standard mode: use template and config files
             self.scorebug_detector = ScorebugDetector(template_path=self.config.template_path, use_split_detection=self.config.use_split_detection)
             logger.info("Scorebug detector initialized (split_detection=%s)", self.config.use_split_detection)
 
-            # Initialize play clock reader
+            # Initialize play clock reader from config file
             self.clock_reader = PlayClockReader(region_config_path=self.config.clock_region_config_path)
             logger.info("Play clock reader initialized")
 
@@ -129,11 +159,8 @@ class PlayDetector:
 
         # Initialize template matching components if enabled
         if self.config.use_template_matching:
-            # Determine region dimensions from fixed coords or clock reader config
-            if self.config.fixed_playclock_coords:
-                region_w = self.config.fixed_playclock_coords[2]  # width from fixed coords
-                region_h = self.config.fixed_playclock_coords[3]  # height from fixed coords
-            elif self.clock_reader and self.clock_reader.config:
+            # Determine region dimensions from clock reader config
+            if self.clock_reader and self.clock_reader.config:
                 region_w = self.clock_reader.config.width
                 region_h = self.clock_reader.config.height
             else:
@@ -149,8 +176,8 @@ class PlayDetector:
                     self.template_library = None
                     logger.info("Could not load templates, will build during detection")
 
-            # Initialize template builder for collection phase (not used in fixed coords mode)
-            if self.template_library is None and not self.config.fixed_playclock_coords:
+            # Initialize template builder for collection phase
+            if self.template_library is None:
                 self.template_builder = DigitTemplateBuilder(region_w, region_h)
                 logger.info("Template builder initialized for collection phase")
 
@@ -207,15 +234,18 @@ class PlayDetector:
 
         return context, stats, timing
 
-    def _pass1_extract_frames(self, context: VideoContext, stats: Dict[str, Any], timing: Dict[str, float], use_fixed_coords: bool) -> Pass1Results:
+    def _pass1_extract_frames(self, context: VideoContext, stats: Dict[str, Any], timing: Dict[str, float]) -> Pass1Results:
         """
         Pass 1: Read frames, detect scorebug, extract play clock regions.
 
+        This method uses the same logic whether coordinates were provided via
+        fixed_coords config or via user selection - the scorebug_detector handles
+        the difference via its fixed_region setting.
+
         Args:
             context: Video context with properties and capture object
             stats: Stats dictionary to update
             timing: Timing dictionary to update
-            use_fixed_coords: Whether to use fixed coordinates mode
 
         Returns:
             Pass1Results with frame results, OCR tasks, and template tasks
@@ -241,7 +271,8 @@ class PlayDetector:
         template_tasks: List[FrameTemplateTask] = []
 
         # Flag to track if we've locked the scorebug region
-        scorebug_region_locked = False
+        # If using fixed coordinates, the region is already locked in _initialize_components
+        scorebug_region_locked = self.scorebug_detector._use_fixed_region if self.scorebug_detector else False
 
         current_frame = context.start_frame
 
@@ -264,11 +295,8 @@ class PlayDetector:
 
             stats["total_frames"] += 1
 
-            # Fixed coordinates mode: skip scorebug detection entirely
-            if use_fixed_coords:
-                frame_result = self._process_frame_fixed_coords(frame, current_time, template_tasks, timing, stats)
-            else:
-                frame_result, scorebug_region_locked = self._process_frame_standard(frame, current_time, template_tasks, ocr_tasks, timing, stats, scorebug_region_locked)
+            # Process frame using standard method (handles both fixed and discovered regions)
+            frame_result, scorebug_region_locked = self._process_frame_standard(frame, current_time, template_tasks, ocr_tasks, timing, stats, scorebug_region_locked)
 
             frame_results.append(frame_result)
 
@@ -289,51 +317,6 @@ class PlayDetector:
 
         return Pass1Results(frame_results=frame_results, ocr_tasks=ocr_tasks, template_tasks=template_tasks)
 
-    def _process_frame_fixed_coords(
-        self,
-        frame: np.ndarray,
-        current_time: float,
-        template_tasks: List[FrameTemplateTask],
-        timing: Dict[str, float],
-        stats: Dict[str, Any],
-    ) -> Dict[str, Any]:
-        """
-        Process a single frame in fixed coordinates mode.
-
-        Args:
-            frame: The video frame
-            current_time: Current timestamp
-            template_tasks: List to append template tasks to
-            timing: Timing dictionary to update
-            stats: Stats dictionary to update
-
-        Returns:
-            Frame result dictionary
-        """
-        # Use fixed coordinates - no scorebug detection needed
-        scorebug_bbox = self.config.fixed_scorebug_coords or (0, 0, 0, 0)
-        frame_result = {
-            "timestamp": current_time,
-            "scorebug_detected": True,  # Always true in fixed mode
-            "scorebug_bbox": scorebug_bbox,
-            "home_timeouts": None,
-            "away_timeouts": None,
-        }
-        stats["frames_with_scorebug"] += 1
-
-        # Extract play clock region directly from fixed coordinates
-        t_start = time.perf_counter()
-        pc_x, pc_y, pc_w, pc_h = self.config.fixed_playclock_coords
-        play_clock_region = frame[pc_y : pc_y + pc_h, pc_x : pc_x + pc_w]
-
-        if play_clock_region is not None and play_clock_region.size > 0:
-            # Store raw region for template matching (fixed coords mode always uses templates)
-            template_tasks.append(FrameTemplateTask(timestamp=current_time, raw_region=play_clock_region.copy(), scorebug_bbox=scorebug_bbox))
-            frame_result["template_task_idx"] = len(template_tasks) - 1
-        timing["preprocessing"] += time.perf_counter() - t_start
-
-        return frame_result
-
     def _process_frame_standard(
         self,
         frame: np.ndarray,
@@ -680,225 +663,27 @@ class PlayDetector:
         logger.info("  TOTAL: %.2fs", total_time)
         logger.info("=" * 50)
 
-    # pylint: disable=too-many-locals,too-many-statements
-    def _detect_single_pass_fixed_coords(self) -> DetectionResult:
-        """
-        Optimized single-pass detection for fixed coordinates mode.
-
-        This is the FASTEST mode - no scorebug detection, template matching done inline.
-        Everything happens in a single pass through the video.
-        """
-        logger.info("Mode: FIXED COORDINATES - SINGLE PASS (fastest)")
-        logger.info("  Play clock coords: %s", self.config.fixed_playclock_coords)
-        if self.config.fixed_scorebug_coords:
-            logger.info("  Scorebug coords: %s", self.config.fixed_scorebug_coords)
-
-        # Open video
-        cap = cv2.VideoCapture(self.config.video_path)
-        if not cap.isOpened():
-            raise RuntimeError(f"Could not open video: {self.config.video_path}")
-
-        # Get video properties
-        fps = cap.get(cv2.CAP_PROP_FPS)
-        total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
-        duration = total_frames / fps if fps > 0 else 0
-        logger.info("Video: %.1fs duration, %.2f fps, %d total frames", duration, fps, total_frames)
-
-        # Determine segment bounds
-        start_time = self.config.start_time
-        end_time = self.config.end_time if self.config.end_time else duration
-
-        # Stats and timing
-        stats = {"total_frames": 0, "frames_with_scorebug": 0, "frames_with_clock": 0}
-        timing = {"video_io": 0.0, "template_matching": 0.0, "state_machine": 0.0}
-
-        # Frame navigation
-        frame_skip = int(self.config.frame_interval * fps)
-        start_frame = int(start_time * fps)
-        end_frame = int(end_time * fps)
-
-        t_io_start = time.perf_counter()
-        cap.set(cv2.CAP_PROP_POS_FRAMES, start_frame)
-        timing["video_io"] += time.perf_counter() - t_io_start
-
-        current_frame = start_frame
-        logger.info("Single-pass: frame_skip=%d (%.2f fps effective), frames %d-%d", frame_skip, fps / frame_skip, start_frame, end_frame)
-
-        # Fixed coordinates
-        pc_x, pc_y, pc_w, pc_h = self.config.fixed_playclock_coords
-        scorebug_bbox = self.config.fixed_scorebug_coords or (0, 0, 0, 0)
-
-        # Dummy scorebug detection (always detected in fixed mode)
-        dummy_scorebug = ScorebugDetection(detected=True, bbox=scorebug_bbox, confidence=1.0, method="fixed")
-
-        # Collect frame data for clock reset detection
-        frame_data_for_clock_reset: List[Dict[str, Any]] = []
-
-        # === SINGLE PASS: Read, extract, match, update ===
-        logger.info("Processing frames (single pass)...")
-        process_start = time.perf_counter()
-
-        while current_frame < end_frame:
-            current_time = current_frame / fps
-
-            # Read frame
-            t_io = time.perf_counter()
-            ret, frame = cap.read()
-            timing["video_io"] += time.perf_counter() - t_io
-
-            if not ret:
-                # Skip frames and continue
-                t_io = time.perf_counter()
-                for _ in range(frame_skip - 1):
-                    cap.grab()
-                timing["video_io"] += time.perf_counter() - t_io
-                current_frame += frame_skip
-                continue
-
-            stats["total_frames"] += 1
-            stats["frames_with_scorebug"] += 1  # Always true in fixed mode
-
-            # Extract play clock region directly
-            play_clock_region = frame[pc_y : pc_y + pc_h, pc_x : pc_x + pc_w]
-
-            # Template matching
-            t_match = time.perf_counter()
-            clock_reading = self.template_reader.read(play_clock_region)
-            timing["template_matching"] += time.perf_counter() - t_match
-
-            # Create PlayClockReading for state machine
-            if clock_reading.detected and clock_reading.value is not None:
-                stats["frames_with_clock"] += 1
-                clock = PlayClockReading(
-                    detected=True,
-                    value=clock_reading.value,
-                    confidence=clock_reading.confidence,
-                    raw_text=str(clock_reading.value),
-                )
-            else:
-                clock = PlayClockReading(detected=False, value=None, confidence=0.0, raw_text="")
-
-            # Update state machine
-            t_sm = time.perf_counter()
-            self.state_machine.update(current_time, dummy_scorebug, clock)
-            timing["state_machine"] += time.perf_counter() - t_sm
-
-            # Store frame data for clock reset detection
-            frame_data_for_clock_reset.append(
-                {
-                    "timestamp": current_time,
-                    "scorebug_detected": True,
-                    "scorebug_bbox": scorebug_bbox,
-                    "clock_detected": clock.detected,
-                    "clock_value": clock.value,
-                    "home_timeouts": None,
-                    "away_timeouts": None,
-                }
-            )
-
-            # Progress logging every 5 minutes of video
-            if stats["total_frames"] % int(300 / self.config.frame_interval) == 0:
-                elapsed = time.perf_counter() - process_start
-                pct = 100 * (current_time - start_time) / (end_time - start_time) if end_time > start_time else 0
-                frames_per_sec = stats["total_frames"] / elapsed if elapsed > 0 else 0
-                eta = (end_time - current_time) / (current_time - start_time) * elapsed if current_time > start_time else 0
-                logger.info(
-                    "Progress: %.1f%% (%d:%02d / %d:%02d) - %.1f fps - ETA: %.0fs",
-                    pct,
-                    int(current_time // 60),
-                    int(current_time % 60),
-                    int(end_time // 60),
-                    int(end_time % 60),
-                    frames_per_sec,
-                    eta,
-                )
-
-            # Skip frames
-            t_io = time.perf_counter()
-            for _ in range(frame_skip - 1):
-                cap.grab()
-            timing["video_io"] += time.perf_counter() - t_io
-            current_frame += frame_skip
-
-        cap.release()
-
-        logger.info("Single pass complete: %d frames processed", stats["total_frames"])
-        logger.info("Clock readings: %d (%.1f%%)", stats["frames_with_clock"], 100 * stats["frames_with_clock"] / max(1, stats["total_frames"]))
-
-        # Clock reset detection pass (detect 40->25 transitions)
-        logger.info("Running clock reset detection...")
-        clock_reset_plays, clock_reset_stats = self._detect_clock_resets(frame_data_for_clock_reset)
-        logger.info(
-            "Clock reset detection: %d total, %d weird (rejected), %d timeouts, %d special plays",
-            clock_reset_stats.get("total", 0),
-            clock_reset_stats.get("weird_clock", 0),
-            clock_reset_stats.get("timeout", 0),
-            clock_reset_stats.get("special", 0),
-        )
-
-        # Get state machine plays and merge with clock reset plays
-        state_machine_plays = self.state_machine.get_plays()
-        play_stats = self.state_machine.get_stats()
-        play_stats["clock_reset_events"] = clock_reset_stats
-
-        plays = self._merge_plays(state_machine_plays, clock_reset_plays)
-
-        # Apply minimum duration filter (only to normal plays, not special/timeout)
-        # Special plays and timeouts can have short durations due to sampling interval
-        original_count = len(plays)
-        plays = [p for p in plays if p.play_type in ("special", "timeout") or (p.end_time - p.start_time) >= MIN_PLAY_DURATION]
-        filtered_count = original_count - len(plays)
-        if filtered_count > 0:
-            logger.info("Filtered out %d normal plays with duration < %.1fs", filtered_count, MIN_PLAY_DURATION)
-
-        # Build result
-        result = DetectionResult(
-            video=Path(self.config.video_path).name,
-            segment_start=start_time,
-            segment_end=end_time,
-            total_frames_processed=stats["total_frames"],
-            frames_with_scorebug=stats["frames_with_scorebug"],
-            frames_with_clock=stats["frames_with_clock"],
-            plays=[self._play_to_dict(p) for p in plays],
-            stats=play_stats,
-            timing=timing,
-        )
-
-        total_time = sum(timing.values())
-        logger.info("=" * 50)
-        logger.info("TIMING BREAKDOWN (Single Pass)")
-        logger.info("=" * 50)
-        for section, t_duration in timing.items():
-            pct = 100 * t_duration / total_time if total_time > 0 else 0
-            logger.info("  %s: %.2fs (%.1f%%)", section, t_duration, pct)
-        logger.info("  TOTAL: %.2fs (%.1f minutes)", total_time, total_time / 60)
-        logger.info("=" * 50)
-
-        logger.info("Detection complete!")
-        logger.info("Plays detected: %d", len(plays))
-
-        return result
-
     def detect(self) -> DetectionResult:
         """
         Run play detection on the video segment.
 
-        Supports three modes:
-        1. FIXED COORDINATES mode (fastest - single pass):
-           - Single pass: Read frame, extract region, template match, state machine update
-           - No scorebug detection needed
+        Uses a unified multi-pass architecture regardless of how coordinates were obtained
+        (either from fixed coordinates config or via user selection):
 
-        2. Template matching mode (use_template_matching=True, ~34x faster than OCR):
-           - Pass 1: Read frames, detect scorebug, store raw regions
+        1. Template matching mode (use_template_matching=True, ~34x faster than OCR):
+           - Pass 1: Read frames, detect/verify scorebug, store raw regions
            - Pass 1.5 (if no templates): Run OCR on first N frames to build templates
            - Pass 2: Run template matching on all frames
            - Pass 3: Process results through state machine
 
-        3. OCR mode (use_template_matching=False):
-           - Pass 1: Read frames, detect scorebug, preprocess OCR images
+        2. OCR mode (use_template_matching=False):
+           - Pass 1: Read frames, detect/verify scorebug, preprocess OCR images
            - Pass 2: Run OCR in parallel using thread pool
            - Pass 3: Process results through state machine
 
+        When fixed coordinates are provided, the scorebug detection step simply verifies
+        the scorebug is present at the known location (faster than searching).
+
         Returns:
             DetectionResult with all detected plays
         """
@@ -906,14 +691,8 @@ class PlayDetector:
         logger.info("Video: %s", self.config.video_path)
         logger.info("Segment: %.1fs to %s", self.config.start_time, self.config.end_time or "end")
 
-        # Check for fixed coordinates mode (fastest - single pass, no scorebug detection)
-        use_fixed_coords = self.config.fixed_playclock_coords is not None
-        if use_fixed_coords and self.template_reader:
-            # Use optimized single-pass detection
-            return self._detect_single_pass_fixed_coords()
-
-        # Log mode info for multi-pass detection
-        self._log_detection_mode(use_fixed_coords)
+        # Log mode info
+        self._log_detection_mode()
 
         # Initialize video and get processing context
         context, stats, timing = self._open_video_and_get_context()
@@ -924,8 +703,8 @@ class PlayDetector:
                 logger.info("Pre-warming EasyOCR reader...")
                 _get_easyocr_reader()
 
-        # Pass 1: Frame extraction and preprocessing
-        pass1_results = self._pass1_extract_frames(context, stats, timing, use_fixed_coords)
+        # Pass 1: Frame extraction and preprocessing (unified for both fixed coords and user selection)
+        pass1_results = self._pass1_extract_frames(context, stats, timing)
 
         # Pass 1.5: Build templates if needed
         self._pass15_build_templates(pass1_results, timing)
@@ -939,21 +718,25 @@ class PlayDetector:
         # Pass 4: Clock reset classification and result building
         return self._pass4_clock_reset_and_build_result(frame_results, ocr_results, context, stats, timing)
 
-    def _log_detection_mode(self, use_fixed_coords: bool) -> None:
+    def _log_detection_mode(self) -> None:
         """Log the detection mode being used."""
-        if use_fixed_coords:
-            logger.info("Mode: FIXED COORDINATES (fastest - no scorebug detection)")
-            logger.info("  Play clock coords: %s", self.config.fixed_playclock_coords)
-            if self.config.fixed_scorebug_coords:
-                logger.info("  Scorebug coords: %s", self.config.fixed_scorebug_coords)
-        elif self.config.use_template_matching:
-            logger.info("Mode: Template matching (34x faster than OCR)")
+        use_fixed_region = self.scorebug_detector and self.scorebug_detector._use_fixed_region
+
+        if use_fixed_region:
+            logger.info("Mode: Fixed region (scorebug location pre-configured)")
+            if self.scorebug_detector.fixed_region:
+                logger.info("  Scorebug region: %s", self.scorebug_detector.fixed_region)
+        else:
+            logger.info("Mode: Dynamic scorebug detection (will discover and lock region)")
+
+        if self.config.use_template_matching:
+            logger.info("Clock reading: Template matching (34x faster than OCR)")
             if self.template_reader:
                 logger.info("  Using pre-built templates")
             else:
                 logger.info("  Will build templates from first %d frames", self.config.template_collection_frames)
         else:
-            logger.info("Mode: OCR (parallel=%s, workers=%d)", self.config.parallel_ocr, self.config.ocr_workers)
+            logger.info("Clock reading: OCR (parallel=%s, workers=%d)", self.config.parallel_ocr, self.config.ocr_workers)
 
     def _run_parallel_ocr(self, tasks: List[FrameOCRTask]) -> List[PlayClockReading]:
         """

src/ui/__init__.py

@@ -1,19 +1,52 @@
-"""UI modules for interactive user input and region selection."""
+"""
+UI module for interactive region selection.
 
-from .region_selector import (
-    RegionSelector,
-    select_scorebug_region,
-    select_playclock_region,
-    select_timeout_region,
+This module provides tools for interactively selecting regions in video frames,
+including scorebug, play clock, and timeout indicator regions.
+"""
+
+# Models
+from .models import BBox, SelectionState, SelectionViewConfig
+
+# Selector
+from .selector import KeyHandler, RegionSelector
+
+# Sessions
+from .sessions import (
+    InteractiveSelectionSession,
+    PlayClockSelectionSession,
+    ScorebugSelectionSession,
+    TimeoutSelectionSession,
+)
+
+# Public API
+from .api import (
+    extract_sample_frames_for_selection,
     get_video_path_from_user,
     print_banner,
+    select_playclock_region,
+    select_scorebug_region,
+    select_timeout_region,
 )
 
 __all__ = [
+    # Models
+    "BBox",
+    "SelectionState",
+    "SelectionViewConfig",
+    # Selector
+    "KeyHandler",
     "RegionSelector",
-    "select_scorebug_region",
-    "select_playclock_region",
-    "select_timeout_region",
+    # Sessions
+    "InteractiveSelectionSession",
+    "PlayClockSelectionSession",
+    "ScorebugSelectionSession",
+    "TimeoutSelectionSession",
+    # Public API
+    "extract_sample_frames_for_selection",
     "get_video_path_from_user",
     "print_banner",
+    "select_playclock_region",
+    "select_scorebug_region",
+    "select_timeout_region",
 ]

src/ui/api.py

@@ -0,0 +1,189 @@
+"""
+Public API functions for the UI module.
+
+This module provides the high-level functions for interactive region selection
+that are intended to be called by external code.
+"""
+
+import logging
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+import numpy as np
+
+from video.frame_extractor import extract_sample_frames
+
+from .models import BBox
+from .sessions import PlayClockSelectionSession, ScorebugSelectionSession, TimeoutSelectionSession
+
+logger = logging.getLogger(__name__)
+
+
+def print_banner():
+    """Print the welcome banner for CFB40."""
+    print("\n" + "=" * 60)
+    print("   CFB40 - College Football Play Detection Pipeline")
+    print("=" * 60 + "\n")
+
+
+def extract_sample_frames_for_selection(video_path: str, start_time: float, num_frames: int = 5, interval: float = 2.0) -> List[Tuple[float, np.ndarray]]:
+    """Extract sample frames from the video for region selection."""
+    return extract_sample_frames(video_path, start_time, num_frames, interval)
+
+
+def select_scorebug_region(frames: List[Tuple[float, np.ndarray]], video_path: str = None) -> Tuple[Optional[Tuple[int, int, int, int]], Optional[Tuple[float, np.ndarray]]]:
+    """
+    Interactive selection of scorebug region.
+
+    Args:
+        frames: List of (timestamp, frame) tuples to choose from.
+        video_path: Path to video file (for loading additional frames if needed).
+
+    Returns:
+        Tuple of (scorebug_bbox, selected_frame) where:
+        - scorebug_bbox: (x, y, width, height) or None if cancelled
+        - selected_frame: The specific (timestamp, frame) tuple that was selected
+    """
+    if not frames:
+        logger.error("No frames provided for selection")
+        return None, None
+
+    print("\n[Phase 2] Region Setup - Scorebug Selection")
+    print("-" * 50)
+    print("Instructions:")
+    print("  1. Click on the TOP-LEFT corner of the scorebug")
+    print("  2. Click on the BOTTOM-RIGHT corner of the scorebug")
+    print("  'n' = next frame, 'p' = previous frame")
+    print("  's' = skip forward 30s, 'S' = skip forward 5min")
+    print("  'r' = reset selection, 'q' = quit")
+    print("-" * 50)
+
+    session = ScorebugSelectionSession(frames, video_path)
+    bbox = session.run()
+
+    if bbox is None:
+        return None, None
+
+    selected_frame = session.state.current_frame
+    logger.info("Selected frame %d/%d @ %.1fs for scorebug region", session.state.frame_idx + 1, len(session.state.frames), selected_frame[0])
+
+    return bbox.to_tuple(), selected_frame
+
+
+def select_playclock_region(selected_frame: Tuple[float, np.ndarray], scorebug_bbox: Tuple[int, int, int, int]) -> Optional[Tuple[int, int, int, int]]:
+    """
+    Interactive selection of play clock region within the scorebug.
+
+    Args:
+        selected_frame: The (timestamp, frame) tuple selected during scorebug selection.
+        scorebug_bbox: Scorebug bounding box (x, y, width, height).
+
+    Returns:
+        Play clock region as (x_offset, y_offset, width, height) relative to scorebug,
+        or None if cancelled.
+    """
+    if selected_frame is None:
+        logger.error("No frame provided for selection")
+        return None
+
+    timestamp, frame = selected_frame
+    sb_bbox = BBox.from_tuple(scorebug_bbox)
+
+    print("\n[Phase 2] Region Setup - Play Clock Selection")
+    print("-" * 50)
+    print("Instructions:")
+    print("  1. Click on the TOP-LEFT corner of the play clock digits")
+    print("  2. Click on the BOTTOM-RIGHT corner of the play clock digits")
+    print("  Press 'r' to reset, 'q' to quit")
+    print("-" * 50)
+
+    logger.info("Using frame @ %.1fs for play clock selection (same as scorebug selection)", timestamp)
+
+    session = PlayClockSelectionSession(frame, sb_bbox, scale_factor=3)
+    bbox = session.get_unscaled_bbox() if session.run() else None
+
+    return bbox.to_tuple() if bbox else None
+
+
+def select_timeout_region(selected_frame: Tuple[float, np.ndarray], scorebug_bbox: Tuple[int, int, int, int], team: str) -> Optional[Tuple[int, int, int, int]]:
+    """
+    Interactive selection of timeout indicator region for a team.
+
+    Args:
+        selected_frame: The (timestamp, frame) tuple selected during scorebug selection.
+        scorebug_bbox: Scorebug bounding box (x, y, width, height).
+        team: "home" or "away".
+
+    Returns:
+        Timeout region as (x, y, width, height) in absolute frame coordinates,
+        or None if cancelled.
+    """
+    if selected_frame is None:
+        logger.error("No frame provided for selection")
+        return None
+
+    timestamp, frame = selected_frame
+    sb_bbox = BBox.from_tuple(scorebug_bbox)
+
+    print(f"\n[Phase 2] Region Setup - {team.upper()} Team Timeout Selection")
+    print("-" * 50)
+    print("Instructions:")
+    print(f"  Select the 3 timeout indicator ovals for the {team.upper()} team")
+    print("  (They are vertically stacked - white = available, dark = used)")
+    print("  1. Click on the TOP-LEFT corner of the timeout region")
+    print("  2. Click on the BOTTOM-RIGHT corner of the timeout region")
+    print("  Press 'r' to reset, 'q' to quit")
+    print("-" * 50)
+
+    logger.info("Using frame @ %.1fs for %s timeout selection", timestamp, team)
+
+    session = TimeoutSelectionSession(frame, sb_bbox, team, scale_factor=3, padding=50)
+    session.run()
+    bbox = session.get_absolute_bbox()
+
+    return bbox.to_tuple() if bbox else None
+
+
+def get_video_path_from_user(project_root: Path) -> Optional[str]:
+    """
+    Prompt user to enter video file path.
+
+    Args:
+        project_root: Root directory of the project.
+
+    Returns:
+        Path to selected video file, or None if no valid selection.
+    """
+    print("\nAvailable videos in full_videos/:")
+    videos_dir = project_root / "full_videos"
+    videos = []
+    if videos_dir.exists():
+        videos = list(videos_dir.glob("*.mp4")) + list(videos_dir.glob("*.mkv"))
+        for i, v in enumerate(videos, 1):
+            print(f"  {i}. {v.name}")
+
+    print("\nEnter video path (or number from list above):")
+    user_input = input("> ").strip()
+
+    if not user_input:
+        return None
+
+    # Check if user entered a number
+    try:
+        idx = int(user_input) - 1
+        if 0 <= idx < len(videos):
+            return str(videos[idx])
+    except ValueError:
+        pass
+
+    # Check if it's a valid path
+    if Path(user_input).exists():
+        return user_input
+
+    # Check if it's relative to full_videos
+    relative_path = videos_dir / user_input
+    if relative_path.exists():
+        return str(relative_path)
+
+    logger.error("Video not found: %s", user_input)
+    return None

src/ui/models.py

@@ -0,0 +1,96 @@
+"""
+Pydantic models and data structures for the UI module.
+
+This module contains all the data models used for region selection,
+including bounding boxes, view configurations, and selection state.
+"""
+
+from typing import List, Optional, Tuple
+
+import numpy as np
+from pydantic import BaseModel, ConfigDict
+
+
+class BBox(BaseModel):
+    """Bounding box with x, y, width, height coordinates."""
+
+    x: int
+    y: int
+    width: int
+    height: int
+
+    @property
+    def x2(self) -> int:
+        """Get the right edge x coordinate."""
+        return self.x + self.width
+
+    @property
+    def y2(self) -> int:
+        """Get the bottom edge y coordinate."""
+        return self.y + self.height
+
+    def to_tuple(self) -> Tuple[int, int, int, int]:
+        """Convert to (x, y, width, height) tuple."""
+        return (self.x, self.y, self.width, self.height)
+
+    def scaled(self, factor: int) -> "BBox":
+        """Return a new BBox scaled by the given factor."""
+        return BBox(x=self.x * factor, y=self.y * factor, width=self.width * factor, height=self.height * factor)
+
+    def unscaled(self, factor: int) -> "BBox":
+        """Return a new BBox divided by the given scale factor."""
+        return BBox(x=self.x // factor, y=self.y // factor, width=self.width // factor, height=self.height // factor)
+
+    def offset(self, dx: int, dy: int) -> "BBox":
+        """Return a new BBox offset by dx, dy."""
+        return BBox(x=self.x + dx, y=self.y + dy, width=self.width, height=self.height)
+
+    @classmethod
+    def from_points(cls, p1: Tuple[int, int], p2: Tuple[int, int]) -> "BBox":
+        """Create BBox from two corner points."""
+        x = min(p1[0], p2[0])
+        y = min(p1[1], p2[1])
+        w = abs(p2[0] - p1[0])
+        h = abs(p2[1] - p1[1])
+        return cls(x=x, y=y, width=w, height=h)
+
+    @classmethod
+    def from_tuple(cls, t: Tuple[int, int, int, int]) -> "BBox":
+        """Create BBox from (x, y, width, height) tuple."""
+        return cls(x=t[0], y=t[1], width=t[2], height=t[3])
+
+
+class SelectionViewConfig(BaseModel):
+    """Configuration for display/view settings during selection."""
+
+    scale_factor: int = 1
+    padding: int = 0
+    window_width: int = 1280
+    window_height: int = 720
+
+
+class SelectionState(BaseModel):
+    """Mutable state for a region selection session."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    frame_idx: int = 0
+    frames: List[Tuple[float, np.ndarray]] = []
+    should_quit: bool = False
+    should_confirm: bool = False
+    video_path: Optional[str] = None
+
+    @property
+    def current_frame(self) -> Tuple[float, np.ndarray]:
+        """Get the current (timestamp, frame) tuple."""
+        return self.frames[self.frame_idx]
+
+    @property
+    def timestamp(self) -> float:
+        """Get the current frame timestamp."""
+        return self.frames[self.frame_idx][0]
+
+    @property
+    def frame(self) -> np.ndarray:
+        """Get the current frame."""
+        return self.frames[self.frame_idx][1]

src/ui/selector.py

@@ -0,0 +1,89 @@
+"""
+Mouse-based region selector using OpenCV callbacks.
+
+This module provides the low-level RegionSelector class that handles
+mouse events for interactive region selection.
+"""
+
+from typing import Callable, List, Optional, Tuple
+
+import cv2
+
+from .models import BBox, SelectionState
+
+
+# Type alias for key handler functions
+KeyHandler = Callable[[SelectionState, "RegionSelector"], None]
+
+
+class RegionSelector:
+    """
+    Interactive region selector using OpenCV mouse callbacks.
+
+    Supports two selection modes:
+    - Two-click selection: click top-left, then click bottom-right
+    - Click-and-drag selection: click, drag, and release
+    """
+
+    def __init__(self, window_name: str, mode: str = "two_click"):
+        """Initialize the region selector."""
+        self.window_name = window_name
+        self.mode = mode
+
+        # Two-click mode state
+        self.points: List[Tuple[int, int]] = []
+        self.current_point: Optional[Tuple[int, int]] = None
+
+        # Drag mode state
+        self.start_point: Optional[Tuple[int, int]] = None
+        self.end_point: Optional[Tuple[int, int]] = None
+        self.drawing = False
+
+        self.selection_complete = False
+
+    def mouse_callback(self, event, x, y, flags, param):  # pylint: disable=unused-argument
+        """Handle mouse events for region selection."""
+        if self.mode == "two_click":
+            if event == cv2.EVENT_MOUSEMOVE:
+                self.current_point = (x, y)
+            elif event == cv2.EVENT_LBUTTONDOWN:
+                self.points.append((x, y))
+                if len(self.points) >= 2:
+                    self.selection_complete = True
+        else:
+            if event == cv2.EVENT_LBUTTONDOWN:
+                self.start_point = (x, y)
+                self.end_point = (x, y)
+                self.drawing = True
+                self.selection_complete = False
+            elif event == cv2.EVENT_MOUSEMOVE and self.drawing:
+                self.end_point = (x, y)
+            elif event == cv2.EVENT_LBUTTONUP:
+                self.end_point = (x, y)
+                self.drawing = False
+                self.selection_complete = True
+
+    def get_bbox(self) -> Optional[BBox]:
+        """Get the selected bounding box."""
+        if self.mode == "two_click":
+            if len(self.points) < 2:
+                return None
+            p1, p2 = self.points[0], self.points[1]
+        else:
+            if self.start_point is None or self.end_point is None:
+                return None
+            p1, p2 = self.start_point, self.end_point
+
+        bbox = BBox.from_points(p1, p2)
+        if bbox.width == 0 or bbox.height == 0:
+            return None
+        return bbox
+
+    def reset(self):
+        """Reset the selection state."""
+        self.points = []
+        self.current_point = None
+        self.start_point = None
+        self.end_point = None
+        self.drawing = False
+        self.selection_complete = False

src/ui/{region_selector.py → sessions.py}

@@ -1,207 +1,26 @@
 """
-Interactive region selection tools using OpenCV.
+Interactive selection session classes.
 
-This module provides classes and functions for interactive selection of regions
-within video frames, including scorebug, play clock, and timeout indicator regions.
+This module provides session classes for different types of region selection:
+- ScorebugSelectionSession: For selecting the main scorebug region
+- PlayClockSelectionSession: For selecting the play clock within scorebug
+- TimeoutSelectionSession: For selecting timeout indicator regions
 """
 
-import logging
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Callable, Dict, List, Optional, Tuple
+from typing import Dict, List, Optional, Tuple
 
 import cv2
 import numpy as np
-from pydantic import BaseModel
 
-from video.frame_extractor import extract_sample_frames
+from .models import BBox, SelectionState, SelectionViewConfig
+from .selector import KeyHandler, RegionSelector
 
-logger = logging.getLogger(__name__)
 
+def _extract_sample_frames_for_selection(video_path: str, start_time: float, num_frames: int = 5, interval: float = 2.0) -> List[Tuple[float, np.ndarray]]:
+    """Extract sample frames - import here to avoid circular imports."""
+    from video.frame_extractor import extract_sample_frames  # pylint: disable=import-outside-toplevel
 
-# =============================================================================
-# Pydantic Models for Region Coordinates
-# =============================================================================
-
-
-class BBox(BaseModel):
-    """Bounding box with x, y, width, height coordinates."""
-
-    x: int
-    y: int
-    width: int
-    height: int
-
-    @property
-    def x2(self) -> int:
-        """Get the right edge x coordinate."""
-        return self.x + self.width
-
-    @property
-    def y2(self) -> int:
-        """Get the bottom edge y coordinate."""
-        return self.y + self.height
-
-    def to_tuple(self) -> Tuple[int, int, int, int]:
-        """Convert to (x, y, width, height) tuple."""
-        return (self.x, self.y, self.width, self.height)
-
-    def scaled(self, factor: int) -> "BBox":
-        """Return a new BBox scaled by the given factor."""
-        return BBox(x=self.x * factor, y=self.y * factor, width=self.width * factor, height=self.height * factor)
-
-    def unscaled(self, factor: int) -> "BBox":
-        """Return a new BBox divided by the given scale factor."""
-        return BBox(x=self.x // factor, y=self.y // factor, width=self.width // factor, height=self.height // factor)
-
-    def offset(self, dx: int, dy: int) -> "BBox":
-        """Return a new BBox offset by dx, dy."""
-        return BBox(x=self.x + dx, y=self.y + dy, width=self.width, height=self.height)
-
-    @classmethod
-    def from_points(cls, p1: Tuple[int, int], p2: Tuple[int, int]) -> "BBox":
-        """Create BBox from two corner points."""
-        x = min(p1[0], p2[0])
-        y = min(p1[1], p2[1])
-        w = abs(p2[0] - p1[0])
-        h = abs(p2[1] - p1[1])
-        return cls(x=x, y=y, width=w, height=h)
-
-    @classmethod
-    def from_tuple(cls, t: Tuple[int, int, int, int]) -> "BBox":
-        """Create BBox from (x, y, width, height) tuple."""
-        return cls(x=t[0], y=t[1], width=t[2], height=t[3])
-
-
-class SelectionViewConfig(BaseModel):
-    """Configuration for display/view settings during selection."""
-
-    scale_factor: int = 1
-    padding: int = 0
-    window_width: int = 1280
-    window_height: int = 720
-
-
-# =============================================================================
-# Selection State Container
-# =============================================================================
-
-
-@dataclass
-class SelectionState:
-    """Mutable state for a region selection session."""
-
-    frame_idx: int = 0
-    frames: List[Tuple[float, np.ndarray]] = field(default_factory=list)
-    should_quit: bool = False
-    should_confirm: bool = False
-    video_path: Optional[str] = None
-
-    @property
-    def current_frame(self) -> Tuple[float, np.ndarray]:
-        """Get the current (timestamp, frame) tuple."""
-        return self.frames[self.frame_idx]
-
-    @property
-    def timestamp(self) -> float:
-        """Get the current frame timestamp."""
-        return self.frames[self.frame_idx][0]
-
-    @property
-    def frame(self) -> np.ndarray:
-        """Get the current frame."""
-        return self.frames[self.frame_idx][1]
-
-
-# =============================================================================
-# Mouse-based Region Selector
-# =============================================================================
-
-
-class RegionSelector:
-    """
-    Interactive region selector using OpenCV mouse callbacks.
-
-    Supports two selection modes:
-    - Two-click selection: click top-left, then click bottom-right
-    - Click-and-drag selection: click, drag, and release
-    """
-
-    def __init__(self, window_name: str, mode: str = "two_click"):
-        """Initialize the region selector."""
-        self.window_name = window_name
-        self.mode = mode
-
-        # Two-click mode state
-        self.points: List[Tuple[int, int]] = []
-        self.current_point: Optional[Tuple[int, int]] = None
-
-        # Drag mode state
-        self.start_point: Optional[Tuple[int, int]] = None
-        self.end_point: Optional[Tuple[int, int]] = None
-        self.drawing = False
-
-        self.selection_complete = False
-
-    def mouse_callback(self, event, x, y, flags, param):  # pylint: disable=unused-argument
-        """Handle mouse events for region selection."""
-        if self.mode == "two_click":
-            if event == cv2.EVENT_MOUSEMOVE:
-                self.current_point = (x, y)
-            elif event == cv2.EVENT_LBUTTONDOWN:
-                self.points.append((x, y))
-                if len(self.points) >= 2:
-                    self.selection_complete = True
-        else:
-            if event == cv2.EVENT_LBUTTONDOWN:
-                self.start_point = (x, y)
-                self.end_point = (x, y)
-                self.drawing = True
-                self.selection_complete = False
-            elif event == cv2.EVENT_MOUSEMOVE and self.drawing:
-                self.end_point = (x, y)
-            elif event == cv2.EVENT_LBUTTONUP:
-                self.end_point = (x, y)
-                self.drawing = False
-                self.selection_complete = True
-
-    def get_bbox(self) -> Optional[BBox]:
-        """Get the selected bounding box."""
-        if self.mode == "two_click":
-            if len(self.points) < 2:
-                return None
-            p1, p2 = self.points[0], self.points[1]
-        else:
-            if self.start_point is None or self.end_point is None:
-                return None
-            p1, p2 = self.start_point, self.end_point
-
-        bbox = BBox.from_points(p1, p2)
-        if bbox.width == 0 or bbox.height == 0:
-            return None
-        return bbox
-
-    def reset(self):
-        """Reset the selection state."""
-        self.points = []
-        self.current_point = None
-        self.start_point = None
-        self.end_point = None
-        self.drawing = False
-        self.selection_complete = False
-
-
-# =============================================================================
-# Key Handler Type
-# =============================================================================
-
-# Type alias for key handler functions
-KeyHandler = Callable[[SelectionState, RegionSelector], None]
-
-
-# =============================================================================
-# Interactive Selection Session
-# =============================================================================
+    return extract_sample_frames(video_path, start_time, num_frames, interval)
 
 
 class InteractiveSelectionSession:
@@ -269,7 +88,7 @@ class InteractiveSelectionSession:
         last_ts = state.frames[-1][0]
         new_start = last_ts + 30
         print(f"  Skipping to {new_start:.1f}s...")
-        new_frames = extract_sample_frames_for_selection(state.video_path, new_start, num_frames=5, interval=2.0)
+        new_frames = _extract_sample_frames_for_selection(state.video_path, new_start, num_frames=5, interval=2.0)
         if new_frames:
             state.frames = new_frames
             state.frame_idx = 0
@@ -285,7 +104,7 @@ class InteractiveSelectionSession:
         last_ts = state.frames[-1][0]
         new_start = last_ts + 300
         print(f"  Skipping to {new_start:.1f}s ({new_start / 60:.1f} min)...")
-        new_frames = extract_sample_frames_for_selection(state.video_path, new_start, num_frames=5, interval=2.0)
+        new_frames = _extract_sample_frames_for_selection(state.video_path, new_start, num_frames=5, interval=2.0)
         if new_frames:
             state.frames = new_frames
             state.frame_idx = 0
@@ -366,11 +185,6 @@ class InteractiveSelectionSession:
         return None
 
 
-# =============================================================================
-# Scorebug Selection Session
-# =============================================================================
-
-
 class ScorebugSelectionSession(InteractiveSelectionSession):
     """Interactive session for selecting the scorebug region."""
 
@@ -417,11 +231,6 @@ class ScorebugSelectionSession(InteractiveSelectionSession):
         return display_frame
 
 
-# =============================================================================
-# Play Clock Selection Session
-# =============================================================================
-
-
 class PlayClockSelectionSession(InteractiveSelectionSession):
     """Interactive session for selecting the play clock region within a scorebug."""
 
@@ -473,11 +282,6 @@ class PlayClockSelectionSession(InteractiveSelectionSession):
         return bbox.unscaled(self.scale_factor)
 
 
-# =============================================================================
-# Timeout Selection Session
-# =============================================================================
-
-
 class TimeoutSelectionSession(InteractiveSelectionSession):
     """Interactive session for selecting timeout indicator regions."""
 
@@ -549,178 +353,3 @@ class TimeoutSelectionSession(InteractiveSelectionSession):
         # Unscale and add padding offset
         unscaled = bbox.unscaled(self.scale_factor)
         return unscaled.offset(self.pad_x1, self.pad_y1)
-
-
-# =============================================================================
-# Public API Functions
-# =============================================================================
-
-
-def print_banner():
-    """Print the welcome banner for CFB40."""
-    print("\n" + "=" * 60)
-    print("   CFB40 - College Football Play Detection Pipeline")
-    print("=" * 60 + "\n")
-
-
-def extract_sample_frames_for_selection(video_path: str, start_time: float, num_frames: int = 5, interval: float = 2.0) -> List[Tuple[float, np.ndarray]]:
-    """Extract sample frames from the video for region selection."""
-    return extract_sample_frames(video_path, start_time, num_frames, interval)
-
-
-def select_scorebug_region(frames: List[Tuple[float, np.ndarray]], video_path: str = None) -> Tuple[Optional[Tuple[int, int, int, int]], Optional[Tuple[float, np.ndarray]]]:
-    """
-    Interactive selection of scorebug region.
-
-    Args:
-        frames: List of (timestamp, frame) tuples to choose from.
-        video_path: Path to video file (for loading additional frames if needed).
-
-    Returns:
-        Tuple of (scorebug_bbox, selected_frame) where:
-        - scorebug_bbox: (x, y, width, height) or None if cancelled
-        - selected_frame: The specific (timestamp, frame) tuple that was selected
-    """
-    if not frames:
-        logger.error("No frames provided for selection")
-        return None, None
-
-    print("\n[Phase 2] Region Setup - Scorebug Selection")
-    print("-" * 50)
-    print("Instructions:")
-    print("  1. Click on the TOP-LEFT corner of the scorebug")
-    print("  2. Click on the BOTTOM-RIGHT corner of the scorebug")
-    print("  'n' = next frame, 'p' = previous frame")
-    print("  's' = skip forward 30s, 'S' = skip forward 5min")
-    print("  'r' = reset selection, 'q' = quit")
-    print("-" * 50)
-
-    session = ScorebugSelectionSession(frames, video_path)
-    bbox = session.run()
-
-    if bbox is None:
-        return None, None
-
-    selected_frame = session.state.current_frame
-    logger.info("Selected frame %d/%d @ %.1fs for scorebug region", session.state.frame_idx + 1, len(session.state.frames), selected_frame[0])
-
-    return bbox.to_tuple(), selected_frame
-
-
-def select_playclock_region(selected_frame: Tuple[float, np.ndarray], scorebug_bbox: Tuple[int, int, int, int]) -> Optional[Tuple[int, int, int, int]]:
-    """
-    Interactive selection of play clock region within the scorebug.
-
-    Args:
-        selected_frame: The (timestamp, frame) tuple selected during scorebug selection.
-        scorebug_bbox: Scorebug bounding box (x, y, width, height).
-
-    Returns:
-        Play clock region as (x_offset, y_offset, width, height) relative to scorebug,
-        or None if cancelled.
-    """
-    if selected_frame is None:
-        logger.error("No frame provided for selection")
-        return None
-
-    timestamp, frame = selected_frame
-    sb_bbox = BBox.from_tuple(scorebug_bbox)
-
-    print("\n[Phase 2] Region Setup - Play Clock Selection")
-    print("-" * 50)
-    print("Instructions:")
-    print("  1. Click on the TOP-LEFT corner of the play clock digits")
-    print("  2. Click on the BOTTOM-RIGHT corner of the play clock digits")
-    print("  Press 'r' to reset, 'q' to quit")
-    print("-" * 50)
-
-    logger.info("Using frame @ %.1fs for play clock selection (same as scorebug selection)", timestamp)
-
-    session = PlayClockSelectionSession(frame, sb_bbox, scale_factor=3)
-    bbox = session.get_unscaled_bbox() if session.run() else None
-
-    return bbox.to_tuple() if bbox else None
-
-
-def select_timeout_region(selected_frame: Tuple[float, np.ndarray], scorebug_bbox: Tuple[int, int, int, int], team: str) -> Optional[Tuple[int, int, int, int]]:
-    """
-    Interactive selection of timeout indicator region for a team.
-
-    Args:
-        selected_frame: The (timestamp, frame) tuple selected during scorebug selection.
-        scorebug_bbox: Scorebug bounding box (x, y, width, height).
-        team: "home" or "away".
-
-    Returns:
-        Timeout region as (x, y, width, height) in absolute frame coordinates,
-        or None if cancelled.
-    """
-    if selected_frame is None:
-        logger.error("No frame provided for selection")
-        return None
-
-    timestamp, frame = selected_frame
-    sb_bbox = BBox.from_tuple(scorebug_bbox)
-
-    print(f"\n[Phase 2] Region Setup - {team.upper()} Team Timeout Selection")
-    print("-" * 50)
-    print("Instructions:")
-    print(f"  Select the 3 timeout indicator ovals for the {team.upper()} team")
-    print("  (They are vertically stacked - white = available, dark = used)")
-    print("  1. Click on the TOP-LEFT corner of the timeout region")
-    print("  2. Click on the BOTTOM-RIGHT corner of the timeout region")
-    print("  Press 'r' to reset, 'q' to quit")
-    print("-" * 50)
-
-    logger.info("Using frame @ %.1fs for %s timeout selection", timestamp, team)
-
-    session = TimeoutSelectionSession(frame, sb_bbox, team, scale_factor=3, padding=50)
-    session.run()
-    bbox = session.get_absolute_bbox()
-
-    return bbox.to_tuple() if bbox else None
-
-
-def get_video_path_from_user(project_root: Path) -> Optional[str]:
-    """
-    Prompt user to enter video file path.
-
-    Args:
-        project_root: Root directory of the project.
-
-    Returns:
-        Path to selected video file, or None if no valid selection.
-    """
-    print("\nAvailable videos in full_videos/:")
-    videos_dir = project_root / "full_videos"
-    videos = []
-    if videos_dir.exists():
-        videos = list(videos_dir.glob("*.mp4")) + list(videos_dir.glob("*.mkv"))
-        for i, v in enumerate(videos, 1):
-            print(f"  {i}. {v.name}")
-
-    print("\nEnter video path (or number from list above):")
-    user_input = input("> ").strip()
-
-    if not user_input:
-        return None
-
-    # Check if user entered a number
-    try:
-        idx = int(user_input) - 1
-        if 0 <= idx < len(videos):
-            return str(videos[idx])
-    except ValueError:
-        pass
-
-    # Check if it's a valid path
-    if Path(user_input).exists():
-        return user_input
-
-    # Check if it's relative to full_videos
-    relative_path = videos_dir / user_input
-    if relative_path.exists():
-        return str(relative_path)
-
-    logger.error("Video not found: %s", user_input)
-    return None

tests/test_digit_templates/test_fast_full_video.py

@@ -2,13 +2,13 @@
 """
 FAST full video evaluation using template-based play clock reading.
 
-This script uses PlayDetector in FIXED COORDINATES mode which:
-1. Skips scorebug detection entirely (uses known fixed coordinates)
+This script uses PlayDetector with pre-configured fixed coordinates, which:
+1. Uses the known scorebug region (skips region discovery/searching)
 2. Uses template matching for play clock reading
 3. Includes all detection logic (state machine + clock reset detection)
 
-This is much faster than standard mode AND uses the same detection logic
-as main.py, avoiding the bug where we missed the clock reset detection pass.
+The detection logic is unified - whether coordinates come from user selection
+or from fixed config like here, the same multi-pass architecture is used.
 
 Usage:
     cd /Users/andytaylor/Documents/Personal/cfb40