perfect mypy

pyproject.toml

@@ -19,6 +19,7 @@ dev = [
     "black>=24.0.0",
     "pylint>=3.0.0",
     "pylint-pydantic>=0.3.0",
+    "mypy>=1.0.0",
 ]
 
 [build-system]
@@ -36,6 +37,12 @@ python_version = "3.13"
 strict = true
 ignore_missing_imports = true
 exclude = ["tests", "scripts", "examples", "static"]
+plugins = ["pydantic.mypy"]
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true
 
 [tool.black]
 line-length = 180

src/config/session.py

@@ -8,7 +8,7 @@ including region selections, video paths, and project constants.
 import json
 import logging
 from pathlib import Path
-from typing import Tuple
+from typing import Any, Optional, Tuple
 
 import cv2
 import numpy as np
@@ -127,7 +127,7 @@ def _save_config_json(config: SessionConfig, output_dir: Path, basename: str) ->
     return config_path
 
 
-def _extract_frame_from_video(video_path: str, timestamp: float) -> np.ndarray | None:
+def _extract_frame_from_video(video_path: str, timestamp: float) -> np.ndarray[Any, Any] | None:
     """
     Extract a single frame from a video at the given timestamp.
 
@@ -151,7 +151,7 @@ def _extract_frame_from_video(video_path: str, timestamp: float) -> np.ndarray |
     return frame
 
 
-def _save_template_image(config: SessionConfig, output_dir: Path, basename: str, frame: np.ndarray) -> Path:
+def _save_template_image(config: SessionConfig, output_dir: Path, basename: str, frame: np.ndarray[Any, Any]) -> Path:
     """
     Extract the scorebug region from a frame and save it as the template image.
 
@@ -255,7 +255,7 @@ def _save_timeout_config(config: SessionConfig, output_dir: Path, basename: str)
 def save_session_config(
     config: SessionConfig,
     output_dir: Path,
-    selected_frame: Tuple[float, np.ndarray] | None = None,
+    selected_frame: Tuple[float, np.ndarray[Any, Any]] | None = None,
 ) -> Tuple[str, str]:
     """
     Save session configuration and generate template image.
@@ -276,6 +276,7 @@ def save_session_config(
     config_path = _save_config_json(config, output_dir, basename)
 
     # Get frame for template generation
+    frame: Optional[np.ndarray[Any, Any]] = None
     if selected_frame is not None:
         timestamp, frame = selected_frame
         logger.info("Using selected frame @ %.1fs for template generation", timestamp)

src/detection/scorebug.py

@@ -8,7 +8,7 @@ This module provides functions to detect the presence and location of the scoreb
 import json
 import logging
 from pathlib import Path
-from typing import Optional, Tuple
+from typing import Any, Optional, Tuple
 
 import cv2
 import numpy as np
@@ -55,15 +55,15 @@ class DetectScoreBug:
             fixed_region_config_path: Path to JSON config with fixed region (alternative to fixed_region)
             use_split_detection: Enable split-half detection for robustness to partial overlays (default: True)
         """
-        self.template = None
+        self.template: Optional[np.ndarray[Any, Any]] = None
         self.template_path = template_path
         self.fixed_region = fixed_region
         self._use_fixed_region = fixed_region is not None
         self.use_split_detection = use_split_detection
 
         # Pre-computed template halves for split detection (populated when template is loaded)
-        self._template_left = None
-        self._template_right = None
+        self._template_left: Optional[np.ndarray[Any, Any]] = None
+        self._template_right: Optional[np.ndarray[Any, Any]] = None
 
         if template_path:
             self.load_template(template_path)
@@ -126,7 +126,7 @@ class DetectScoreBug:
                 self._template_right.shape[0],
             )
 
-    def detect(self, frame: np.ndarray) -> ScorebugDetection:
+    def detect(self, frame: np.ndarray[Any, Any]) -> ScorebugDetection:
         """
         Detect scorebug in a frame.
 
@@ -167,7 +167,7 @@ class DetectScoreBug:
         return detection
 
     # pylint: disable=too-many-locals
-    def _detect_in_fixed_region(self, frame: np.ndarray) -> ScorebugDetection:
+    def _detect_in_fixed_region(self, frame: np.ndarray[Any, Any]) -> ScorebugDetection:
         """
         Detect scorebug by checking only the fixed known location.
 
@@ -185,6 +185,10 @@ class DetectScoreBug:
         Returns:
             Detection result
         """
+        # Asserts: this method should only be called when fixed_region and template are set
+        assert self.fixed_region is not None
+        assert self.template is not None
+
         x, y, _, _ = self.fixed_region
         th, tw = self.template.shape[:2]
 
@@ -244,7 +248,7 @@ class DetectScoreBug:
         return ScorebugDetection(detected=False, confidence=full_confidence, bbox=(x, y, tw, th), method="fixed_region")
 
     # pylint: disable=too-many-locals
-    def _detect_by_template_fullsearch(self, frame: np.ndarray) -> ScorebugDetection:
+    def _detect_by_template_fullsearch(self, frame: np.ndarray[Any, Any]) -> ScorebugDetection:
         """
         Detect scorebug using full-frame template matching.
 
@@ -351,7 +355,7 @@ class DetectScoreBug:
 
         logger.info("Saved fixed region config to: %s", config_path)
 
