cleaning up pylint

src/detection/scorebug.py

@@ -78,6 +78,11 @@ class DetectScoreBug:
         if self._use_fixed_region:
             logger.info("  Fixed region: %s", self.fixed_region)
 
+    @property
+    def is_fixed_region_mode(self) -> bool:
+        """Check if detector is using fixed region mode for faster detection."""
+        return self._use_fixed_region
+
     def _load_fixed_region_config(self, config_path: str) -> None:
         """Load fixed region from a JSON config file."""
         path = Path(config_path)

src/pipeline/models.py

@@ -88,6 +88,23 @@ class DetectionResult(BaseModel):
 # =============================================================================
 
 
+class ParallelProcessingConfig(BaseModel):
+    """Configuration for parallel video chunk processing.
+
+    This model groups the configuration parameters needed by parallel processing
+    functions, reducing the number of individual arguments.
+    """
+
+    video_path: str = Field(..., description="Path to video file")
+    start_time: float = Field(..., description="Start time in seconds")
+    end_time: float = Field(..., description="End time in seconds")
+    frame_interval: float = Field(..., description="Time interval between frames")
+    fixed_playclock_coords: Tuple[int, int, int, int] = Field(..., description="(x, y, w, h) for play clock region")
+    fixed_scorebug_coords: Tuple[int, int, int, int] = Field(..., description="(x, y, w, h) for scorebug region")
+    template_library_path: Optional[str] = Field(None, description="Path to template library directory")
+    timeout_config_path: Optional[str] = Field(None, description="Path to timeout tracker config")
+
+
 class ChunkResult(BaseModel):
     """Result from processing a single video chunk in parallel processing.
 

src/pipeline/orchestrator.py

@@ -11,7 +11,7 @@ Supports both sequential and parallel processing modes:
 
 import logging
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict
 
 from config.session import SessionConfig, MIN_PLAY_DURATION
 from detection import DetectTimeouts

src/pipeline/parallel.py

@@ -15,7 +15,8 @@ from multiprocessing import Manager
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
-from .models import ChunkResult
+from utils import create_frame_result
+from .models import ChunkResult, ParallelProcessingConfig
 
 logger = logging.getLogger(__name__)
 
@@ -25,53 +26,58 @@ logger = logging.getLogger(__name__)
 # =============================================================================
 
 
-def _init_chunk_detectors(
-    fixed_playclock_coords: Tuple[int, int, int, int],
-    fixed_scorebug_coords: Tuple[int, int, int, int],
-    template_library_path: Optional[str],
-    timeout_config_path: Optional[str],
-) -> Tuple[Any, Any, Any, Any]:
+def _init_chunk_detectors(config: ParallelProcessingConfig) -> Tuple[Any, Any, Any, Any]:
     """
     Initialize all detection components for a chunk worker.
 
     Must be called within the subprocess since these objects can't be pickled.
 
+    Note: Imports are inside this function because multiprocessing requires
+    fresh imports in each worker process. Moving these to module level would
+    cause pickling errors when spawning workers.
+
     Args:
-        fixed_playclock_coords: (x, y, w, h) for play clock region.
-        fixed_scorebug_coords: (x, y, w, h) for scorebug region.
-        template_library_path: Path to template library directory.
-        timeout_config_path: Path to timeout tracker config.
+        config: Parallel processing configuration.
 
     Returns:
         Tuple of (scorebug_detector, clock_reader, template_reader, timeout_tracker).
     """
+    # pylint: disable=import-outside-toplevel
+    # Imports must be inside function for multiprocessing - each subprocess
+    # needs its own fresh imports of these modules to avoid pickling errors
     from detection import DetectScoreBug, DetectTimeouts
     from readers import ReadPlayClock
     from setup import DigitTemplateLibrary, PlayClockRegionConfig, PlayClockRegionExtractor
 
     # Create scorebug detector with fixed region
     scorebug_detector = DetectScoreBug(template_path=None, use_split_detection=True)
-    scorebug_detector.set_fixed_region(fixed_scorebug_coords)
+    scorebug_detector.set_fixed_region(config.fixed_scorebug_coords)
 
     # Create play clock region extractor
-    pc_x, pc_y, pc_w, pc_h = fixed_playclock_coords
-    sb_x, sb_y, _, _ = fixed_scorebug_coords
-    x_offset = pc_x - sb_x
-    y_offset = pc_y - sb_y
-    playclock_config = PlayClockRegionConfig(x_offset=x_offset, y_offset=y_offset, width=pc_w, height=pc_h, source_video="", scorebug_template="", samples_used=0)
+    pc_x, pc_y, pc_w, pc_h = config.fixed_playclock_coords
+    sb_x, sb_y, _, _ = config.fixed_scorebug_coords
+    playclock_config = PlayClockRegionConfig(
+        x_offset=pc_x - sb_x,
+        y_offset=pc_y - sb_y,
+        width=pc_w,
+        height=pc_h,
+        source_video="",
+        scorebug_template="",
+        samples_used=0,
+    )
     clock_reader = PlayClockRegionExtractor(region_config=playclock_config)
 
     # Create template reader if template path provided
     template_reader = None
-    if template_library_path and Path(template_library_path).exists():
+    if config.template_library_path and Path(config.template_library_path).exists():
         template_library = DigitTemplateLibrary()
-        if template_library.load(template_library_path):
+        if template_library.load(config.template_library_path):
             template_reader = ReadPlayClock(template_library, pc_w, pc_h)
 
     # Initialize timeout tracker if config provided
     timeout_tracker = None
-    if timeout_config_path and Path(timeout_config_path).exists():
-        timeout_tracker = DetectTimeouts(config_path=timeout_config_path)
+    if config.timeout_config_path and Path(config.timeout_config_path).exists():
+        timeout_tracker = DetectTimeouts(config_path=config.timeout_config_path)
 
     return scorebug_detector, clock_reader, template_reader, timeout_tracker
 
@@ -103,15 +109,12 @@ def _process_frame(
     # Detect scorebug (fast path with fixed region)
     scorebug = scorebug_detector.detect(img)
 
-    frame_result = {
-        "timestamp": timestamp,
-        "scorebug_detected": scorebug.detected,
-        "scorebug_bbox": scorebug.bbox if scorebug.detected else None,
-        "home_timeouts": None,
-        "away_timeouts": None,
-        "clock_value": None,
-        "clock_detected": False,
-    }
+    # Initialize frame result using shared factory
+    frame_result = create_frame_result(
+        timestamp=timestamp,
+        scorebug_detected=scorebug.detected,
+        scorebug_bbox=scorebug.bbox if scorebug.detected else None,
+    )
 
     if scorebug.detected:
         stats["frames_with_scorebug"] += 1
@@ -123,7 +126,7 @@ def _process_frame(
             frame_result["away_timeouts"] = timeout_reading.away_timeouts
 
         # Extract play clock region and template match
-        play_clock_region = clock_reader._extract_region(img, scorebug.bbox)
+        play_clock_region = clock_reader.extract_region(img, scorebug.bbox)
         if play_clock_region is not None and template_reader:
             clock_result = template_reader.read(play_clock_region)
             frame_result["clock_detected"] = clock_result.detected
@@ -134,16 +137,50 @@ def _process_frame(
     return frame_result
 
 
+def _read_video_frames(cap: Any, start_frame: int, end_frame: int, frame_skip: int, fps: float) -> Tuple[List[Tuple[float, Any]], float]:
+    """
+    Read frames from video capture within the given range.
+
+    Args:
+        cap: OpenCV VideoCapture object.
+        start_frame: First frame to read.
+        end_frame: Last frame to read.
+        frame_skip: Number of frames to skip between samples.
+        fps: Video frames per second.
+
+    Returns:
+        Tuple of (list of (timestamp, frame) tuples, total_io_time).
+    """
+    frames = []
+    io_time = 0.0
+    current_frame = start_frame
+
+    while current_frame < end_frame:
+        t_io_start = time.perf_counter()
+        ret, img = cap.read()
+        io_time += time.perf_counter() - t_io_start
+
+        if not ret:
+            break
+
+        timestamp = current_frame / fps
+        frames.append((timestamp, img))
+
+        # Skip to next sample frame
+        t_io_start = time.perf_counter()
+        for _ in range(frame_skip - 1):
+            cap.grab()
+        io_time += time.perf_counter() - t_io_start
+        current_frame += frame_skip
+
+    return frames, io_time
+
+# pylint: disable=too-many-locals
 def _process_chunk(
     chunk_id: int,
-    video_path: str,
-    start_time: float,
-    end_time: float,
-    frame_interval: float,
-    fixed_playclock_coords: Tuple[int, int, int, int],
-    fixed_scorebug_coords: Tuple[int, int, int, int],
-    template_library_path: Optional[str],
-    timeout_config_path: Optional[str],
+    config: ParallelProcessingConfig,
+    chunk_start: float,
+    chunk_end: float,
     progress_dict: Optional[Dict] = None,
 ) -> ChunkResult:
     """