-    def discover_and_lock_region(self, frame: np.ndarray) -> bool:
+    def discover_and_lock_region(self, frame: np.ndarray[Any, Any]) -> bool:
         """
         Discover scorebug location using full search, then lock to fixed region mode.
 
@@ -376,7 +380,7 @@ class DetectScoreBug:
         self._use_fixed_region = old_use_fixed
         return False
 
-    def visualize_detection(self, frame: np.ndarray, detection: ScorebugDetection) -> np.ndarray:
+    def visualize_detection(self, frame: np.ndarray[Any, Any], detection: ScorebugDetection) -> np.ndarray[Any, Any]:
         """
         Draw detection results on frame for visualization.
 
@@ -403,7 +407,7 @@ class DetectScoreBug:
         return vis_frame
 
 
-def create_template_from_frame(frame: np.ndarray, bbox: Tuple[int, int, int, int], output_path: str) -> None:
+def create_template_from_frame(frame: np.ndarray[Any, Any], bbox: Tuple[int, int, int, int], output_path: str) -> None:
     """
     Extract a region from a frame to use as a template.
 

src/detection/timeouts.py

@@ -9,7 +9,7 @@ Detecting when an oval changes from white to dark indicates a timeout was called
 import json
 import logging
 from pathlib import Path
-from typing import Optional, Tuple, List
+from typing import Any, Optional, Tuple, List
 
 import cv2
 import numpy as np
@@ -128,7 +128,7 @@ class DetectTimeouts:
         self._configured = True
         logger.info("Timeout regions set: home=%s, away=%s", home_region.bbox, away_region.bbox)
 
-    def _extract_oval_bright_ratios(self, frame: np.ndarray, region: TimeoutRegionConfig) -> List[float]:
+    def _extract_oval_bright_ratios(self, frame: np.ndarray[Any, Any], region: TimeoutRegionConfig) -> List[float]:
         """
         Extract the ratio of bright pixels for each oval in a region.
 
@@ -194,7 +194,7 @@ class DetectTimeouts:
         """Count how many timeouts are available (white ovals)."""
         return sum(1 for state in oval_states if state)
 
-    def read_timeouts(self, frame: np.ndarray) -> TimeoutReading:
+    def read_timeouts(self, frame: np.ndarray[Any, Any]) -> TimeoutReading:
         """
         Read the current timeout count for each team.
 
@@ -208,6 +208,10 @@ class DetectTimeouts:
             logger.warning("Timeout tracker not configured")
             return TimeoutReading(home_timeouts=3, away_timeouts=3, confidence=0.0)
 
+        # Asserts: _configured guarantees regions are set
+        assert self.home_region is not None
+        assert self.away_region is not None
+
         # Read home team timeouts using bright pixel ratio
         home_bright_ratios = self._extract_oval_bright_ratios(frame, self.home_region)
         home_states = self._classify_ovals(home_bright_ratios)
@@ -291,7 +295,7 @@ class DetectTimeouts:
         self._prev_reading = curr_reading
         return result
 
-    def update(self, frame: np.ndarray) -> Tuple[TimeoutReading, Optional[str]]:
+    def update(self, frame: np.ndarray[Any, Any]) -> Tuple[TimeoutReading, Optional[str]]:
         """
         Read timeouts and detect any change in one call.
 
@@ -310,7 +314,7 @@ class DetectTimeouts:
         self._prev_reading = None
         logger.debug("Timeout tracking reset")
 
-    def visualize(self, frame: np.ndarray, reading: Optional[TimeoutReading] = None) -> np.ndarray:
+    def visualize(self, frame: np.ndarray[Any, Any], reading: Optional[TimeoutReading] = None) -> np.ndarray[Any, Any]:
         """
         Draw timeout regions and states on frame for visualization.
 

src/pipeline/parallel.py

@@ -13,7 +13,7 @@ import time
 from concurrent.futures import Future, ProcessPoolExecutor, as_completed
 from multiprocessing import Manager
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Dict, List, MutableMapping, Optional, Tuple
 
 from utils import create_frame_result
 from .models import ChunkResult, ParallelProcessingConfig
@@ -182,7 +182,7 @@ def _process_chunk(
     config: ParallelProcessingConfig,
     chunk_start: float,
     chunk_end: float,
-    progress_dict: Optional[Dict[int, Any]] = None,
+    progress_dict: Optional[MutableMapping[int, Any]] = None,
 ) -> ChunkResult:
     """
     Process a single video chunk using OpenCV.