@@ -154,47 +191,41 @@ def _process_chunk(
 
     Args:
         chunk_id: Identifier for this chunk (for logging).
-        video_path: Path to video file.
-        start_time: Chunk start time in seconds.
-        end_time: Chunk end time in seconds.
-        frame_interval: Time interval between frames.
-        fixed_playclock_coords: (x, y, w, h) for play clock region.
-        fixed_scorebug_coords: (x, y, w, h) for scorebug region.
-        template_library_path: Path to template library directory (or None).
-        timeout_config_path: Path to timeout tracker config (or None).
+        config: Parallel processing configuration.
+        chunk_start: Chunk start time in seconds.
+        chunk_end: Chunk end time in seconds.
         progress_dict: Shared dictionary for progress updates.
 
     Returns:
         ChunkResult with processing results.
     """
-    # Import cv2 here to avoid issues with multiprocessing
+    # pylint: disable=import-outside-toplevel
+    # cv2 import must be inside function for multiprocessing - each subprocess
+    # needs its own fresh import to avoid issues with OpenCV's internal state
     import cv2
 
     t_start = time.perf_counter()
-    io_time = 0.0
 
     # Initialize all detection components
-    scorebug_detector, clock_reader, template_reader, timeout_tracker = _init_chunk_detectors(
-        fixed_playclock_coords, fixed_scorebug_coords, template_library_path, timeout_config_path
-    )
+    scorebug_detector, clock_reader, template_reader, timeout_tracker = _init_chunk_detectors(config)
 
     # Open video and seek to start
     t_io_start = time.perf_counter()
-    cap = cv2.VideoCapture(video_path)
+    cap = cv2.VideoCapture(config.video_path)
     if not cap.isOpened():
-        raise RuntimeError(f"Could not open video: {video_path}")
+        raise RuntimeError(f"Could not open video: {config.video_path}")
 
     fps = cap.get(cv2.CAP_PROP_FPS)
-    frame_skip = int(frame_interval * fps)
-    start_frame = int(start_time * fps)
-    end_frame = int(end_time * fps)
+    frame_skip = int(config.frame_interval * fps)
+    start_frame = int(chunk_start * fps)
+    end_frame = int(chunk_end * fps)
     cap.set(cv2.CAP_PROP_POS_FRAMES, start_frame)
-    io_time += time.perf_counter() - t_io_start
+    io_time = time.perf_counter() - t_io_start
 
     # Initialize processing state
     frame_data: List[Dict[str, Any]] = []
     stats = {"total_frames": 0, "frames_with_scorebug": 0, "frames_with_clock": 0}
-    total_expected_frames = max(1, int((end_time - start_time) / frame_interval))
+    total_expected_frames = max(1, int((chunk_end - chunk_start) / config.frame_interval))
 
     # Initialize progress
     if progress_dict is not None:
@@ -236,8 +267,8 @@ def _process_chunk(
 
     return ChunkResult(
         chunk_id=chunk_id,
-        start_time=start_time,
-        end_time=end_time,
+        start_time=chunk_start,
+        end_time=chunk_end,
         frames_processed=stats["total_frames"],
         frames_with_scorebug=stats["frames_with_scorebug"],
         frames_with_clock=stats["frames_with_clock"],
@@ -337,7 +368,8 @@ def _display_progress(progress_dict: Dict, num_workers: int) -> None:
     overall_pct = min(100, int(100 * total_frames_done / total_frames_expected)) if total_frames_expected > 0 else 0
     progress_str = " | ".join(parts)
 
-    if completed_workers > 0 and completed_workers < num_workers:
+    # Use chained comparison for cleaner code
+    if 0 < completed_workers < num_workers:
         remaining = num_workers - completed_workers
         status_msg = f"  [{overall_pct:3d}%] {progress_str} — waiting for {remaining} worker{'s' if remaining > 1 else ''}..."
     elif completed_workers == num_workers:
@@ -352,12 +384,7 @@ def _display_progress(progress_dict: Dict, num_workers: int) -> None:
 def _submit_chunk_jobs(
     executor: ProcessPoolExecutor,
     chunks: List[Tuple[int, float, float]],
-    video_path: str,
-    frame_interval: float,
-    fixed_playclock_coords: Tuple[int, int, int, int],
-    fixed_scorebug_coords: Tuple[int, int, int, int],
-    template_library_path: Optional[str],
-    timeout_config_path: Optional[str],
+    config: ParallelProcessingConfig,
     progress_dict: Dict,
 ) -> Dict[Future, int]:
     """
@@ -366,12 +393,7 @@ def _submit_chunk_jobs(
     Args:
         executor: ProcessPoolExecutor instance.
         chunks: List of (chunk_id, start_time, end_time) tuples.
-        video_path: Path to video file.
-        frame_interval: Time between frame samples.
-        fixed_playclock_coords: Play clock region coordinates.
-        fixed_scorebug_coords: Scorebug region coordinates.
-        template_library_path: Path to template library.
-        timeout_config_path: Path to timeout config.
+        config: Parallel processing configuration.
         progress_dict: Shared progress dictionary.
 
     Returns:
@@ -382,14 +404,9 @@ def _submit_chunk_jobs(
         future = executor.submit(
             _process_chunk,
             chunk_id,
-            video_path,
+            config,
             chunk_start,
             chunk_end,
-            frame_interval,
-            fixed_playclock_coords,
-            fixed_scorebug_coords,
-            template_library_path,
-            timeout_config_path,
             progress_dict,
         )
         futures[future] = chunk_id
@@ -458,14 +475,7 @@ def _merge_chunk_results(results: Dict[int, Optional[ChunkResult]], num_workers:
 
 
 def process_video_parallel(
-    video_path: str,
-    start_time: float,
-    end_time: float,
-    frame_interval: float,
-    fixed_playclock_coords: Tuple[int, int, int, int],
-    fixed_scorebug_coords: Tuple[int, int, int, int],
-    template_library_path: Optional[str],
-    timeout_config_path: Optional[str],
+    config: ParallelProcessingConfig,
     num_workers: int = 2,
 ) -> Tuple[List[Dict[str, Any]], Dict[str, int], float]:
     """
@@ -475,22 +485,16 @@ def process_video_parallel(
     Results are merged in chronological order.
 
     Args:
-        video_path: Path to video file.
-        start_time: Start time in seconds.
-        end_time: End time in seconds.
-        frame_interval: Time interval between frames.
-        fixed_playclock_coords: (x, y, w, h) for play clock region.
-        fixed_scorebug_coords: (x, y, w, h) for scorebug region.
-        template_library_path: Path to template library directory.
-        timeout_config_path: Path to timeout tracker config.
+        config: Parallel processing configuration containing video path,
+                time bounds, frame interval, and region coordinates.
         num_workers: Number of parallel workers (default 2).
 
     Returns:
         Tuple of (frame_data_list, stats_dict, total_io_time).
     """
     # Calculate chunk boundaries
-    chunks = _calculate_chunk_boundaries(start_time, end_time, num_workers)
-    chunk_duration = (end_time - start_time) / num_workers
+    chunks = _calculate_chunk_boundaries(config.start_time, config.end_time, num_workers)
+    chunk_duration = (config.end_time - config.start_time) / num_workers
 
     logger.info("Parallel processing: %d workers, %.1fs per chunk", num_workers, chunk_duration)
     for chunk_id, chunk_start, chunk_end in chunks:
@@ -508,9 +512,7 @@ def process_video_parallel(
 
     # Execute chunks in parallel
     with ProcessPoolExecutor(max_workers=num_workers) as executor:
-        futures = _submit_chunk_jobs(
-            executor, chunks, video_path, frame_interval, fixed_playclock_coords, fixed_scorebug_coords, template_library_path, timeout_config_path, progress_dict
-        )
+        futures = _submit_chunk_jobs(executor, chunks, config, progress_dict)
         results = _collect_chunk_results(futures)
 
     # Stop progress monitor and show completion

src/pipeline/play_detector.py

@@ -29,8 +29,9 @@ from detection import DetectScoreBug, ScorebugDetection, DetectTimeouts
 from readers import ReadPlayClock, PlayClockReading
 from setup import DigitTemplateBuilder, DigitTemplateLibrary, PlayClockRegionConfig, PlayClockRegionExtractor
 from tracking import TrackPlayState, PlayEvent, PlayMerger, TimeoutInfo
+from utils import create_frame_result
 from video import ThreadedFrameReader
-from .models import DetectionConfig, DetectionResult, VideoContext
+from .models import DetectionConfig, DetectionResult, ParallelProcessingConfig, VideoContext
 from .parallel import process_video_parallel
 from .template_builder_pass import TemplateBuildingPass
 
@@ -300,7 +301,7 @@ class PlayDetector:
         frame_data: List[Dict[str, Any]] = []
 
         # Flag to track if we've locked the scorebug region
-        scorebug_region_locked = self.scorebug_detector._use_fixed_region if self.scorebug_detector else False
+        scorebug_region_locked = self.scorebug_detector.is_fixed_region_mode if self.scorebug_detector else False
 
         # Progress tracking
         progress_interval = int(30 / self.config.frame_interval)  # Log every 30 seconds of video
@@ -383,16 +384,12 @@ class PlayDetector:
         scorebug = self.scorebug_detector.detect(frame)
         timing["scorebug_detection"] += time.perf_counter() - t_start
 
-        # Initialize frame result
-        frame_result = {
-            "timestamp": current_time,
-            "scorebug_detected": scorebug.detected,
-            "scorebug_bbox": scorebug.bbox if scorebug.detected else None,
-            "home_timeouts": None,
-            "away_timeouts": None,
-            "clock_value": None,
-            "clock_detected": False,
-        }
+        # Initialize frame result using shared factory
+        frame_result = create_frame_result(
+            timestamp=current_time,
+            scorebug_detected=scorebug.detected,
+            scorebug_bbox=scorebug.bbox if scorebug.detected else None,
+        )
 
         # Initialize timeout_info for state machine
         timeout_info = None
@@ -449,7 +446,6 @@ class PlayDetector:
 
     def _finalize_detection(
         self,
-        frame_data: List[Dict[str, Any]],  # pylint: disable=unused-argument
         context: VideoContext,
         stats: Dict[str, Any],
         timing: Dict[str, float],
@@ -461,7 +457,6 @@ class PlayDetector:
         the streaming pass, so we just need to merge/filter and build the result.
 
         Args:
-            frame_data: Complete frame data from streaming detection pass (unused, kept for API compatibility)
             context: Video context
             stats: Processing stats
             timing: Timing breakdown
@@ -570,11 +565,13 @@ class PlayDetector:
 
         # Streaming detection pass: read frames + template match + state machine (all in one)
         # Uses threaded video I/O to overlap reading with processing
-        frame_data = self._streaming_detection_pass(context, stats, timing)
+        # Note: Return value unused - state machine is updated inline during the pass
+        _ = self._streaming_detection_pass(context, stats, timing)
 
         # Finalize: Clock reset classification and result building
-        return self._finalize_detection(frame_data, context, stats, timing)
+        return self._finalize_detection(context, stats, timing)
 
+    # pylint: disable=too-many-locals
     def detect_parallel(self, num_workers: int = 2, output_dir: Optional[Path] = None) -> DetectionResult:
         """
         Run play detection using parallel chunk processing.
@@ -596,8 +593,6 @@ class PlayDetector:
         Returns:
             DetectionResult with all detected plays
         """
-        import time as time_module
-
         logger.info("Starting parallel play detection (%d workers)...", num_workers)
         logger.info("Video: %s", self.config.video_path)
         logger.info("Segment: %.1fs to %s", self.config.start_time, self.config.end_time or "end")
@@ -643,9 +638,10 @@ class PlayDetector:
 
         # Run parallel processing
         logger.info("Starting parallel frame extraction...")
-        t_parallel_start = time_module.perf_counter()
+        t_parallel_start = time.perf_counter()
 
-        frame_data, stats, io_time = process_video_parallel(
+        # Create parallel processing config
+        parallel_config = ParallelProcessingConfig(
             video_path=self.config.video_path,
             start_time=self.config.start_time,
             end_time=end_time,
@@ -654,12 +650,13 @@ class PlayDetector:
             fixed_scorebug_coords=self.config.fixed_scorebug_coords,
             template_library_path=str(template_path) if template_path else None,
             timeout_config_path=timeout_config_path,
-            num_workers=num_workers,
         )
 
+        frame_data, stats, io_time = process_video_parallel(parallel_config, num_workers=num_workers)
+
         timing["video_io"] = io_time
         # Estimate template matching time from parallel processing
-        parallel_time = time_module.perf_counter() - t_parallel_start
+        parallel_time = time.perf_counter() - t_parallel_start
         timing["template_matching"] = max(0, parallel_time - io_time - timing["template_building"])
 
         logger.info("Parallel processing complete: %d frames", stats["total_frames"])
@@ -678,7 +675,7 @@ class PlayDetector:
         )
 
         # Run state machine on merged frame data
-        t_sm_start = time_module.perf_counter()
+        t_sm_start = time.perf_counter()
         for frame in frame_data:
             # Create proper objects for state machine
             scorebug = ScorebugDetection(
@@ -700,7 +697,7 @@ class PlayDetector:
                     away_timeouts=frame.get("away_timeouts"),
                 )
             self.state_machine.update(frame["timestamp"], scorebug, clock_reading, timeout_info)
-        timing["state_machine"] = time_module.perf_counter() - t_sm_start
+        timing["state_machine"] = time.perf_counter() - t_sm_start
 
         # Update stats dict
         stats_dict = {
@@ -710,11 +707,11 @@ class PlayDetector:
         }
 
         # Finalize: Clock reset classification and result building
-        return self._finalize_detection(frame_data, context, stats_dict, timing)
+        return self._finalize_detection(context, stats_dict, timing)
 
     def _log_detection_mode(self) -> None:
         """Log the detection mode being used."""
-        use_fixed_region = self.scorebug_detector and self.scorebug_detector._use_fixed_region
+        use_fixed_region = self.scorebug_detector and self.scorebug_detector.is_fixed_region_mode
 
         if use_fixed_region:
             logger.info("Mode: Fixed region (scorebug location pre-configured)")

src/pipeline/template_builder_pass.py

@@ -4,15 +4,21 @@ Template building pass (Pass 0) for the play detection pipeline.
 This module handles the initial phase of building digit templates by scanning
 the video for frames with scorebugs and running OCR on the play clock region.
 These templates are then used for fast template matching in subsequent passes.
+
+Note: This module uses functions instead of a class because there is only one
+public entry point (run_template_building_pass). The class pattern was causing
+"too few public methods" warnings.
 """
 
 import logging
 import time
+from functools import lru_cache
 from pathlib import Path
-from typing import Dict, Optional, Tuple
+from typing import Optional, Tuple
 
 import cv2
 import easyocr
+import numpy as np
 
 from detection import DetectScoreBug
 from readers import ReadPlayClock
@@ -21,23 +27,186 @@ from .models import DetectionConfig
 
 logger = logging.getLogger(__name__)
 
-# Global EasyOCR reader instance for template building (lazy-loaded)
-_easyocr_reader = None  # pylint: disable=invalid-name
-
 
+@lru_cache(maxsize=1)
 def get_easyocr_reader() -> easyocr.Reader:
-    """Get or create the global EasyOCR reader instance for template building."""
-    global _easyocr_reader  # pylint: disable=global-statement
-    if _easyocr_reader is None:
-        logger.info("Initializing EasyOCR reader for template building...")
-        _easyocr_reader = easyocr.Reader(["en"], gpu=False, verbose=False)
-        logger.info("EasyOCR reader initialized")
-    return _easyocr_reader
+    """Get or create the EasyOCR reader instance (lazily loaded, cached)."""
+    logger.info("Initializing EasyOCR reader for template building...")
+    reader = easyocr.Reader(["en"], gpu=False, verbose=False)
+    logger.info("EasyOCR reader initialized")
+    return reader
+
+
+def _validate_config(config: DetectionConfig) -> bool:
+    """Validate that required configuration is present for template building."""
+    if not config.template_path:
+        logger.warning("Pass 0: No scorebug template path provided, cannot detect scorebugs")
+        return False
+
+    template_path = Path(config.template_path)
+    if not template_path.exists():
+        logger.warning("Pass 0: Scorebug template not found at %s", template_path)
+        return False
+
+    if not config.fixed_scorebug_coords:
+        logger.warning("Pass 0: No fixed scorebug coordinates provided")
+        return False
+
+    return True
+
+
+def _process_scorebug_frame(
+    frame: np.ndarray,
+    scorebug_bbox: Tuple[int, int, int, int],
+    current_time: float,
+    clock_reader: PlayClockRegionExtractor,
+    template_builder: DigitTemplateBuilder,
+    reader: easyocr.Reader,
+) -> int:
+    """
+    Process a frame with detected scorebug and extract play clock via OCR.
+
+    Args:
+        frame: Video frame
+        scorebug_bbox: Scorebug bounding box (x, y, w, h)
+        current_time: Current timestamp
+        clock_reader: Play clock region extractor
+        template_builder: Digit template builder
+        reader: EasyOCR reader
+
+    Returns:
+        1 if a valid sample was collected, 0 otherwise
+    """
+    # Extract play clock region
+    play_clock_region = clock_reader.extract_region(frame, scorebug_bbox)
+    if play_clock_region is None:
+        return 0
+
+    # Preprocess and run OCR
+    preprocessed = clock_reader.preprocess_for_ocr(play_clock_region)
 
+    try:
+        ocr_results = reader.readtext(preprocessed, allowlist="0123456789", detail=1)
+        if not ocr_results:
+            return 0
 
-class TemplateBuildingPass:
+        best = max(ocr_results, key=lambda x: x[2])
+        text, confidence = best[1].strip(), best[2]
+
+        # Parse and validate
+        if text and confidence >= 0.5:
+            try:
+                value = int(text)
+                if 0 <= value <= 40:
+                    template_builder.add_sample(play_clock_region, value, current_time, confidence)
+                    return 1
+            except ValueError:
+                pass  # Invalid text, skip
+
+    except Exception as e:  # pylint: disable=broad-except
+        logger.debug("Pass 0: OCR error at %.1fs: %s", current_time, e)
+
+    return 0
+
+
+def _scan_video(
+    config: DetectionConfig,
+    clock_reader: PlayClockRegionExtractor,
+    template_builder: DigitTemplateBuilder,
+    temp_detector: DetectScoreBug,
+    reader: easyocr.Reader,
+    min_samples: int,
+    max_scan_frames: int,
+    target_coverage: float,
+) -> Tuple[int, int, int]:
     """
-    Build digit templates by scanning video using template-based scorebug detection.
+    Scan video frames and collect OCR samples for template building.
+
+    Args:
+        config: Detection configuration
+        clock_reader: Play clock region extractor
+        template_builder: Digit template builder
+        temp_detector: Scorebug detector to use
+        reader: EasyOCR reader instance
+        min_samples: Minimum valid OCR samples to collect
+        max_scan_frames: Maximum frames to scan
+        target_coverage: Target template coverage (0.0-1.0)
+
+    Returns:
+        Tuple of (valid_samples, frames_scanned, frames_with_scorebug)
+    """
+    # Open video
+    cap = cv2.VideoCapture(config.video_path)
+    if not cap.isOpened():
+        logger.error("Pass 0: Could not open video")
+        return 0, 0, 0
+
+    fps = cap.get(cv2.CAP_PROP_FPS)
+    frame_skip = int(config.frame_interval * fps)
+
+    # Initialize counters
+    valid_samples = 0
+    frames_scanned = 0
+    frames_with_scorebug = 0
+    current_frame = 0
+
+    cap.set(cv2.CAP_PROP_POS_FRAMES, 0)
+    logger.info("  Scanning from frame 0 (0.0s)...")
+
+    try:
+        while frames_scanned < max_scan_frames:
+            ret, frame = cap.read()
+            if not ret:
+                break
+
+            current_time = current_frame / fps
+            frames_scanned += 1
+
+            # Detect scorebug using template matching
+            scorebug_result = temp_detector.detect(frame)
+
+            if scorebug_result.detected:
+                frames_with_scorebug += 1
+                valid_samples += _process_scorebug_frame(frame, scorebug_result.bbox, current_time, clock_reader, template_builder, reader)
+
+            # Progress logging every 200 frames
+            if frames_scanned % 200 == 0:
+                coverage = template_builder.get_coverage_estimate()
+                logger.info(
+                    "  Pass 0 progress: %d frames scanned, %d with scorebug, %d valid samples, ~%.0f%% coverage",
+                    frames_scanned,
+                    frames_with_scorebug,
+                    valid_samples,
+                    coverage * 100,
+                )
+
+                # Check completion criteria
+                if valid_samples >= min_samples or coverage >= target_coverage:
+                    logger.info("  Completion criteria met!")
+                    break
+
+            # Skip frames
+            for _ in range(frame_skip - 1):
+                cap.grab()
+            current_frame += frame_skip
+
+    finally:
+        cap.release()
+
+    return valid_samples, frames_scanned, frames_with_scorebug
+
+
+# pylint: disable=too-many-locals
+def run_template_building_pass(
+    config: DetectionConfig,
+    clock_reader: PlayClockRegionExtractor,
+    template_builder: DigitTemplateBuilder,
+    min_samples: int = 200,
+    max_scan_frames: int = 2000,
+    target_coverage: float = 0.70,
+) -> Tuple[Optional[DigitTemplateLibrary], Optional[ReadPlayClock], float]:
+    """
+    Run the template building pass (Pass 0).
 
     This pass runs BEFORE the main detection loop. It:
     1. Uses the scorebug template (created during user setup) for detection
@@ -47,6 +216,89 @@ class TemplateBuildingPass:
 
     This solves the problem of building templates from pre-game content that
     has no scorebug, which causes all subsequent template matching to fail.
+
+    Args:
+        config: Detection configuration
+        clock_reader: Play clock region extractor
+        template_builder: Digit template builder
+        min_samples: Minimum valid OCR samples to collect (default: 200)
+        max_scan_frames: Maximum frames to scan (default: 2000)
+        target_coverage: Target template coverage 0.0-1.0 (default: 0.70)
+
+    Returns:
+        Tuple of (template_library, template_reader, build_time).
+        template_library and template_reader may be None if building failed.
+    """
+    logger.info("Pass 0: Building templates using scorebug template detection...")
+    logger.info("  Target: %d samples OR %.0f%% template coverage", min_samples, target_coverage * 100)
+
+    t_build_start = time.perf_counter()
+
+    # Validate configuration
+    if not _validate_config(config):
+        return None, None, time.perf_counter() - t_build_start
+
+    # 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)
+    logger.info("  Scorebug template: %s", config.template_path)
+
+    temp_detector = DetectScoreBug(
+        template_path=str(config.template_path),
+        fixed_region=(sb_x, sb_y, sb_w, sb_h),
+        use_split_detection=config.use_split_detection,
+    )
+
+    # Get EasyOCR reader for labeling
+    reader = get_easyocr_reader()
+
+    # Scan video and collect samples
+    valid_samples, frames_scanned, frames_with_scorebug = _scan_video(config, clock_reader, template_builder, temp_detector, reader, min_samples, max_scan_frames, target_coverage)
+
+    # Log scan results
+    logger.info(
+        "Pass 0 scan complete: %d frames, %d with scorebug (%.1f%%), %d valid samples",
+        frames_scanned,
+        frames_with_scorebug,
+        100 * frames_with_scorebug / max(1, frames_scanned),
+        valid_samples,
+    )
+
+    # Check if we have enough samples
+    if valid_samples < 50:
+        logger.warning("Pass 0: Insufficient samples (%d < 50), template building may fail", valid_samples)
+        if frames_with_scorebug == 0:
+            logger.error("Pass 0: No scorebugs detected! Check that the scorebug template matches the video.")
+            return None, None, time.perf_counter() - t_build_start
+
+    # Build templates
+    template_library = template_builder.build_templates(min_samples=2)
+    coverage = template_library.get_coverage_status()
+    logger.info(
+        "Pass 0 templates built: %d/%d (%.1f%%) coverage",
+        coverage["total_have"],
+        coverage["total_needed"],
+        100 * coverage["total_have"] / coverage["total_needed"],
+    )
+
+    # Create template reader
+    region_w = clock_reader.config.width if clock_reader.config else 50
+    region_h = clock_reader.config.height if clock_reader.config else 28
+    template_reader = ReadPlayClock(template_library, region_w, region_h)
+
+    build_time = time.perf_counter() - t_build_start
+    logger.info("Pass 0 complete: Template building took %.2fs", build_time)
+
+    return template_library, template_reader, build_time
+
+
+# Keep the class for backward compatibility, but it now delegates to the function
+class TemplateBuildingPass:  # pylint: disable=too-few-public-methods
+    """
+    Backward-compatible class wrapper for run_template_building_pass.
+
+    Deprecated: Use run_template_building_pass() function directly instead.
+    This class exists only for backward compatibility with existing code.
     """
 
     def __init__(
@@ -58,17 +310,7 @@ class TemplateBuildingPass:
         max_scan_frames: int = 2000,
         target_coverage: float = 0.70,
     ):
-        """
-        Initialize the template building pass.
-
-        Args:
-            config: Detection configuration
-            clock_reader: Play clock region extractor
-            template_builder: Digit template builder
-            min_samples: Minimum valid OCR samples to collect
-            max_scan_frames: Maximum frames to scan
-            target_coverage: Target template coverage (0.0-1.0)
-        """
+        """Initialize the template building pass."""
         self.config = config
         self.clock_reader = clock_reader
         self.template_builder = template_builder
@@ -77,203 +319,12 @@ class TemplateBuildingPass:
         self.target_coverage = target_coverage
 
     def run(self) -> Tuple[Optional[DigitTemplateLibrary], Optional[ReadPlayClock], float]:
-        """
-        Run the template building pass.
-
-        Returns:
-            Tuple of (template_library, template_reader, build_time).
-            template_library and template_reader may be None if building failed.
-        """
-        logger.info("Pass 0: Building templates using scorebug template detection...")
-        logger.info("  Target: %d samples OR %.0f%% template coverage", self.min_samples, self.target_coverage * 100)
-
-        t_build_start = time.perf_counter()
-
-        # Validate configuration
-        if not self._validate_config():
-            return None, None, time.perf_counter() - t_build_start
-
-        # Create temporary scorebug detector for Pass 0
-        sb_x, sb_y, sb_w, sb_h = self.config.fixed_scorebug_coords
-        logger.info("  Scorebug region: (%d, %d, %d, %d)", sb_x, sb_y, sb_w, sb_h)
-        logger.info("  Scorebug template: %s", self.config.template_path)
-
-        temp_detector = DetectScoreBug(
-            template_path=str(self.config.template_path),
-            fixed_region=(sb_x, sb_y, sb_w, sb_h),
-            use_split_detection=self.config.use_split_detection,
-        )
-
-        # Get EasyOCR reader for labeling
-        reader = get_easyocr_reader()
-
-        # Scan video and collect samples
-        valid_samples, frames_scanned, frames_with_scorebug = self._scan_video(temp_detector, reader)
-
-        # Log scan results
-        logger.info(
-            "Pass 0 scan complete: %d frames, %d with scorebug (%.1f%%), %d valid samples",
-            frames_scanned,
-            frames_with_scorebug,
-            100 * frames_with_scorebug / max(1, frames_scanned),
-            valid_samples,
-        )
-
-        # Check if we have enough samples
-        if valid_samples < 50:
-            logger.warning("Pass 0: Insufficient samples (%d < 50), template building may fail", valid_samples)
-            if frames_with_scorebug == 0:
-                logger.error("Pass 0: No scorebugs detected! Check that the scorebug template matches the video.")
-                return None, None, time.perf_counter() - t_build_start
-
-        # Build templates
-        template_library = self.template_builder.build_templates(min_samples=2)
-        coverage = template_library.get_coverage_status()
-        logger.info(
-            "Pass 0 templates built: %d/%d (%.1f%%) coverage",
-            coverage["total_have"],
-            coverage["total_needed"],
-            100 * coverage["total_have"] / coverage["total_needed"],
+        """Run the template building pass by delegating to the function."""
+        return run_template_building_pass(
+            self.config,
+            self.clock_reader,
+            self.template_builder,
+            self.min_samples,
+            self.max_scan_frames,
+            self.target_coverage,
         )
-
-        # Create template reader
-        region_w = self.clock_reader.config.width if self.clock_reader.config else 50
-        region_h = self.clock_reader.config.height if self.clock_reader.config else 28
-        template_reader = ReadPlayClock(template_library, region_w, region_h)
-
-        build_time = time.perf_counter() - t_build_start
-        logger.info("Pass 0 complete: Template building took %.2fs", build_time)
-
-        return template_library, template_reader, build_time
-
-    def _validate_config(self) -> bool:
-        """Validate that required configuration is present."""
-        if not self.config.template_path:
-            logger.warning("Pass 0: No scorebug template path provided, cannot detect scorebugs")
-            return False
-
-        template_path = Path(self.config.template_path)
-        if not template_path.exists():
-            logger.warning("Pass 0: Scorebug template not found at %s", template_path)
-            return False
-
-        if not self.config.fixed_scorebug_coords:
-            logger.warning("Pass 0: No fixed scorebug coordinates provided")
-            return False
-
-        return True
-
-    def _scan_video(self, temp_detector: DetectScoreBug, reader: easyocr.Reader) -> Tuple[int, int, int]:
-        """
-        Scan video frames and collect OCR samples for template building.
-
-        Args:
-            temp_detector: Scorebug detector to use
-            reader: EasyOCR reader instance
-
-        Returns:
-            Tuple of (valid_samples, frames_scanned, frames_with_scorebug)
-        """
-        # Open video
-        cap = cv2.VideoCapture(self.config.video_path)
-        if not cap.isOpened():
-            logger.error("Pass 0: Could not open video")
-            return 0, 0, 0
-
-        fps = cap.get(cv2.CAP_PROP_FPS)
-        frame_skip = int(self.config.frame_interval * fps)
-
-        # Initialize counters
-        valid_samples = 0
-        frames_scanned = 0
-        frames_with_scorebug = 0
-        current_frame = 0
-
-        cap.set(cv2.CAP_PROP_POS_FRAMES, 0)
-        logger.info("  Scanning from frame 0 (0.0s)...")
-
-        try:
-            while frames_scanned < self.max_scan_frames:
-                ret, frame = cap.read()
-                if not ret:
-                    break
-
-                current_time = current_frame / fps
-                frames_scanned += 1
-
-                # Detect scorebug using template matching
-                scorebug_result = temp_detector.detect(frame)
-
-                if scorebug_result.detected:
-                    frames_with_scorebug += 1
-                    valid_samples += self._process_scorebug_frame(frame, scorebug_result.bbox, current_time, reader)
-
-                # Progress logging every 200 frames
-                if frames_scanned % 200 == 0:
-                    coverage = self.template_builder.get_coverage_estimate()
-                    logger.info(
-                        "  Pass 0 progress: %d frames scanned, %d with scorebug, %d valid samples, ~%.0f%% coverage",
-                        frames_scanned,
-                        frames_with_scorebug,
-                        valid_samples,
-                        coverage * 100,
-                    )
-
-                    # Check completion criteria
-                    if valid_samples >= self.min_samples or coverage >= self.target_coverage:
-                        logger.info("  Completion criteria met!")
-                        break
-
-                # Skip frames
-                for _ in range(frame_skip - 1):
-                    cap.grab()
-                current_frame += frame_skip
-
-        finally:
-            cap.release()
-
-        return valid_samples, frames_scanned, frames_with_scorebug
-
-    def _process_scorebug_frame(self, frame, scorebug_bbox: Tuple[int, int, int, int], current_time: float, reader: easyocr.Reader) -> int:
-        """
-        Process a frame with detected scorebug and extract play clock via OCR.
-
-        Args:
-            frame: Video frame
-            scorebug_bbox: Scorebug bounding box (x, y, w, h)
-            current_time: Current timestamp
-            reader: EasyOCR reader
-
-        Returns:
-            1 if a valid sample was collected, 0 otherwise
-        """
-        # Extract play clock region
-        play_clock_region = self.clock_reader.extract_region(frame, scorebug_bbox)
-        if play_clock_region is None:
-            return 0
-
-        # Preprocess and run OCR
-        preprocessed = self.clock_reader.preprocess_for_ocr(play_clock_region)
-
-        try:
-            ocr_results = reader.readtext(preprocessed, allowlist="0123456789", detail=1)
-            if not ocr_results:
-                return 0
-
-            best = max(ocr_results, key=lambda x: x[2])
-            text, confidence = best[1].strip(), best[2]
-
-            # Parse and validate
-            if text and confidence >= 0.5:
-                try:
-                    value = int(text)
-                    if 0 <= value <= 40:
-                        self.template_builder.add_sample(play_clock_region, value, current_time, confidence)
-                        return 1
-                except ValueError:
-                    pass  # Invalid text, skip
-
-        except Exception as e:  # pylint: disable=broad-except
-            logger.debug("Pass 0: OCR error at %.1fs: %s", current_time, e)
-
-        return 0

src/readers/__init__.py

@@ -3,6 +3,8 @@
 This package contains components that read values from detected regions:
 - Play clock digit values (via template matching)
 - Future: expanded timeout value reading
+
+Note: detect_red_digits and normalize_to_grayscale are now in utils.color
 """
 
 from .models import (
@@ -12,8 +14,6 @@ from .models import (
 )
 from .playclock import (
     ReadPlayClock,
-    detect_red_digits,
-    normalize_to_grayscale,
     backfill_missing_readings,
 )
 
@@ -24,7 +24,5 @@ __all__ = [
     "TemplatePlayClockReading",
     # Play clock reading
     "ReadPlayClock",
-    "detect_red_digits",
-    "normalize_to_grayscale",
     "backfill_missing_readings",
 ]

src/readers/playclock.py

@@ -1,14 +1,12 @@
-# pylint: disable=too-many-lines,duplicate-code
 """
 Play clock reading via template matching.
 
 This module provides:
 - ReadPlayClock: Fast template-based clock value reading
-- Color normalization utilities for handling red/white digits
 - backfill_missing_readings for gap interpolation
 
-Note: detect_red_digits and normalize_to_grayscale are duplicated in setup/template_builder.py
-to avoid circular imports. Both modules need these utilities independently.
+Color normalization utilities (detect_red_digits, normalize_to_grayscale) are
+now shared from utils.color to eliminate code duplication.
 
 Performance comparison (from ocr_benchmark.md):
 - EasyOCR: 48.9ms/frame
@@ -22,73 +20,12 @@ import cv2
 import numpy as np
 
 from setup import DigitTemplateLibrary
+from utils import extract_center_region, extract_far_left_region, extract_left_region, extract_right_region, preprocess_playclock_region
 from .models import PlayClockReading, TemplateMatchResult, TemplatePlayClockReading
 
 logger = logging.getLogger(__name__)
 
 
-# =============================================================================
-# Color Normalization Utilities
-# =============================================================================
-
-
-def detect_red_digits(region: np.ndarray) -> bool:
-    """
-    Detect if the play clock digits are red.
-
-    Red digits appear when the play clock has 5 seconds or less remaining.
-    Red digits have high red channel values with very low green and blue.
-
-    Args:
-        region: Play clock region (BGR format)
-
-    Returns:
-        True if red digits detected, False otherwise
-    """
-    # Split into BGR channels
-    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)
-
-    # Red digits: high red channel, very low green/blue, red > 2x green
-    # pylint: disable=chained-comparison
-    is_red = r_mean > 15 and max(g_mean, b_mean) < 15 and r_mean > (g_mean * 2)
-
-    if is_red:
-        logger.debug("Red digits detected: R=%.1f, G=%.1f, B=%.1f", r_mean, g_mean, b_mean)
-
-    return is_red
-
-
-def normalize_to_grayscale(region: np.ndarray) -> np.ndarray:
-    """
-    Normalize a play clock region to grayscale, handling both red and white digits.
-
-    Red digits (displayed when clock <= 5) are converted to white-like grayscale
-    by extracting the red channel. White digits use standard grayscale conversion.
-    This allows a single set of templates to match both color variants.
-
-    Args:
-        region: Play clock region (BGR format)
-
-    Returns:
-        Grayscale image where digits appear as bright pixels on dark background
-    """
-    is_red = detect_red_digits(region)
-
-    if is_red:
-        # For red digits, use the red channel directly as grayscale
-        # This converts red digits to white-like appearance
-        _, _, r = cv2.split(region)
-        return r
-
-    # Standard grayscale conversion for white digits
-    return cv2.cvtColor(region, cv2.COLOR_BGR2GRAY)
-
-
 # =============================================================================
 # Template-Based Play Clock Reader
 # =============================================================================
@@ -134,7 +71,7 @@ class ReadPlayClock:
         """
         Preprocess play clock region for template matching.
 
-        Uses color normalization to handle both red and white digits uniformly.
+        Delegates to shared utility function in utils.regions.
 
         Args:
             region: Play clock region (BGR format)
@@ -142,46 +79,7 @@ class ReadPlayClock:
         Returns:
             Preprocessed binary image (scaled up)
         """
-        # Normalize color (red → white conversion)
-        gray = normalize_to_grayscale(region)
-
-        # Scale up to match template resolution
-        scaled = cv2.resize(gray, None, fx=self.scale_factor, fy=self.scale_factor, interpolation=cv2.INTER_LINEAR)
-
-        # Use Otsu's thresholding
-        _, binary = cv2.threshold(scaled, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
-
-        # Ensure white digits on black background
-        mean_intensity = np.mean(binary)
-        if mean_intensity > 128:
-            binary = cv2.bitwise_not(binary)
-
-        return binary
-
-    def _extract_left_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """Extract left region for tens digit."""
-        _, w = preprocessed.shape[:2]
-        mid_x = w // 2
-        return preprocessed[:, : mid_x - 2]
-
-    def _extract_right_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """Extract right region for ones digit in double-digit displays."""
-        _, w = preprocessed.shape[:2]
-        mid_x = w // 2
-        return preprocessed[:, mid_x + 2 :]
-
-    def _extract_center_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """Extract center region for ones digit in single-digit displays."""
-        _, w = preprocessed.shape[:2]
-        center_start = int(w * 0.20)
-        center_end = int(w * 0.80)
-        return preprocessed[:, center_start:center_end]
-
-    def _extract_far_left_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """Extract far left region for blank detection in single-digit displays."""
-        _, w = preprocessed.shape[:2]
-        far_left_end = int(w * 0.20)
-        return preprocessed[:, :far_left_end]
+        return preprocess_playclock_region(region, self.scale_factor)
 
     def match_digit(self, region: np.ndarray, templates: List) -> TemplateMatchResult:
         """
@@ -251,9 +149,9 @@ class ReadPlayClock:
                 method="template_double",
             )
 
-        # Extract regions
-        tens_region = self._extract_left_region(preprocessed)
-        ones_region = self._extract_right_region(preprocessed)
+        # Extract regions using shared utility functions
+        tens_region = extract_left_region(preprocessed)
+        ones_region = extract_right_region(preprocessed)
 
         # Match digits
         tens_match = self.match_digit(tens_region, tens_templates)
@@ -320,9 +218,9 @@ class ReadPlayClock:
                 method="template_single",
             )
 
-        # Extract regions
-        center_region = self._extract_center_region(preprocessed)
-        far_left_region = self._extract_far_left_region(preprocessed)
+        # Extract regions using shared utility functions
+        center_region = extract_center_region(preprocessed)
+        far_left_region = extract_far_left_region(preprocessed)
 
         # Match center digit (ones)
         ones_match = self.match_digit(center_region, ones_templates)
@@ -490,7 +388,104 @@ class ReadPlayClock:
 # =============================================================================
 
 
-def backfill_missing_readings(readings: list[PlayClockReading], max_gap_seconds: int = 3) -> list[PlayClockReading]:
+def _find_gap_extent(readings: List[PlayClockReading], start_idx: int) -> int:
+    """Find the end index of a gap starting at start_idx."""
+    gap_end = start_idx
+    while gap_end < len(readings) and (not readings[gap_end].detected or readings[gap_end].value is None):
+        gap_end += 1
+    return gap_end
+
+
+def _validate_gap_boundaries(readings: List[PlayClockReading], gap_start: int, gap_end: int, max_gap_seconds: int) -> Tuple[bool, int, int, int]:
+    """
+    Validate that a gap can be backfilled.
+
+    Returns:
+        Tuple of (is_valid, left_value, right_value, seconds_gap).
+        is_valid is False if gap cannot be backfilled.
+    """
+    # Check if we have valid readings on both sides
+    if gap_start == 0:
+        logger.debug("Gap at start of sequence (index 0), no left side for backfill")
+        return False, 0, 0, 0
+
+    if gap_end >= len(readings):
+        logger.debug("Gap at end of sequence (index %d), no right side for backfill", gap_start)
+        return False, 0, 0, 0
+
+    # Get the clock values on either side
+    left_value = readings[gap_start - 1].value
+    right_value = readings[gap_end].value
+
+    if left_value is None or right_value is None:
+        logger.debug("Adjacent values are None, cannot backfill")
+        return False, 0, 0, 0
+
+    # Left should be higher than right in a countdown
+    if left_value <= right_value:
+        logger.debug("Invalid countdown: left=%d not greater than right=%d", left_value, right_value)
+        return False, 0, 0, 0
+
+    seconds_gap = left_value - right_value - 1
+
+    # Check if gap in seconds is within our limit
+    if seconds_gap > max_gap_seconds:
+        logger.debug(
+            "Gap of %d seconds (left=%d, right=%d) exceeds max_gap_seconds=%d, skipping backfill",
+            seconds_gap,
+            left_value,
+            right_value,
+            max_gap_seconds,
+        )
+        return False, 0, 0, 0
+
+    return True, left_value, right_value, seconds_gap
+
+
+def _backfill_interpolate(result: List[PlayClockReading], gap_start: int, gap_frame_count: int, left_value: int, right_value: int) -> None:
+    """Backfill a gap using nearest value interpolation (no missing clock values)."""
+    logger.debug("No missing clock values between %d and %d, using nearest value interpolation", left_value, right_value)
+    for j in range(gap_frame_count):
+        # Use left value for first half, right value for second half
+        backfill_value = left_value if j < gap_frame_count / 2 else right_value
+        result[gap_start + j] = PlayClockReading(
+            detected=True,
+            value=backfill_value,
+            confidence=0.0,
+            raw_text=f"BACKFILLED_{backfill_value}",
+        )
+
+
+def _backfill_with_missing_values(result: List[PlayClockReading], gap_start: int, gap_end: int, left_value: int, right_value: int) -> None:
+    """Backfill a gap by distributing missing clock values across frames."""
+    gap_frame_count = gap_end - gap_start
+    missing_values = list(range(left_value - 1, right_value, -1))
+
+    logger.info(
+        "Backfilling gap: frames %d-%d, clock values %d to %d, missing values: %s",
+        gap_start,
+        gap_end - 1,
+        left_value,
+        right_value,
+        missing_values,
+    )
+
+    for j in range(gap_frame_count):
+        # Calculate which missing value this frame should have
+        position = j / gap_frame_count
+        value_index = min(int(position * len(missing_values)), len(missing_values) - 1)
+        backfill_value = missing_values[value_index]
+
+        result[gap_start + j] = PlayClockReading(
+            detected=True,
+            value=backfill_value,
+            confidence=0.0,
+            raw_text=f"BACKFILLED_{backfill_value}",
+        )
+        logger.debug("  Backfilled index %d with value %d", gap_start + j, backfill_value)
+
+
+def backfill_missing_readings(readings: List[PlayClockReading], max_gap_seconds: int = 3) -> List[PlayClockReading]:
     """
     Backfill missing play clock readings when there's a clear countdown sequence with gaps.
 
@@ -517,112 +512,31 @@ def backfill_missing_readings(readings: list[PlayClockReading], max_gap_seconds:
     if not readings:
         return readings
 
-    # Create a copy to avoid modifying the original
     result = list(readings)
-
-    # Find gaps and try to backfill
     i = 0
+
     while i < len(result):
         # Skip if this reading is valid
         if result[i].detected and result[i].value is not None:
             i += 1
             continue
 
-        # Found a missing reading - find the extent of the gap (in frames)
+        # Found a missing reading - find the extent of the gap
         gap_start = i
-        gap_end = i
-        while gap_end < len(result) and (not result[gap_end].detected or result[gap_end].value is None):
-            gap_end += 1
-
+        gap_end = _find_gap_extent(result, i)
         gap_frame_count = gap_end - gap_start
 
-        # Check if we have valid readings on both sides
-        if gap_start == 0:
-            logger.debug("Gap at start of sequence (index 0), no left side for backfill")
-            i = gap_end
-            continue
-
-        if gap_end >= len(result):
-            logger.debug("Gap at end of sequence (index %d), no right side for backfill", gap_start)
-            i = gap_end
-            continue
-
-        # Get the clock values on either side
-        left_value = result[gap_start - 1].value
-        right_value = result[gap_end].value
-
-        if left_value is None or right_value is None:
-            logger.debug("Adjacent values are None, cannot backfill")
-            i = gap_end
-            continue
-
-        # Calculate the gap in seconds (clock values)
-        # Left should be higher than right in a countdown
-        if left_value <= right_value:
-            logger.debug("Invalid countdown: left=%d not greater than right=%d", left_value, right_value)
-            i = gap_end
-            continue
-
-        seconds_gap = left_value - right_value - 1  # Number of missing clock values
-
-        # Check if gap in seconds is within our limit
-        if seconds_gap > max_gap_seconds:
-            logger.debug(
-                "Gap of %d seconds (left=%d, right=%d) exceeds max_gap_seconds=%d, skipping backfill",
-                seconds_gap,
-                left_value,
-                right_value,
-                max_gap_seconds,
-            )
+        # Validate that we can backfill this gap
+        is_valid, left_value, right_value, seconds_gap = _validate_gap_boundaries(result, gap_start, gap_end, max_gap_seconds)
+        if not is_valid:
             i = gap_end
             continue
 
+        # Perform the backfill
         if seconds_gap <= 0:
-            # No missing values (e.g., left=5, right=4 means we just missed some frames of 5 or 4)
-            # Still backfill with a reasonable value (closer to left or right based on position)
-            logger.debug("No missing clock values between %d and %d, using nearest value interpolation", left_value, right_value)
-            for j in range(gap_frame_count):
-                # Use left value for first half, right value for second half
-                if j < gap_frame_count / 2:
-                    backfill_value = left_value
-                else:
-                    backfill_value = right_value
-                result[gap_start + j] = PlayClockReading(
-                    detected=True,
-                    value=backfill_value,
-                    confidence=0.0,
-                    raw_text=f"BACKFILLED_{backfill_value}",
-                )
-            i = gap_end
-            continue
-
-        # Calculate the missing clock values
-        missing_values = list(range(left_value - 1, right_value, -1))
-
-        logger.info(
-            "Backfilling gap: frames %d-%d, clock values %d to %d, missing values: %s",
-            gap_start,
-            gap_end - 1,
-            left_value,
-            right_value,
-            missing_values,
-        )
-
-        # Distribute missing values across the gap frames
-        for j in range(gap_frame_count):
-            # Calculate which missing value this frame should have
-            position = j / gap_frame_count
-            value_index = int(position * len(missing_values))
-            value_index = min(value_index, len(missing_values) - 1)
-            backfill_value = missing_values[value_index]
-
-            result[gap_start + j] = PlayClockReading(
-                detected=True,
-                value=backfill_value,
-                confidence=0.0,
-                raw_text=f"BACKFILLED_{backfill_value}",
-            )
-            logger.debug("  Backfilled index %d with value %d", gap_start + j, backfill_value)
+            _backfill_interpolate(result, gap_start, gap_frame_count, left_value, right_value)
+        else:
+            _backfill_with_missing_values(result, gap_start, gap_end, left_value, right_value)
 
         i = gap_end
 

src/setup/coverage.py

@@ -0,0 +1,84 @@
+"""
+Shared coverage calculation utilities for digit templates.
+
+This module provides utilities for calculating template coverage status,
+shared between DigitTemplateBuilder and DigitTemplateLibrary.
+"""
+
+from typing import Any, Dict, Iterable, Set, Tuple
+
+
+# Standard digit sets for play clock displays
+ONES_DIGITS = set(range(10))  # 0-9
+TENS_DIGITS = {1, 2, 3, 4}  # 10, 20, 30, 40
+
+
+def categorize_template_keys(keys: Iterable[Tuple[bool, int, str]]) -> Tuple[Set[int], Set[int], Set[int], bool]:
+    """
+    Categorize template keys into digit sets.
+
+    Args:
+        keys: Iterable of (is_tens, digit, position) tuples
+
+    Returns:
+        Tuple of (ones_center_have, ones_right_have, tens_have, has_blank)
+    """
+    ones_center_have: Set[int] = set()
+    ones_right_have: Set[int] = set()
+    tens_have: Set[int] = set()
+    has_blank = False
+
+    for is_tens, digit, position in keys:
+        if is_tens:
+            if digit == -1:
+                has_blank = True
+            else:
+                tens_have.add(digit)
+        else:
+            if position == "center":
+                ones_center_have.add(digit)
+            elif position == "right":
+                ones_right_have.add(digit)
+
+    return ones_center_have, ones_right_have, tens_have, has_blank
+
+
+def calculate_coverage_status(
+    ones_center_have: Set[int],
+    ones_right_have: Set[int],
+    tens_have: Set[int],
+    has_blank: bool,
+    total_items: int = 0,
+) -> Dict[str, Any]:
+    """
+    Calculate coverage status from digit sets.
+
+    Args:
+        ones_center_have: Set of ones digits that have center templates
+        ones_right_have: Set of ones digits that have right templates
+        tens_have: Set of tens digits that have templates
+        has_blank: Whether blank template exists
+        total_items: Total number of items (templates or samples)
+
+    Returns:
+        Dictionary with coverage information
+    """
+    ones_center_missing = ONES_DIGITS - ones_center_have
+    ones_right_missing = ONES_DIGITS - ones_right_have
+    tens_missing = TENS_DIGITS - tens_have
+
+    # Total needed: 10 ones_center + 10 ones_right + 4 tens + 1 blank = 25
+    total_needed = 25
+
+    return {
+        "total_needed": total_needed,
+        "total_have": total_items,
+        "is_complete": total_items >= total_needed,
+        "ones_center_have": sorted(ones_center_have),
+        "ones_center_missing": sorted(ones_center_missing),
+        "ones_right_have": sorted(ones_right_have),
+        "ones_right_missing": sorted(ones_right_missing),
+        "tens_have": sorted(tens_have),
+        "tens_missing": sorted(tens_missing),
+        "has_blank": has_blank,
+    }

src/setup/playclock_region.py

@@ -1,4 +1,3 @@
-# pylint: disable=duplicate-code
 """
 Play clock region extraction and OCR preprocessing for template building.
 
@@ -9,8 +8,7 @@ This module provides:
 The region extraction logic determines WHERE to look in the frame,
 while the OCR preprocessing prepares images for EasyOCR labeling.
 
-Note: detect_red_digits and normalize_to_grayscale are duplicated in readers/playclock.py
-to avoid circular imports. Both modules need these utilities independently.
+Color detection utilities are shared from utils.color to eliminate code duplication.
 """
 
 import json
@@ -21,47 +19,12 @@ from typing import Optional, Tuple
 import cv2
 import numpy as np
 
+from utils import detect_red_digits
 from .models import PlayClockRegionConfig
 
 logger = logging.getLogger(__name__)
 
 
-# =============================================================================
-# Color Detection Utilities (duplicated to avoid circular imports)
-# =============================================================================
-
-
-def detect_red_digits(region: np.ndarray) -> bool:
-    """
-    Detect if the play clock digits are red.
-
-    Red digits appear when the play clock has 5 seconds or less remaining.
-    Red digits have high red channel values with very low green and blue.
-
-    Args:
-        region: Play clock region (BGR format)
-
-    Returns:
-        True if red digits detected, False otherwise
-    """
-    # Split into BGR channels
-    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)
-
-    # Red digits: high red channel, very low green/blue, red > 2x green
-    # pylint: disable=chained-comparison
-    is_red = r_mean > 15 and max(g_mean, b_mean) < 15 and r_mean > (g_mean * 2)
-
-    if is_red:
-        logger.debug("Red digits detected: R=%.1f, G=%.1f, B=%.1f", r_mean, g_mean, b_mean)
-
-    return is_red
-
-
 # =============================================================================
 # Play Clock Region Extractor
 # =============================================================================

src/setup/template_builder.py

@@ -1,4 +1,3 @@
-# pylint: disable=duplicate-code
 """
 Digit template builder for creating play clock digit templates from OCR samples.
 
@@ -6,8 +5,7 @@ This module provides the DigitTemplateBuilder class which collects samples from
 the play clock region, extracts individual digits, and builds averaged templates
 for each unique digit value.
 
-Note: detect_red_digits and normalize_to_grayscale are duplicated in detection/clock_reader.py
-to avoid circular imports. Both modules need these utilities independently.
+Region extraction and preprocessing utilities are shared from utils to eliminate code duplication.
 """
 
 import logging
@@ -16,69 +14,20 @@ from typing import Dict, List, Optional, Tuple
 import cv2
 import numpy as np
 
+from utils import (
+    extract_center_region,
+    extract_far_left_region,
+    extract_left_region,
+    extract_right_region,
+    preprocess_playclock_region,
+)
+from .coverage import ONES_DIGITS, categorize_template_keys
 from .models import DigitSample, DigitTemplate
 from .template_library import DigitTemplateLibrary
 
 logger = logging.getLogger(__name__)
 
 
-def detect_red_digits(region: np.ndarray) -> bool:
-    """
-    Detect if the play clock digits are red.
-
-    Red digits appear when the play clock has 5 seconds or less remaining.
-    Red digits have high red channel values with very low green and blue.
-
-    Args:
-        region: Play clock region (BGR format)
-
-    Returns:
-        True if red digits detected, False otherwise
-    """
-    # Split into BGR channels
-    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)
-
-    # Red digits: high red channel, very low green/blue, red > 2x green
-    # pylint: disable=chained-comparison
-    is_red = r_mean > 15 and max(g_mean, b_mean) < 15 and r_mean > (g_mean * 2)
-
-    if is_red:
-        logger.debug("Red digits detected: R=%.1f, G=%.1f, B=%.1f", r_mean, g_mean, b_mean)
-
-    return is_red
-
-
-def normalize_to_grayscale(region: np.ndarray) -> np.ndarray:
-    """
-    Normalize a play clock region to grayscale, handling both red and white digits.
-
-    Red digits (displayed when clock <= 5) are converted to white-like grayscale
-    by extracting the red channel. White digits use standard grayscale conversion.
-    This allows a single set of templates to match both color variants.
-
-    Args:
-        region: Play clock region (BGR format)
-
-    Returns:
-        Grayscale image where digits appear as bright pixels on dark background
-    """
-    is_red = detect_red_digits(region)
-
-    if is_red:
-        # For red digits, use the red channel directly as grayscale
-        # This converts red digits to white-like appearance
-        _, _, r = cv2.split(region)
-        return r
-
-    # Standard grayscale conversion for white digits
-    return cv2.cvtColor(region, cv2.COLOR_BGR2GRAY)
-
-
 class DigitTemplateBuilder:
     """
     Builds digit templates from OCR-labeled play clock samples.
@@ -116,7 +65,7 @@ class DigitTemplateBuilder:
         """
         Preprocess play clock region for template extraction.
 
-        Uses color normalization to handle both red and white digits uniformly.
+        Delegates to shared utility function in utils.regions.
 
         Args:
             region: Play clock region (BGR format)
@@ -124,97 +73,7 @@ class DigitTemplateBuilder:
         Returns:
             Preprocessed binary image (white digits on black background)
         """
-        # Normalize color (red → white conversion happens here)
-        gray = normalize_to_grayscale(region)
-
-        # Scale up for better template quality
-        scale_factor = 4
-        scaled = cv2.resize(gray, None, fx=scale_factor, fy=scale_factor, interpolation=cv2.INTER_LINEAR)
-
-        # Use Otsu's thresholding
-        _, 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)
-        if mean_intensity > 128:
-            binary = cv2.bitwise_not(binary)
-
-        return binary
-
-    def extract_left_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """
-        Extract the left (tens digit) region from preprocessed play clock.
-
-        Used for tens digits in double-digit displays (10-40).
-
-        Args:
-            preprocessed: Preprocessed play clock image (scaled 4x)
-
-        Returns:
-            Left region image for tens digit
-        """
-        _, w = preprocessed.shape[:2]
-        mid_x = w // 2
-        return preprocessed[:, : mid_x - 2]  # Small gap in middle
-
-    def extract_far_left_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """
-        Extract the far left region from preprocessed play clock.
-
-        Used for blank detection in single-digit displays (0-9). This narrow
-        region (0%-20% of width) doesn't overlap with a centered digit,
-        so it should be truly empty when the clock shows a single digit.
-
-        Args:
-            preprocessed: Preprocessed play clock image (scaled 4x)
-
-        Returns:
-            Far left region image (should be mostly black for single digits)
-        """
-        _, w = preprocessed.shape[:2]
-        # Far left: 0% to 20% of width - avoids overlap with centered digit
-        far_left_end = int(w * 0.20)
-        return preprocessed[:, :far_left_end]
-
-    def extract_right_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """
-        Extract the right (ones digit) region from preprocessed play clock.
-
-        Used for ones digits in double-digit displays (10-40).
-
-        Args:
-            preprocessed: Preprocessed play clock image (scaled 4x)
-
-        Returns:
-            Right region image for ones digit
-        """
-        _, w = preprocessed.shape[:2]
-        mid_x = w // 2
-        return preprocessed[:, mid_x + 2 :]
-
-    def extract_center_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """
-        Extract the center region from preprocessed play clock.
-
-        Used for ones digits in single-digit displays (0-9) where the
-        digit is center-aligned rather than right-aligned.
-
-        The center region spans approximately 60% of the width, centered.
-
-        Args:
-            preprocessed: Preprocessed play clock image (scaled 4x)
-
-        Returns:
-            Center region image for centered single digit
-        """
-        _, w = preprocessed.shape[:2]
-
-        # Center region: ~20% padding on each side, capturing middle 60%
-        # This encompasses where a centered single digit would appear
-        center_start = int(w * 0.20)
-        center_end = int(w * 0.80)
-
-        return preprocessed[:, center_start:center_end]
+        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]]:
         """
@@ -234,9 +93,9 @@ class DigitTemplateBuilder:
         """
         if clock_value >= 10:
             # Double-digit: standard left/right split
-            return self.extract_left_region(preprocessed), self.extract_right_region(preprocessed), None, None
+            return extract_left_region(preprocessed), extract_right_region(preprocessed), None, None
         # Single-digit: far-left is blank (truly empty), ones is centered
-        return None, None, self.extract_center_region(preprocessed), self.extract_far_left_region(preprocessed)
+        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:
         """
@@ -439,32 +298,20 @@ class DigitTemplateBuilder:
 
     def get_coverage_status(self) -> Dict[str, any]:
         """Get current sample coverage status."""
-        ones_center_have = set()
-        ones_right_have = set()
-        tens_have = set()
-        has_blank = False
+        # Get keys for samples that have at least one entry
+        keys_with_samples = [key for key, samples in self.samples.items() if len(samples) >= 1]
 
-        for (is_tens, digit, position), samples in self.samples.items():
-            if len(samples) >= 1:  # At least one sample
-                if is_tens:
-                    if digit == -1:
-                        has_blank = True
-                    else:
-                        tens_have.add(digit)
-                else:
-                    if position == "center":
-                        ones_center_have.add(digit)
-                    elif position == "right":
-                        ones_right_have.add(digit)
+        # Use shared utility to categorize
+        ones_center_have, ones_right_have, tens_have, has_blank = categorize_template_keys(keys_with_samples)
 
         return {
             "ones_center": sorted(ones_center_have),
             "ones_right": sorted(ones_right_have),
             "tens": sorted(tens_have),
             "has_blank": has_blank,
-            "ones_center_missing": sorted(set(DigitTemplateLibrary.ONES_DIGITS) - ones_center_have),
-            "ones_right_missing": sorted(set(DigitTemplateLibrary.ONES_DIGITS) - ones_right_have),
-            "tens_missing": sorted(set([1, 2, 3, 4]) - tens_have),
+            "ones_center_missing": sorted(ONES_DIGITS - ones_center_have),
+            "ones_right_missing": sorted(ONES_DIGITS - ones_right_have),
+            "tens_missing": sorted({1, 2, 3, 4} - tens_have),
         }
 
     def get_coverage_estimate(self) -> float:

src/setup/template_library.py

@@ -1,4 +1,3 @@
-# pylint: disable=duplicate-code
 """
 Digit template library for storing and managing play clock digit templates.
 
@@ -9,10 +8,11 @@ managing digit templates used for play clock reading.
 import json
 import logging
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Tuple
 
 import cv2
 
+from .coverage import ONES_DIGITS, calculate_coverage_status, categorize_template_keys
 from .models import DigitTemplate
 
 logger = logging.getLogger(__name__)
@@ -93,60 +93,30 @@ class DigitTemplateLibrary:
                     templates.append(template)
         return templates
 
-    def get_coverage_status(self) -> Dict[str, any]:
+    def get_coverage_status(self) -> Dict[str, Any]:
         """
         Get the current template coverage status.
 
         Returns:
             Dictionary with coverage information
         """
-        ones_center_have = set()
-        ones_right_have = set()
-        tens_have = set()
-        has_blank = False
-
-        for (is_tens, digit, position), _ in self.templates.items():
-            if is_tens:
-                if digit == -1:
-                    has_blank = True
-                else:
-                    tens_have.add(digit)
-            else:
-                if position == "center":
-                    ones_center_have.add(digit)
-                elif position == "right":
-                    ones_right_have.add(digit)
-
-        ones_center_missing = set(self.ONES_DIGITS) - ones_center_have
-        ones_right_missing = set(self.ONES_DIGITS) - ones_right_have
-        tens_missing = set([1, 2, 3, 4]) - tens_have
-
-        # Calculate totals
-        # ones_center (10) + ones_right (10) + tens (4) + blank (1) = 25
-        total_needed = 25
-        total_have = len(self.templates)
+        # Use shared utility to categorize template keys
+        ones_center_have, ones_right_have, tens_have, has_blank = categorize_template_keys(self.templates.keys())
+
+        # Get base coverage status from shared utility
+        status = calculate_coverage_status(ones_center_have, ones_right_have, tens_have, has_blank, total_items=len(self.templates))
 
         # Convert -1 to "blank" for display
         def format_tens(digits):
             return sorted(["blank" if d == -1 else d for d in digits], key=lambda x: (isinstance(x, str), x))
 
-        return {
-            "total_needed": total_needed,
-            "total_have": total_have,
-            "is_complete": total_have >= total_needed,
-            "ones_center_have": sorted(ones_center_have),
-            "ones_center_missing": sorted(ones_center_missing),
-            "ones_right_have": sorted(ones_right_have),
-            "ones_right_missing": sorted(ones_right_missing),
-            "tens_have": sorted(tens_have),
-            "tens_missing": sorted(tens_missing),
-            "has_blank": has_blank,
-            # Legacy fields for backward compatibility
-            "ones_have": sorted(ones_center_have | ones_right_have),
-            "ones_missing": sorted(ones_center_missing & ones_right_missing),
-            "tens_have_formatted": format_tens(tens_have | ({-1} if has_blank else set())),
-            "tens_missing_formatted": format_tens(tens_missing | (set() if has_blank else {-1})),
-        }
+        # Add legacy fields for backward compatibility
+        status["ones_have"] = sorted(ones_center_have | ones_right_have)
+        status["ones_missing"] = sorted((ONES_DIGITS - ones_center_have) & (ONES_DIGITS - ones_right_have))
+        status["tens_have_formatted"] = format_tens(tens_have | ({-1} if has_blank else set()))
+        status["tens_missing_formatted"] = format_tens((status["tens_missing"]) | (set() if has_blank else {-1}))
+
+        return status
 
     def is_complete(self) -> bool:
         """Check if all required templates are present."""

src/tracking/play_merger.py

@@ -13,10 +13,13 @@ from .models import PlayEvent
 logger = logging.getLogger(__name__)
 
 
-class PlayMerger:
+class PlayMerger:  # pylint: disable=too-few-public-methods
     """
     Merge plays from multiple sources with deduplication and filtering.
 
+    This is intentionally a single-purpose utility class with one public method (merge).
+    The filtering methods are internal implementation details.
+
     Handles:
     - Overlapping plays (start_time < last.end_time)
     - Close plays (start times within proximity_threshold) representing same event

src/tracking/play_state.py

@@ -1,4 +1,3 @@
-# pylint: disable=duplicate-code
 """
 Play state machine module for detecting play start and end times.
 
@@ -23,7 +22,7 @@ from .models import PlayEvent, PlayState, PlayTrackingState, TrackPlayStateConfi
 logger = logging.getLogger(__name__)
 
 
-class TrackPlayState:  # pylint: disable=too-many-instance-attributes,too-many-public-methods
+class TrackPlayState:
     """
     State machine for detecting play boundaries using play clock behavior.
 
@@ -315,7 +314,8 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes,too-many-p
             self._state.current_play_type = "special"
             self._start_play(timestamp, "clock_reset_special", 40)
 
-        return None
+        # Play tracking is started, not completed - no PlayEvent to return
+        # (implicitly returns None)
 
     def _check_timeout_change(self, timeout_info: Optional[TimeoutInfo] = None) -> Optional[str]:
         """
@@ -341,17 +341,41 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes,too-many-p
 
         return None
 
-    # pylint: disable=too-many-return-statements,too-many-branches
     def _handle_play_in_progress(self, timestamp: float, clock_value: int) -> Optional[PlayEvent]:
-        """Handle clock reading during PLAY_IN_PROGRESS state."""
+        """Handle clock reading during PLAY_IN_PROGRESS state.
+
+        Delegates to helper methods for each detection scenario to reduce complexity.
+        """
         if self._state.current_play_start_time is None:
             return None
 
         # Check for play duration timeout
+        result = self._check_play_timeout(timestamp, clock_value)
+        if result is not None:
+            return result
+
+        # Handle clock still at 40 (waiting for countdown)
+        if clock_value == 40:
+            self._handle_clock_at_40(timestamp)
+            return None
+
+        # Check for possession change (40→25 transition)
+        # Note: This function only updates state, never returns a PlayEvent
+        self._check_possession_change(timestamp, clock_value)
+
+        # Check for abnormal clock drop (first reading after 40)
+        result = self._check_abnormal_clock_drop(timestamp, clock_value)
+        if result is not None:
+            return result
+
+        # Check for countdown confirmation (play end detection)
+        return self._check_countdown_confirmation(timestamp, clock_value)
+
+    def _check_play_timeout(self, timestamp: float, clock_value: int) -> Optional[PlayEvent]:
+        """Check if play duration has exceeded maximum allowed time."""
         play_duration = timestamp - self._state.current_play_start_time
         if play_duration > self.config.max_play_duration:
             # Cap the end time at start + max_duration to avoid inflated durations
-            # This prevents long gaps (commercials, etc.) from extending play end times
             capped_end_time = self._state.current_play_start_time + self.config.max_play_duration
             logger.warning(
                 "Play duration (%.1fs) exceeded max (%.1fs), forcing end at %.1fs (capped from %.1fs)",
@@ -361,133 +385,129 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes,too-many-p
                 timestamp,
             )
             self._state.direct_end_time = capped_end_time
-            self._state.countdown_history = []  # Reset countdown tracking
+            self._state.countdown_history = []
             return self._end_play_capped(capped_end_time, clock_value, "max_duration")
+        return None
 
-        # If clock is still at 40, the play just started and clock hasn't begun countdown yet
-        # We need to wait for the clock to drop below 40 before we can detect play end
-        if clock_value == 40:
-            # Track when we first saw 40 (for turnover detection)
-            if self._state.first_40_timestamp is None:
-                self._state.first_40_timestamp = timestamp
-            # Clock is still at 40 after reset - waiting for countdown to begin
-            logger.debug("Play in progress at %.1fs, clock still at 40 (%.1fs at 40)", timestamp, timestamp - self._state.first_40_timestamp)
-            self._state.countdown_history = []  # Reset countdown tracking
-            return None
+    def _handle_clock_at_40(self, timestamp: float) -> None:
+        """Handle case when clock is still at 40 (play just started, waiting for countdown)."""
+        if self._state.first_40_timestamp is None:
+            self._state.first_40_timestamp = timestamp
+        logger.debug(
+            "Play in progress at %.1fs, clock still at 40 (%.1fs at 40)",
+            timestamp,
+            timestamp - self._state.first_40_timestamp,
+        )
+        self._state.countdown_history = []
 
-        # RAPID 40→25 TRANSITION DETECTION (possession change during play):
-        # This happens during punts, kickoffs, and after XPs/FGs:
-        # - Punt: Ball punted, receiving team catches it → clock resets to 25
-        # - Kickoff: Similar to punt
-        # - XP/FG: After kick, clock resets to 25 for next team's possession
-        #
-        # IMPORTANT: We should NOT end the play here! For punts/kickoffs, the return
-        # is still in progress. We need to:
-        # 1. Mark this as a special play
-        # 2. Update the clock base to 25
-        # 3. Continue tracking until proper end detection (countdown confirmed, scorebug lost, or max duration)
-        if clock_value == 25 and self._state.first_40_timestamp is not None:
-            time_at_40 = timestamp - self._state.first_40_timestamp
-            max_time_for_possession_change = 5.0  # 40→25 within 5 seconds indicates possession change
-            min_time_at_40 = 0.5  # Must be at 40 briefly to avoid OCR noise (lowered from 1.0 for timing precision)
-
-            if min_time_at_40 <= time_at_40 <= max_time_for_possession_change and len(self._state.countdown_history) == 0:
-                # Possession change detected - play continues (e.g., punt return in progress)
-                # DO NOT end the play here - let it continue until proper end detection
-                logger.info(
-                    "Possession change detected at %.1fs: 40 → 25 after %.1fs. Play continues (return may be in progress).",
-                    timestamp,
-                    time_at_40,
-                )
-                # Mark as special play and update clock base for proper end detection
-                self._state.current_play_type = "special"
-                self._state.current_play_clock_base = 25
-                self._state.first_40_timestamp = None  # Reset since we're now tracking at 25
-                self._state.countdown_history = []  # Reset countdown tracking for fresh detection at 25
-                return None  # Continue tracking - DO NOT end the play!
-
-        # ABNORMAL CLOCK DROP DETECTION:
-        # If the first reading after seeing 40 drops by more than 5 seconds (e.g., 40 → 25),
-        # this could be either:
-        # 1. A timeout/injury reset (no play happened) - clock was at 40 briefly
-        # 2. A turnover/possession change (play DID happen) - clock was at 40 for several seconds during play
-        # We distinguish by checking how long the clock was at 40.
-        if len(self._state.countdown_history) == 0:
-            # This is the first reading after 40
-            clock_drop = 40 - clock_value
-            max_normal_drop = 5  # Allow up to 5 second drop on first reading (accounts for timing/OCR variance)
-            if clock_drop > max_normal_drop:
-                # Check how long clock was at 40 to distinguish turnover from timeout
-                time_at_40 = (timestamp - self._state.first_40_timestamp) if self._state.first_40_timestamp else 0
-                min_time_for_play = 2.0  # If clock was at 40 for > 2 seconds, a play likely happened
-
-                if time_at_40 > min_time_for_play:
-                    # Ball was snapped, play happened - this is likely a turnover/possession change
-                    # Estimate play ended shortly before we saw the abnormal reading
-                    play_end_time = timestamp - 1.0
-                    logger.info(
-                        "Turnover/possession change detected at %.1fs: 40 → %d after %.1fs at 40. Recording play end at %.1fs.",
-                        timestamp,
-                        clock_value,
-                        time_at_40,
-                        play_end_time,
-                    )
-                    return self._end_play_with_backward_calc(timestamp, clock_value, play_end_time)
-                # Brief time at 40, likely timeout/reset, not a real play
-                logger.warning(
-                    "Abnormal clock drop detected at %.1fs: 40 → %d (drop of %d seconds, only %.1fs at 40). "
-                    "Likely timeout/injury reset, not a real play. Resetting to PRE_SNAP.",
-                    timestamp,
-                    clock_value,
-                    clock_drop,
-                    time_at_40,
-                )
-                self._reset_play_tracking()
-                self._state.state = PlayState.PRE_SNAP
-                return None
+    def _check_possession_change(self, timestamp: float, clock_value: int) -> None:
+        """Check for rapid 40→25 transition indicating possession change during play.
+
+        This happens during punts, kickoffs, and after XPs/FGs. The play continues
+        (e.g., punt return in progress) - we don't end the play here.
+        """
+        if clock_value != 25 or self._state.first_40_timestamp is None:
+            return  # Not a 40→25 transition
+
+        time_at_40 = timestamp - self._state.first_40_timestamp
+        max_time_for_possession_change = 5.0
+        min_time_at_40 = 0.5
 
-        # Track countdown history for confirming play end
-        # We require K consecutive descending ticks to confirm
+        if min_time_at_40 <= time_at_40 <= max_time_for_possession_change and len(self._state.countdown_history) == 0:
+            logger.info(
+                "Possession change detected at %.1fs: 40 → 25 after %.1fs. Play continues (return may be in progress).",
+                timestamp,
+                time_at_40,
+            )
+            # Mark as special play and update clock base for proper end detection
+            self._state.current_play_type = "special"
+            self._state.current_play_clock_base = 25
+            self._state.first_40_timestamp = None
+            self._state.countdown_history = []
+
+    def _check_abnormal_clock_drop(self, timestamp: float, clock_value: int) -> Optional[PlayEvent]:
+        """Check for abnormal clock drop on first reading after 40.
+
+        Distinguishes between:
+        - Turnover/possession change (play happened, clock was at 40 for several seconds)
+        - Timeout/injury reset (no play, clock was at 40 briefly)
+        """
+        if len(self._state.countdown_history) != 0:
+            return None  # Not the first reading after 40
+
+        clock_drop = 40 - clock_value
+        max_normal_drop = 5
+        if clock_drop <= max_normal_drop:
+            return None  # Normal drop, not abnormal
+
+        time_at_40 = (timestamp - self._state.first_40_timestamp) if self._state.first_40_timestamp else 0
+        min_time_for_play = 2.0
+
+        if time_at_40 > min_time_for_play:
+            # Ball was snapped, play happened - likely a turnover/possession change
+            play_end_time = timestamp - 1.0
+            logger.info(
+                "Turnover/possession change detected at %.1fs: 40 → %d after %.1fs at 40. Recording play end at %.1fs.",
+                timestamp,
+                clock_value,
+                time_at_40,
+                play_end_time,
+            )
+            return self._end_play_with_backward_calc(timestamp, clock_value, play_end_time)
+
+        # Brief time at 40, likely timeout/reset, not a real play
+        logger.warning(
+            "Abnormal clock drop detected at %.1fs: 40 → %d (drop of %d seconds, only %.1fs at 40). Likely timeout/injury reset, not a real play. Resetting to PRE_SNAP.",
+            timestamp,
+            clock_value,
+            clock_drop,
+            time_at_40,
+        )
+        self._reset_play_tracking()
+        self._state.state = PlayState.PRE_SNAP
+        return None
+
+    def _check_countdown_confirmation(self, timestamp: float, clock_value: int) -> Optional[PlayEvent]:
+        """Check for countdown confirmation to detect play end.
+
+        Requires K consecutive descending ticks to confirm play has ended.
+        """
+        # Track countdown history
         self._state.countdown_history.append((timestamp, clock_value))
 
         # Check if we have enough consecutive descending values
-        if len(self._state.countdown_history) >= self.config.required_countdown_ticks:
-            # Get last K readings
-            recent = self._state.countdown_history[-self.config.required_countdown_ticks :]
-            values = [v for _, v in recent]
-
-            # Check if values are strictly descending (or stable which means same second)
-            is_valid_countdown = True
-            for i in range(1, len(values)):
-                # Allow same value (within same second) or descending
-                if values[i] > values[i - 1]:
-                    is_valid_countdown = False
-                    break
-
-            if is_valid_countdown:
-                # Use the first reading in our confirmed sequence for backward calculation
-                first_timestamp, first_value = recent[0]
-                # Use the correct clock base (40 for normal plays, 25 for special teams)
-                calculated_end_time = first_timestamp - (self._state.current_play_clock_base - first_value)
-                logger.info(
-                    "Play END confirmed via %d-tick countdown: %.1fs (clock=%d→%d, base=%d, observed %.1fs-%.1fs)",
-                    self.config.required_countdown_ticks,
-                    calculated_end_time,
-                    values[0],
-                    values[-1],
-                    self._state.current_play_clock_base,
-                    recent[0][0],
-                    recent[-1][0],
-                )
-                self._state.direct_end_time = timestamp  # When we confirmed the countdown
-                self._state.countdown_history = []  # Reset for next play
-                return self._end_play_with_backward_calc(timestamp, first_value, calculated_end_time)
+        if len(self._state.countdown_history) < self.config.required_countdown_ticks:
+            return None
 
-        return None
+        # Get last K readings
+        recent = self._state.countdown_history[-self.config.required_countdown_ticks :]
+        values = [v for _, v in recent]
+
+        # Check if values are strictly descending (or stable which means same second)
+        for i in range(1, len(values)):
+            if values[i] > values[i - 1]:
+                return None  # Not a valid countdown
+
+        # Valid countdown confirmed - calculate play end time
+        first_timestamp, first_value = recent[0]
+        calculated_end_time = first_timestamp - (self._state.current_play_clock_base - first_value)
+        logger.info(
+            "Play END confirmed via %d-tick countdown: %.1fs (clock=%d→%d, base=%d, observed %.1fs-%.1fs)",
+            self.config.required_countdown_ticks,
+            calculated_end_time,
+            values[0],
+            values[-1],
+            self._state.current_play_clock_base,
+            recent[0][0],
+            recent[-1][0],
+        )
+        self._state.direct_end_time = timestamp
+        self._state.countdown_history = []
+        return self._end_play_with_backward_calc(timestamp, first_value, calculated_end_time)
 
-    def _handle_post_play(self, timestamp: float, clock_value: int) -> None:  # pylint: disable=unused-argument
+    def _handle_post_play(self, timestamp: float, _clock_value: int) -> None:
         """Handle clock reading during POST_PLAY state."""
-        # Note: clock_value unused for now, but kept for potential future use
+        # Note: clock_value unused for now, but kept for consistent API
         # Transition back to PRE_SNAP
         logger.debug("Transitioning from POST_PLAY to PRE_SNAP at %.1fs", timestamp)
         self._state.state = PlayState.PRE_SNAP

src/ui/sessions.py

@@ -17,8 +17,16 @@ 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]]:
-    """Extract sample frames - import here to avoid circular imports."""
-    from video.frame_extractor import extract_sample_frames  # pylint: disable=import-outside-toplevel
+    """Extract sample frames for interactive selection.
+
+    Note: Import is inside function to avoid circular imports.
+    The video.frame_extractor module imports from ui, so importing
+    it at module level would create a circular dependency.
+    """
+    # pylint: disable=import-outside-toplevel
+    # Import must be inside function to avoid circular dependency:
+    # ui.sessions -> video.frame_extractor -> ui (circular)
+    from video.frame_extractor import extract_sample_frames
 
     return extract_sample_frames(video_path, start_time, num_frames, interval)
 

src/utils/__init__.py

@@ -0,0 +1,27 @@
+"""
+Shared utility modules for the cfb40 project.
+
+This package contains utilities that are used across multiple modules
+to avoid code duplication and circular imports.
+"""
+
+from .color import detect_red_digits, normalize_to_grayscale
+from .regions import (
+    extract_left_region,
+    extract_right_region,
+    extract_center_region,
+    extract_far_left_region,
+    preprocess_playclock_region,
+)
+from .frame_result import create_frame_result
+
+__all__ = [
+    "detect_red_digits",
+    "normalize_to_grayscale",
+    "extract_left_region",
+    "extract_right_region",
+    "extract_center_region",
+    "extract_far_left_region",
+    "preprocess_playclock_region",
+    "create_frame_result",
+]

src/utils/color.py

@@ -0,0 +1,75 @@
+"""
+Color detection and normalization utilities for play clock digit processing.
+
+This module provides utilities for detecting red digits (shown when play clock <= 5)
+and normalizing play clock regions to grayscale for consistent template matching.
+
+These utilities are shared across:
+- readers/playclock.py (template matching)
+- setup/template_builder.py (template building)
+- setup/playclock_region.py (OCR preprocessing)
+"""
+
+import logging
+
+import cv2
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+def detect_red_digits(region: np.ndarray) -> bool:
+    """
+    Detect if the play clock digits are red.
+
+    Red digits appear when the play clock has 5 seconds or less remaining.
+    Red digits have high red channel values with very low green and blue.
+
+    Args:
+        region: Play clock region (BGR format)
+
+    Returns:
+        True if red digits detected, False otherwise
+    """
+    # Split into BGR channels
+    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)
+
+    # Red digits: high red channel, very low green/blue, red > 2x green
+    max_gb = max(g_mean, b_mean)
+    is_red = r_mean > 15 > max_gb and r_mean > g_mean * 2
+
+    if is_red:
+        logger.debug("Red digits detected: R=%.1f, G=%.1f, B=%.1f", r_mean, g_mean, b_mean)
+
+    return is_red
+
+
+def normalize_to_grayscale(region: np.ndarray) -> np.ndarray:
+    """
+    Normalize a play clock region to grayscale, handling both red and white digits.
+
+    Red digits (displayed when clock <= 5) are converted to white-like grayscale
+    by extracting the red channel. White digits use standard grayscale conversion.
+    This allows a single set of templates to match both color variants.
+
+    Args:
+        region: Play clock region (BGR format)
+
+    Returns:
+        Grayscale image where digits appear as bright pixels on dark background
+    """
+    is_red = detect_red_digits(region)
+
+    if is_red:
+        # For red digits, use the red channel directly as grayscale
+        # This converts red digits to white-like appearance
+        _, _, r = cv2.split(region)
+        return r
+
+    # Standard grayscale conversion for white digits
+    return cv2.cvtColor(region, cv2.COLOR_BGR2GRAY)