@@ -310,7 +310,7 @@ def _calculate_chunk_boundaries(start_time: float, end_time: float, num_workers:
     return chunks
 
 
-def _create_progress_monitor(progress_dict: Dict[int, Any], num_workers: int) -> Tuple[threading.Thread, threading.Event]:
+def _create_progress_monitor(progress_dict: MutableMapping[int, Any], num_workers: int) -> Tuple[threading.Thread, threading.Event]:
     """
     Create a progress monitoring thread.
 
@@ -333,7 +333,7 @@ def _create_progress_monitor(progress_dict: Dict[int, Any], num_workers: int) ->
     return monitor_thread, stop_monitor
 
 
-def _display_progress(progress_dict: Dict[int, Any], num_workers: int) -> None:
+def _display_progress(progress_dict: MutableMapping[int, Any], num_workers: int) -> None:
     """
     Build and display current progress string.
 
@@ -386,7 +386,7 @@ def _submit_chunk_jobs(
     executor: ProcessPoolExecutor,
     chunks: List[Tuple[int, float, float]],
     config: ParallelProcessingConfig,
-    progress_dict: Dict[int, Any],
+    progress_dict: MutableMapping[int, Any],
 ) -> Dict[Future[ChunkResult], int]:
     """
     Submit all chunk processing jobs to the executor.

src/pipeline/play_detector.py

@@ -82,17 +82,15 @@ class PlayDetector:
             timeout_tracker: Optional timeout tracker for clock reset classification
         """
         self.config = config
-        self.scorebug_detector: Optional[DetectScoreBug] = None
-        self.clock_reader: Optional[PlayClockRegionExtractor] = None
-        self.state_machine: Optional[TrackPlayState] = None
         self.timeout_tracker = timeout_tracker
 
-        # Template-based clock reading components
+        # Template-based clock reading components (conditionally initialized)
         self.template_builder: Optional[DigitTemplateBuilder] = None
         self.template_library: Optional[DigitTemplateLibrary] = None
         self.template_reader: Optional[ReadPlayClock] = None
 
         self._validate_config()
+        # Core components are initialized here (scorebug_detector, clock_reader, state_machine)
         self._initialize_components()
 
     def _validate_config(self) -> None:
@@ -125,6 +123,7 @@ class PlayDetector:
             logger.info("Fixed coordinates mode - regions pre-configured")
 
             # Compute play clock offset relative to scorebug from absolute coordinates
+            assert self.config.fixed_playclock_coords is not None  # Already checked above, helps mypy
             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
@@ -138,7 +137,7 @@ class PlayDetector:
             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)