src/utils/frame_result.py

@@ -0,0 +1,50 @@
+"""
+Frame result factory for creating standardized detection result dictionaries.
+
+This module provides a factory function for creating frame-level detection results
+used in both sequential and parallel processing pipelines.
+
+These utilities are shared across:
+- pipeline/parallel.py
+- pipeline/play_detector.py
+"""
+
+from typing import Any, Dict, Optional, Tuple
+
+
+def create_frame_result(
+    timestamp: float,
+    scorebug_detected: bool,
+    scorebug_bbox: Optional[Tuple[int, int, int, int]] = None,
+    home_timeouts: Optional[int] = None,
+    away_timeouts: Optional[int] = None,
+    clock_value: Optional[int] = None,
+    clock_detected: bool = False,
+) -> Dict[str, Any]:
+    """
+    Create a standardized frame detection result dictionary.
+
+    This factory function ensures consistent structure for frame results
+    across both sequential and parallel processing pipelines.
+
+    Args:
+        timestamp: Frame timestamp in seconds.
+        scorebug_detected: Whether scorebug was detected in this frame.
+        scorebug_bbox: Scorebug bounding box (x, y, w, h) if detected.
+        home_timeouts: Number of home team timeouts remaining.
+        away_timeouts: Number of away team timeouts remaining.
+        clock_value: Detected play clock value (0-40).
+        clock_detected: Whether clock value was successfully read.
+
+    Returns:
+        Dictionary with frame detection results.
+    """
+    return {
+        "timestamp": timestamp,
+        "scorebug_detected": scorebug_detected,
+        "scorebug_bbox": scorebug_bbox,
+        "home_timeouts": home_timeouts,
+        "away_timeouts": away_timeouts,
+        "clock_value": clock_value,
+        "clock_detected": clock_detected,
+    }