-            self.scorebug_detector = DetectScoreBug(template_path=None, use_split_detection=self.config.use_split_detection)
+            self.scorebug_detector: DetectScoreBug = DetectScoreBug(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:
@@ -146,7 +145,7 @@ class PlayDetector:
                 logger.info("Scorebug fixed region set: %s", self.config.fixed_scorebug_coords)
 
             # Initialize play clock region extractor with the derived config
-            self.clock_reader = PlayClockRegionExtractor(region_config=playclock_config)
+            self.clock_reader: PlayClockRegionExtractor = PlayClockRegionExtractor(region_config=playclock_config)
             logger.info("Play clock region extractor initialized with offset=(%d, %d), size=(%d, %d)", x_offset, y_offset, pc_w, pc_h)
         else:
             # Standard mode: use template and config files
@@ -158,7 +157,7 @@ class PlayDetector:
             logger.info("Play clock region extractor initialized")
 
         # Initialize state machine
-        self.state_machine = TrackPlayState()
+        self.state_machine: TrackPlayState = TrackPlayState()
         logger.info("State machine initialized")
 
         # Initialize template matching components
@@ -249,6 +248,8 @@ class PlayDetector:
             True if templates were built successfully, False otherwise
         """
         # Use the extracted TemplateBuildingPass module
+        # Assert: template_builder is initialized when this method is called
+        assert self.template_builder is not None
         template_pass = TemplateBuildingPass(
             config=self.config,
             clock_reader=self.clock_reader,
@@ -355,7 +356,7 @@ class PlayDetector:
 
     def _process_frame_streaming(
         self,
-        frame: np.ndarray,
+        frame: np.ndarray[Any, Any],
         current_time: float,
         timing: Dict[str, float],
         stats: Dict[str, Any],
@@ -410,6 +411,7 @@ class PlayDetector:
 
             # Extract play clock region and run template matching immediately
             t_start = time.perf_counter()
+            assert scorebug.bbox is not None  # scorebug.detected implies bbox is set
             play_clock_region = self.clock_reader.extract_region(frame, scorebug.bbox)
             timing["preprocessing"] += time.perf_counter() - t_start
 
@@ -492,9 +494,9 @@ class PlayDetector:
         plays = self._merge_plays(state_machine_plays, clock_reset_plays)
 
         # Recalculate stats from merged plays
-        start_methods = {}
-        end_methods = {}
-        play_types = {}
+        start_methods: Dict[str, int] = {}
+        end_methods: Dict[str, int] = {}
+        play_types: Dict[str, int] = {}
         for play in plays:
             start_methods[play.start_method] = start_methods.get(play.start_method, 0) + 1
             end_methods[play.end_method] = end_methods.get(play.end_method, 0) + 1
@@ -697,13 +699,13 @@ class PlayDetector:
         Returns:
             Play end timestamp
         """
-        start_timestamp = frame_data[frame_idx]["timestamp"]
+        start_timestamp: float = frame_data[frame_idx]["timestamp"]
         max_end_time = start_timestamp + max_duration
 
         # Look for scorebug disappearance (but cap at max_duration from start)
         for j in range(frame_idx + 1, len(frame_data)):
             frame = frame_data[j]
-            timestamp = frame["timestamp"]
+            timestamp: float = frame["timestamp"]
 
             # If we've exceeded max_duration, end the play at max_duration
             if timestamp >= max_end_time:
@@ -715,7 +717,7 @@ class PlayDetector:
                 return timestamp
 
         # Default: end at max_duration (or end of data if shorter)
-        return min(max_end_time, frame_data[-1]["timestamp"] if frame_data else max_end_time)
+        return min(max_end_time, float(frame_data[-1]["timestamp"]) if frame_data else max_end_time)
 
     def _merge_plays(self, state_machine_plays: List[PlayEvent], clock_reset_plays: List[PlayEvent]) -> List[PlayEvent]:
         """
@@ -942,6 +944,9 @@ class PlayDetector:
         t_parallel_start = time.perf_counter()
 
         # Create parallel processing config
+        # Asserts: validated by _validate_config, parallel mode requires fixed coords
+        assert self.config.fixed_playclock_coords is not None
+        assert self.config.fixed_scorebug_coords is not None
         parallel_config = ParallelProcessingConfig(
             video_path=self.config.video_path,
             start_time=self.config.start_time,

src/pipeline/template_builder_pass.py

@@ -14,7 +14,7 @@ import logging
 import time
 from functools import lru_cache
 from pathlib import Path
-from typing import Optional, Tuple
+from typing import Any, Optional, Tuple
 
 import cv2
 import easyocr
@@ -56,7 +56,7 @@ def _validate_config(config: DetectionConfig) -> bool:
 
 
 def _process_scorebug_frame(
-    frame: np.ndarray,
+    frame: np.ndarray[Any, Any],
     scorebug_bbox: Tuple[int, int, int, int],
     current_time: float,
     clock_reader: PlayClockRegionExtractor,
@@ -167,6 +167,7 @@ def _scan_video(
 
             if scorebug_result.detected:
                 frames_with_scorebug += 1
+                assert scorebug_result.bbox is not None  # detected implies bbox is set
                 valid_samples += _process_scorebug_frame(frame, scorebug_result.bbox, current_time, clock_reader, template_builder, reader)
 
             # Progress logging every 200 frames
@@ -238,6 +239,9 @@ def run_template_building_pass(
     if not _validate_config(config):
         return None, None, time.perf_counter() - t_build_start
 
+    # Assert: _validate_config guarantees fixed_scorebug_coords is set
+    assert config.fixed_scorebug_coords is not None
+
     # Create temporary scorebug detector for Pass 0
     sb_x, sb_y, sb_w, sb_h = config.fixed_scorebug_coords
     logger.info("  Scorebug region: (%d, %d, %d, %d)", sb_x, sb_y, sb_w, sb_h)

src/readers/playclock.py

@@ -14,7 +14,7 @@ Performance comparison (from ocr_benchmark.md):
 """
 
 import logging
-from typing import List, Tuple
+from typing import Any, List, Tuple
 
 import cv2
 import numpy as np
@@ -67,7 +67,7 @@ class ReadPlayClock:
 
         logger.info("ReadPlayClock initialized")
 
-    def preprocess_region(self, region: np.ndarray) -> np.ndarray:
+    def preprocess_region(self, region: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
         """
         Preprocess play clock region for template matching.
 
@@ -81,7 +81,7 @@ class ReadPlayClock:
         """
         return preprocess_playclock_region(region, self.scale_factor)
 
-    def match_digit(self, region: np.ndarray, templates: List[DigitTemplate]) -> TemplateMatchResult:
+    def match_digit(self, region: np.ndarray[Any, Any], templates: List[DigitTemplate]) -> TemplateMatchResult:
         """
         Match a region against a set of digit templates.
 
@@ -124,7 +124,7 @@ class ReadPlayClock:
 
         return TemplateMatchResult(digit_value=best_digit, confidence=best_confidence, is_valid=is_valid)
 
-    def _try_double_digit(self, preprocessed: np.ndarray) -> TemplatePlayClockReading:
+    def _try_double_digit(self, preprocessed: np.ndarray[Any, Any]) -> TemplatePlayClockReading:
         """
         Try to read as double-digit display (10-40): tens on left, ones on right.
 
@@ -194,7 +194,7 @@ class ReadPlayClock:
             method="template_double",
         )
 
-    def _try_single_digit(self, preprocessed: np.ndarray) -> TemplatePlayClockReading:
+    def _try_single_digit(self, preprocessed: np.ndarray[Any, Any]) -> TemplatePlayClockReading:
         """
         Try to read as single-digit display (0-9): digit is centered.
 
@@ -268,7 +268,7 @@ class ReadPlayClock:
             method="template_single",
         )
 
-    def read(self, region: np.ndarray) -> TemplatePlayClockReading:
+    def read(self, region: np.ndarray[Any, Any]) -> TemplatePlayClockReading:
         """
         Read the play clock value from a region using dual-mode template matching.
 
@@ -306,7 +306,7 @@ class ReadPlayClock:
 
     def read_from_frame(
         self,
-        frame: np.ndarray,
+        frame: np.ndarray[Any, Any],
         scorebug_bbox: Tuple[int, int, int, int],
         clock_region_offset: Tuple[int, int, int, int],
     ) -> TemplatePlayClockReading:
@@ -347,7 +347,7 @@ class ReadPlayClock:
 
     def read_from_fixed_location(
         self,
-        frame: np.ndarray,
+        frame: np.ndarray[Any, Any],
         absolute_coords: Tuple[int, int, int, int],
     ) -> TemplatePlayClockReading:
         """

src/setup/models.py

@@ -6,6 +6,8 @@ OCR-labeled samples are collected and averaged into digit templates.
 Also includes region configuration models for setup.
 """
 
+from typing import Any
+
 import numpy as np
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -18,7 +20,7 @@ class DigitSample(BaseModel):
     digit_value: int = Field(..., description="0-9 for ones digit, 0-4 for tens digit, -1 for blank")
     is_tens_digit: bool = Field(..., description="True if this is the tens place digit")
     position: str = Field(..., description="'left', 'center', or 'right' - where digit appears in region")
-    image: np.ndarray = Field(..., description="The digit image (grayscale, preprocessed)")
+    image: np.ndarray[Any, Any] = Field(..., description="The digit image (grayscale, preprocessed)")
     source_clock_value: int = Field(..., description="The full clock value this was extracted from")
     timestamp: float = Field(..., description="Video timestamp where this was captured")
     confidence: float = Field(..., description="OCR confidence for this sample")
@@ -32,7 +34,7 @@ class DigitTemplate(BaseModel):
     digit_value: int = Field(..., description="0-9 for ones, 0-4 for tens, -1 for blank")
     is_tens_digit: bool = Field(..., description="True if this is a tens place template")
     position: str = Field(..., description="'left', 'center', or 'right' - where digit appears in region")
-    template: np.ndarray = Field(..., description="The template image (grayscale)")
+    template: np.ndarray[Any, Any] = Field(..., description="The template image (grayscale)")
     sample_count: int = Field(..., description="Number of samples used to build this template")
     avg_confidence: float = Field(..., description="Average OCR confidence of source samples")
 

src/setup/playclock_region.py

@@ -14,7 +14,7 @@ Color detection utilities are shared from utils.color to eliminate code duplicat
 import json
 import logging
 from pathlib import Path
-from typing import Optional, Tuple
+from typing import Any, Optional, Tuple
 
 import cv2
 import numpy as np
@@ -90,7 +90,7 @@ class PlayClockRegionExtractor:
             self.config.height,
         )
 