src/utils/regions.py

@@ -0,0 +1,116 @@
+"""
+Region extraction utilities for play clock digit processing.
+
+This module provides utilities for extracting digit regions from preprocessed
+play clock images. The regions are used for both template building and matching.
+
+Play clock display layouts:
+- Single-digit (0-9): Digit is CENTER-aligned, tens position is blank
+- Double-digit (10-40): Tens on LEFT, ones on RIGHT
+
+These utilities are shared across:
+- readers/playclock.py (template matching)
+- setup/template_builder.py (template building)
+"""
+
+import cv2
+import numpy as np
+
+from .color import normalize_to_grayscale
+
+
+def extract_left_region(preprocessed: np.ndarray) -> np.ndarray:
+    """
+    Extract left region for tens digit in double-digit displays.
+
+    Args:
+        preprocessed: Preprocessed play clock image (scaled up)
+
+    Returns:
+        Left region image for tens digit
+    """
+    _, w = preprocessed.shape[:2]
+    mid_x = w // 2
+    return preprocessed[:, : mid_x - 2]  # Small gap in middle
+
+
+def extract_right_region(preprocessed: np.ndarray) -> np.ndarray:
+    """
+    Extract right region for ones digit in double-digit displays.
+
+    Args:
+        preprocessed: Preprocessed play clock image (scaled up)
+
+    Returns:
+        Right region image for ones digit
+    """
+    _, w = preprocessed.shape[:2]
+    mid_x = w // 2
+    return preprocessed[:, mid_x + 2 :]
+
+
+def extract_center_region(preprocessed: np.ndarray) -> np.ndarray:
+    """
+    Extract center region for ones digit in single-digit displays.
+
+    The center region spans approximately 60% of the width, centered.
+
+    Args:
+        preprocessed: Preprocessed play clock image (scaled up)
+
+    Returns:
+        Center region image for centered single digit
+    """
+    _, w = preprocessed.shape[:2]
+    center_start = int(w * 0.20)
+    center_end = int(w * 0.80)
+    return preprocessed[:, center_start:center_end]
+
+
+def extract_far_left_region(preprocessed: np.ndarray) -> np.ndarray:
+    """
+    Extract far left region for blank detection in single-digit displays.
+
+    This narrow region (0%-20% of width) doesn't overlap with a centered digit,
+    so it should be truly empty when the clock shows a single digit.
+
+    Args:
+        preprocessed: Preprocessed play clock image (scaled up)
+
+    Returns:
+        Far left region image (should be mostly black for single digits)
+    """
+    _, w = preprocessed.shape[:2]
+    far_left_end = int(w * 0.20)
+    return preprocessed[:, :far_left_end]
+
+
+def preprocess_playclock_region(region: np.ndarray, scale_factor: int = 4) -> np.ndarray:
+    """
+    Preprocess play clock region for template matching or building.
+
+    Uses color normalization to handle both red and white digits uniformly,
+    then scales and binarizes the image.
+
+    Args:
+        region: Play clock region (BGR format)
+        scale_factor: Scale factor for upscaling (default: 4)
+
+    Returns:
+        Preprocessed binary image (white digits on black background)
+    """
+    # Normalize color (red → white conversion happens here)
+    gray = normalize_to_grayscale(region)
+
+    # Scale up for better template quality/matching
+    scaled = cv2.resize(gray, None, fx=scale_factor, fy=scale_factor, interpolation=cv2.INTER_LINEAR)
+
+    # Use Otsu's thresholding
+    _, 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)
+    if mean_intensity > 128:
+        binary = cv2.bitwise_not(binary)
+
+    return binary