-    def extract_region(self, frame: np.ndarray, scorebug_bbox: Tuple[int, int, int, int]) -> Optional[np.ndarray]:
+    def extract_region(self, frame: np.ndarray[Any, Any], scorebug_bbox: Tuple[int, int, int, int]) -> Optional[np.ndarray[Any, Any]]:
         """
         Extract the play clock region from the frame.
 
@@ -131,7 +131,7 @@ class PlayClockRegionExtractor:
         region = frame[pc_y : pc_y + pc_h, pc_x : pc_x + pc_w].copy()
         return region
 
-    def preprocess_for_ocr(self, region: np.ndarray) -> np.ndarray:
+    def preprocess_for_ocr(self, region: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
         """
         Preprocess the play clock region for OCR (used during template building).
 
@@ -167,7 +167,7 @@ class PlayClockRegionExtractor:
 
         if is_red:
             # For red digits, use percentile-based threshold on the red channel
-            threshold_value = np.percentile(scaled, 90)
+            threshold_value = float(np.percentile(np.asarray(scaled), 90))
             _, binary = cv2.threshold(scaled, threshold_value, 255, cv2.THRESH_BINARY)
             logger.debug("Red digit threshold (90th percentile): %.1f", threshold_value)
 
@@ -182,7 +182,7 @@ class PlayClockRegionExtractor:
             _, binary = cv2.threshold(scaled, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
 
             # Determine if we need to invert
-            mean_intensity = np.mean(binary)
+            mean_intensity = np.mean(np.asarray(binary))
             if mean_intensity < 128:
                 binary = cv2.bitwise_not(binary)
 

src/setup/template_builder.py

@@ -57,11 +57,11 @@ class DigitTemplateBuilder:
         self.samples: Dict[Tuple[bool, int, str], List[DigitSample]] = {}
 
         # Track raw clock region images for potential reprocessing
-        self.raw_regions: List[Tuple[float, int, np.ndarray]] = []  # (timestamp, clock_value, region)
+        self.raw_regions: List[Tuple[float, int, np.ndarray[Any, Any]]] = []  # (timestamp, clock_value, region)
 
         logger.info("DigitTemplateBuilder initialized (region: %dx%d)", region_width, region_height)
 
-    def preprocess_region(self, region: np.ndarray) -> np.ndarray:
+    def preprocess_region(self, region: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
         """
         Preprocess play clock region for template extraction.
 
@@ -75,7 +75,9 @@ class DigitTemplateBuilder:
         """
         return preprocess_playclock_region(region, scale_factor=4)
 
-    def extract_digits(self, preprocessed: np.ndarray, clock_value: int) -> Tuple[Optional[np.ndarray], Optional[np.ndarray], Optional[np.ndarray], Optional[np.ndarray]]:
+    def extract_digits(
+        self, preprocessed: np.ndarray[Any, Any], clock_value: int
+    ) -> Tuple[Optional[np.ndarray[Any, Any]], Optional[np.ndarray[Any, Any]], Optional[np.ndarray[Any, Any]], Optional[np.ndarray[Any, Any]]]:
         """
         Extract individual digit images from preprocessed play clock region.
 
@@ -97,7 +99,7 @@ class DigitTemplateBuilder:
         # Single-digit: far-left is blank (truly empty), ones is centered
         return None, None, extract_center_region(preprocessed), extract_far_left_region(preprocessed)
 
-    def add_sample(self, region: np.ndarray, clock_value: int, timestamp: float, confidence: float = 1.0) -> None:
+    def add_sample(self, region: np.ndarray[Any, Any], clock_value: int, timestamp: float, confidence: float = 1.0) -> None:
         """
         Add a play clock sample for template building.
 
@@ -130,6 +132,7 @@ class DigitTemplateBuilder:
 
         if clock_value >= 10:
             # Double-digit display (10-40): tens on left, ones on right
+            assert tens_img is not None  # Asserts: validated by extract_digits
             # Store tens sample (left position)
             tens_sample = DigitSample(
                 digit_value=tens_digit,
@@ -146,6 +149,7 @@ class DigitTemplateBuilder:
             self.samples[tens_key].append(tens_sample)
 
             # Store ones sample (right position)
+            assert ones_right_img is not None  # Asserts: validated by extract_digits
             ones_sample = DigitSample(
                 digit_value=ones_digit,
                 is_tens_digit=False,
@@ -170,6 +174,7 @@ class DigitTemplateBuilder:
         else:
             # Single-digit display (0-9): digit is centered, tens position is blank
             # Store blank sample (far-left position - should be truly empty)
+            assert blank_img is not None  # Asserts: validated by extract_digits
             blank_sample = DigitSample(
                 digit_value=-1,  # blank
                 is_tens_digit=True,
@@ -185,6 +190,7 @@ class DigitTemplateBuilder:
             self.samples[blank_key].append(blank_sample)
 
             # Store ones sample (center position)
+            assert ones_center_img is not None  # Asserts: validated by extract_digits
             ones_sample = DigitSample(
                 digit_value=ones_digit,
                 is_tens_digit=False,

src/ui/api.py

@@ -7,7 +7,7 @@ that are intended to be called by external code.
 
 import logging
 from pathlib import Path
-from typing import List, Optional, Tuple
+from typing import Any, List, Optional, Tuple
 
 import numpy as np
 
@@ -26,12 +26,14 @@ def print_banner() -> None:
     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]]:
+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[Any, Any]]]:
     """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 = None) -> Tuple[Optional[Tuple[int, int, int, int]], Optional[Tuple[float, np.ndarray]]]:
+def select_scorebug_region(
+    frames: List[Tuple[float, np.ndarray[Any, Any]]], video_path: str | None = None
+) -> Tuple[Optional[Tuple[int, int, int, int]], Optional[Tuple[float, np.ndarray[Any, Any]]]]:
     """
     Interactive selection of scorebug region.
 
@@ -70,7 +72,7 @@ def select_scorebug_region(frames: List[Tuple[float, np.ndarray]], video_path: s
     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]]:
+def select_playclock_region(selected_frame: Tuple[float, np.ndarray[Any, Any]], scorebug_bbox: Tuple[int, int, int, int]) -> Optional[Tuple[int, int, int, int]]:
     """
     Interactive selection of play clock region within the scorebug.
 
@@ -105,7 +107,7 @@ def select_playclock_region(selected_frame: Tuple[float, np.ndarray], scorebug_b
     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]]:
+def select_timeout_region(selected_frame: Tuple[float, np.ndarray[Any, Any]], scorebug_bbox: Tuple[int, int, int, int], team: str) -> Optional[Tuple[int, int, int, int]]:
     """
     Interactive selection of timeout indicator region for a team.
 

src/ui/models.py

@@ -5,7 +5,7 @@ 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
+from typing import Any, List, Optional, Tuple
 
 import numpy as np
 from pydantic import BaseModel, ConfigDict
@@ -75,13 +75,13 @@ class SelectionState(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
     frame_idx: int = 0
-    frames: List[Tuple[float, np.ndarray]] = []
+    frames: List[Tuple[float, np.ndarray[Any, Any]]] = []
     should_quit: bool = False
     should_confirm: bool = False
     video_path: Optional[str] = None
 
     @property
-    def current_frame(self) -> Tuple[float, np.ndarray]:
+    def current_frame(self) -> Tuple[float, np.ndarray[Any, Any]]:
         """Get the current (timestamp, frame) tuple."""
         return self.frames[self.frame_idx]
 
@@ -91,6 +91,6 @@ class SelectionState(BaseModel):
         return self.frames[self.frame_idx][0]
 
     @property
-    def frame(self) -> np.ndarray:
+    def frame(self) -> np.ndarray[Any, Any]:
         """Get the current frame."""
         return self.frames[self.frame_idx][1]

src/ui/sessions.py

@@ -7,7 +7,7 @@ This module provides session classes for different types of region selection:
 - TimeoutSelectionSession: For selecting timeout indicator regions
 """
 
-from typing import Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Tuple
 
 import cv2
 import numpy as np
@@ -16,7 +16,7 @@ from .models import BBox, SelectionState, SelectionViewConfig
 from .selector import KeyHandler, RegionSelector
 
 
-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]]:
+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[Any, Any]]]:
     """Extract sample frames for interactive selection.
 
     Note: Import is inside function to avoid circular imports.
@@ -42,7 +42,7 @@ class InteractiveSelectionSession:
     def __init__(
         self,
         window_name: str,
-        frames: List[Tuple[float, np.ndarray]],
+        frames: List[Tuple[float, np.ndarray[Any, Any]]],
         view_config: Optional[SelectionViewConfig] = None,
         video_path: Optional[str] = None,
     ):
@@ -130,15 +130,15 @@ class InteractiveSelectionSession:
     # Display Methods (to be overridden by subclasses)
     # -------------------------------------------------------------------------
 
-    def _render_frame(self, display_frame: np.ndarray) -> np.ndarray:
+    def _render_frame(self, display_frame: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
         """Render overlays on the display frame. Override in subclasses."""
         return display_frame
 
-    def _get_display_frame(self) -> np.ndarray:
+    def _get_display_frame(self) -> np.ndarray[Any, Any]:
         """Get the frame to display. Override in subclasses for custom views."""
         return self.state.frame.copy()
 
-    def _draw_selection_overlay(self, display_frame: np.ndarray) -> np.ndarray:
+    def _draw_selection_overlay(self, display_frame: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
         """Draw the selection points and rectangles on the frame."""
         # Draw clicked points
         for i, point in enumerate(self.selector.points):
@@ -196,7 +196,7 @@ class InteractiveSelectionSession:
 class ScorebugSelectionSession(InteractiveSelectionSession):
     """Interactive session for selecting the scorebug region."""
 
-    def __init__(self, frames: List[Tuple[float, np.ndarray]], video_path: Optional[str] = None):
+    def __init__(self, frames: List[Tuple[float, np.ndarray[Any, Any]]], video_path: Optional[str] = None):
         """Initialize scorebug selection session."""
         super().__init__(
             window_name="Select Scorebug Region",
@@ -211,7 +211,7 @@ class ScorebugSelectionSession(InteractiveSelectionSession):
         self._key_handlers[ord("S")] = self._handle_skip_5min
         self._key_handlers[13] = self._handle_confirm  # Enter key
 
-    def _render_frame(self, display_frame: np.ndarray) -> np.ndarray:
+    def _render_frame(self, display_frame: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
         """Render scorebug-specific overlays and instructions."""
         # Draw point labels
         for i, point in enumerate(self.selector.points):
@@ -242,7 +242,7 @@ class ScorebugSelectionSession(InteractiveSelectionSession):
 class PlayClockSelectionSession(InteractiveSelectionSession):
     """Interactive session for selecting the play clock region within a scorebug."""
 
-    def __init__(self, frame: np.ndarray, scorebug_bbox: BBox, scale_factor: int = 3):
+    def __init__(self, frame: np.ndarray[Any, Any], scorebug_bbox: BBox, scale_factor: int = 3):
         """Initialize play clock selection session."""
         self.scorebug_bbox = scorebug_bbox
         self.scale_factor = scale_factor
@@ -268,7 +268,7 @@ class PlayClockSelectionSession(InteractiveSelectionSession):
         )
         self._key_handlers[13] = self._handle_confirm  # Enter key
 
-    def _render_frame(self, display_frame: np.ndarray) -> np.ndarray:
+    def _render_frame(self, display_frame: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
         """Render play clock selection overlays."""
         # Draw grid for reference
         grid_spacing = 50 * self.scale_factor
@@ -293,7 +293,7 @@ class PlayClockSelectionSession(InteractiveSelectionSession):
 class TimeoutSelectionSession(InteractiveSelectionSession):
     """Interactive session for selecting timeout indicator regions."""
 
-    def __init__(self, frame: np.ndarray, scorebug_bbox: BBox, team: str, scale_factor: int = 3, padding: int = 50):
+    def __init__(self, frame: np.ndarray[Any, Any], scorebug_bbox: BBox, team: str, scale_factor: int = 3, padding: int = 50):
         """Initialize timeout selection session."""
         self.scorebug_bbox = scorebug_bbox
         self.scale_factor = scale_factor
@@ -328,7 +328,7 @@ class TimeoutSelectionSession(InteractiveSelectionSession):
         )
         self._key_handlers[13] = self._handle_confirm  # Enter key
 
-    def _render_frame(self, display_frame: np.ndarray) -> np.ndarray:
+    def _render_frame(self, display_frame: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
         """Render timeout selection overlays."""
         # Draw scorebug boundary for reference
         sb_scaled = self.scorebug_offset.scaled(self.scale_factor)

src/utils/color.py

@@ -11,6 +11,7 @@ These utilities are shared across:
 """
 
 import logging
+from typing import Any
 
 import cv2
 import numpy as np
@@ -18,7 +19,7 @@ import numpy as np
 logger = logging.getLogger(__name__)
 
 
-def detect_red_digits(region: np.ndarray) -> bool:
+def detect_red_digits(region: np.ndarray[Any, Any]) -> bool:
     """
     Detect if the play clock digits are red.
 
@@ -31,13 +32,13 @@ def detect_red_digits(region: np.ndarray) -> bool:
     Returns:
         True if red digits detected, False otherwise
     """
-    # Split into BGR channels
+    # Split into BGR channels (np.asarray normalizes cv2.Mat type for numpy)
     b, g, r = cv2.split(region)
 
     # Calculate mean values for each channel
-    r_mean = np.mean(r)
-    g_mean = np.mean(g)
-    b_mean = np.mean(b)
+    r_mean = np.mean(np.asarray(r))
+    g_mean = np.mean(np.asarray(g))
+    b_mean = np.mean(np.asarray(b))
 
     # Red digits: high red channel, very low green/blue, red > 2x green
     max_gb = max(g_mean, b_mean)
@@ -49,7 +50,7 @@ def detect_red_digits(region: np.ndarray) -> bool:
     return is_red
 
 
-def normalize_to_grayscale(region: np.ndarray) -> np.ndarray:
+def normalize_to_grayscale(region: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
     """
     Normalize a play clock region to grayscale, handling both red and white digits.
 

src/utils/regions.py

@@ -13,13 +13,15 @@ These utilities are shared across:
 - setup/template_builder.py (template building)
 """
 
+from typing import Any
+
 import cv2
 import numpy as np
 
 from .color import normalize_to_grayscale
 
 
-def extract_left_region(preprocessed: np.ndarray) -> np.ndarray:
+def extract_left_region(preprocessed: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
     """
     Extract left region for tens digit in double-digit displays.
 
@@ -34,7 +36,7 @@ def extract_left_region(preprocessed: np.ndarray) -> np.ndarray:
     return preprocessed[:, : mid_x - 2]  # Small gap in middle
 
 
-def extract_right_region(preprocessed: np.ndarray) -> np.ndarray:
+def extract_right_region(preprocessed: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
     """
     Extract right region for ones digit in double-digit displays.
 
@@ -49,7 +51,7 @@ def extract_right_region(preprocessed: np.ndarray) -> np.ndarray:
     return preprocessed[:, mid_x + 2 :]
 
 
-def extract_center_region(preprocessed: np.ndarray) -> np.ndarray:
+def extract_center_region(preprocessed: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
     """
     Extract center region for ones digit in single-digit displays.
 
@@ -67,7 +69,7 @@ def extract_center_region(preprocessed: np.ndarray) -> np.ndarray:
     return preprocessed[:, center_start:center_end]
 
 
-def extract_far_left_region(preprocessed: np.ndarray) -> np.ndarray:
+def extract_far_left_region(preprocessed: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
     """
     Extract far left region for blank detection in single-digit displays.
 
@@ -85,7 +87,7 @@ def extract_far_left_region(preprocessed: np.ndarray) -> np.ndarray:
     return preprocessed[:, :far_left_end]
 
 
-def preprocess_playclock_region(region: np.ndarray, scale_factor: int = 4) -> np.ndarray:
+def preprocess_playclock_region(region: np.ndarray[Any, Any], scale_factor: int = 4) -> np.ndarray[Any, Any]:
     """
     Preprocess play clock region for template matching or building.
 
@@ -109,7 +111,7 @@ def preprocess_playclock_region(region: np.ndarray, scale_factor: int = 4) -> np
     _, binary = cv2.threshold(scaled, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
 
     # Ensure white digits on black background (digits should be bright)
-    mean_intensity = np.mean(binary)
+    mean_intensity = np.mean(np.asarray(binary))
     if mean_intensity > 128:
         binary = cv2.bitwise_not(binary)
 

src/video/frame_extractor.py

@@ -7,7 +7,7 @@ getting video metadata, and other video-related utilities.
 
 import logging
 import subprocess
-from typing import Callable, List, Optional, Tuple
+from typing import Any, Callable, List, Optional, Tuple
 
 import cv2
 import numpy as np
@@ -87,7 +87,7 @@ def get_video_frame_count(video_path: str) -> int:
     return frame_count
 
 
-def extract_sample_frames(video_path: str, start_time: float, num_frames: int = 5, interval: float = 2.0) -> List[Tuple[float, np.ndarray]]:
+def extract_sample_frames(video_path: str, start_time: float, num_frames: int = 5, interval: float = 2.0) -> List[Tuple[float, np.ndarray[Any, Any]]]:
     """
     Extract sample frames from a video file at specified intervals.
 
@@ -126,7 +126,7 @@ def extract_sample_frames(video_path: str, start_time: float, num_frames: int =
     return frames
 
 
-def extract_frame_at_time(video_path: str, timestamp: float) -> Optional[np.ndarray]:
+def extract_frame_at_time(video_path: str, timestamp: float) -> Optional[np.ndarray[Any, Any]]:
     """
     Extract a single frame from a video at a specific timestamp.
 
@@ -161,7 +161,7 @@ def extract_frames_with_callback(
     start_time: float,
     end_time: Optional[float],
     interval: float,
-    callback: Callable[[float, np.ndarray], bool],
+    callback: Callable[[float, np.ndarray[Any, Any]], bool],
 ) -> int:
     """
     Extract frames from a video and call a callback function for each frame.
@@ -175,7 +175,7 @@ def extract_frames_with_callback(
         end_time: End time in seconds, or None to process until end.
         interval: Time interval between frames in seconds.
         callback: Function to call for each frame. Signature:
-                  callback(timestamp: float, frame: np.ndarray) -> bool
+                  callback(timestamp: float, frame: np.ndarray[Any, Any]) -> bool
                   Return False to stop processing early.
 
     Returns:

src/video/frame_reader.py

@@ -9,7 +9,7 @@ import logging
 import queue
 import threading
 import time
-from typing import Optional, Tuple
+from typing import Any, Optional, Tuple
 
 import cv2
 import numpy as np
@@ -45,8 +45,8 @@ class ThreadedFrameReader:
         self.frame_skip = frame_skip
         self.queue_size = queue_size
 
-        # Frame queue: (frame_number, frame_data) or (frame_number, None) for read failures
-        self.frame_queue: queue.Queue = queue.Queue(maxsize=queue_size)
+        # Frame queue: (frame_number, frame_data) or None as end-of-stream sentinel
+        self.frame_queue: queue.Queue[Tuple[int, np.ndarray[Any, Any] | None] | None] = queue.Queue(maxsize=queue_size)
 
         # Control flags
         self.stop_flag = threading.Event()
@@ -76,7 +76,7 @@ class ThreadedFrameReader:
             self.reader_thread.join(timeout=2.0)
         logger.debug("Threaded frame reader stopped (read %d frames, %.2fs I/O)", self.frames_read, self.io_time)
 
-    def get_frame(self, timeout: float = 5.0) -> Optional[Tuple[int, Optional[np.ndarray]]]:
+    def get_frame(self, timeout: float = 5.0) -> Optional[Tuple[int, Optional[np.ndarray[Any, Any]]]]:
         """
         Get the next frame from the queue.