feat: Enhance inference management with device tracking and telemetry updates

- Introduced VideoPlayer class to handle local video playback, emitting frames via frame_ready signal.
- Updated MainWindow to switch between camera and video sources, integrating video playback controls.
- Enhanced AppMenuBar with options to open video files and manage inference models.
- Implemented BboxOverlay for displaying detection results on video frames.
- Added InferenceManager to manage YOLO inference in a separate process, with error handling and restart logic.
- Created tests for BboxOverlay and InferenceManager to ensure functionality and robustness.
- Updated pyproject.toml to include optional dependencies for inference support.

app/config.py

@@ -27,3 +27,20 @@ DISPATCHER_MAX_QUEUE_SIZE = 2  # max pending frames per slow subscriber before d
 LOG_DIR = Path("logs")              # relative to CWD (project root)
 MAX_LOG_FILES = 20                  # oldest sessions are deleted when exceeded
 TELEMETRY_CSV_INTERVAL_S = 5.0     # how often a CSV row is written (seconds)
+
+# Inference worker
+INFERENCE_WORKER_TIMEOUT_S = 10.0  # seconds without response before watchdog fires
+INFERENCE_MAX_RESTARTS = 3         # max auto-restart attempts before giving up
+INFERENCE_POLL_INTERVAL_MS = 50    # how often GUI thread polls output queue (ms)
+INFERENCE_WATCHDOG_INTERVAL_MS = 2000  # how often watchdog checks process health (ms)
+
+# BBox overlay
+BBOX_COLOR = (0, 220, 60, 255)          # RGBA — vivid green
+BBOX_LABEL_BG_COLOR = (0, 220, 60, 200) # RGBA — semi-transparent green for label bg
+BBOX_LABEL_TEXT_COLOR = (0, 0, 0, 255)  # RGBA — black text on green bg
+BBOX_LINE_WIDTH = 2
+BBOX_FONT_SIZE = 11
+
+# Video file source
+VIDEO_FILE_EXTENSIONS = "Video Files (*.mp4 *.avi *.mov *.mkv *.m4v *.webm)"
+MODEL_FILE_EXTENSIONS = "YOLO Model (*.pt *.pth)"

app/inference/bbox_overlay.py

@@ -0,0 +1,154 @@
+"""BboxOverlay — draws YOLO detection bounding boxes on the camera view."""
+
+from __future__ import annotations
+
+import logging
+from typing import NamedTuple
+
+from PySide6.QtCore import QRect, QSize, Qt, Slot
+from PySide6.QtGui import QColor, QFont, QPainter, QPen
+
+from app.config import (
+    BBOX_COLOR,
+    BBOX_FONT_SIZE,
+    BBOX_LABEL_BG_COLOR,
+    BBOX_LABEL_TEXT_COLOR,
+    BBOX_LINE_WIDTH,
+)
+from app.overlay.overlay_layer import IOverlayLayer
+
+logger = logging.getLogger(__name__)
+
+
+class Detection(NamedTuple):
+    """
+    A single object detection result.
+
+    Coordinates (x1, y1, x2, y2) are in pixels of the *source frame*
+    (i.e. the frame that was submitted to inference).  BboxOverlay maps
+    them to the letterboxed video_rect before drawing.
+    """
+
+    x1: float
+    y1: float
+    x2: float
+    y2: float
+    conf: float
+    label: str
+
+
+class BboxOverlay(IOverlayLayer):
+    """
+    Overlay layer that renders detection bounding boxes.
+
+    Usage:
+        overlay = BboxOverlay()
+        camera_view.add_overlay_layer(overlay)
+        inference_manager.detections_ready.connect(overlay.on_detections)
+
+    Thread safety:
+        on_detections() is called from the GUI thread (via Qt signal).
+        paint() is also called from the GUI thread (paintEvent).
+        No locks required.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._detections: list[Detection] = []
+        self._source_size: QSize = QSize(0, 0)
+
+        self._pen = QPen(QColor(*BBOX_COLOR))
+        self._pen.setWidth(BBOX_LINE_WIDTH)
+        self._pen.setJoinStyle(Qt.PenJoinStyle.MiterJoin)
+
+        self._font = QFont("Monospace")
+        self._font.setStyleHint(QFont.StyleHint.TypeWriter)
+        self._font.setPointSize(BBOX_FONT_SIZE)
+        self._font.setBold(True)
+
+        self._box_color = QColor(*BBOX_COLOR)
+        self._bg_color = QColor(*BBOX_LABEL_BG_COLOR)
+        self._text_color = QColor(*BBOX_LABEL_TEXT_COLOR)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @Slot(object, object)
+    def on_detections(
+        self,
+        detections: list[Detection],
+        source_size: tuple[int, int],
+    ) -> None:
+        """
+        Receive detection results from InferenceManager.
+
+        Args:
+            detections:  List of Detection namedtuples (pixel coords).
+            source_size: (width, height) of the frame that was inferred.
+        """
+        self._detections = detections
+        self._source_size = QSize(*source_size)
+
+    def clear(self) -> None:
+        """Remove all currently displayed detections."""
+        self._detections = []
+
+    # ------------------------------------------------------------------
+    # IOverlayLayer implementation
+    # ------------------------------------------------------------------
+
+    def paint(self, painter: QPainter, video_rect: QRect) -> None:
+        if not self._detections:
+            return
+        if self._source_size.isEmpty():
+            return
+
+        src_w = self._source_size.width()
+        src_h = self._source_size.height()
+        vr = video_rect
+
+        # Scale factors: source-pixel → video_rect-pixel
+        scale_x = vr.width() / src_w
+        scale_y = vr.height() / src_h
+
+        painter.setFont(self._font)
+        fm = painter.fontMetrics()
+
+        for det in self._detections:
+            # Map to widget coordinates
+            wx1 = vr.x() + int(det.x1 * scale_x)
+            wy1 = vr.y() + int(det.y1 * scale_y)
+            wx2 = vr.x() + int(det.x2 * scale_x)
+            wy2 = vr.y() + int(det.y2 * scale_y)
+
+            box_rect = QRect(wx1, wy1, wx2 - wx1, wy2 - wy1)
+
+            # Draw bounding box
+            painter.setPen(self._pen)
+            painter.setBrush(Qt.BrushStyle.NoBrush)
+            painter.drawRect(box_rect)
+
+            # Label text: "label 0.87"
+            label_text = f"{det.label} {det.conf:.2f}"
+            text_w = fm.horizontalAdvance(label_text) + 6
+            text_h = fm.height() + 2
+
+            # Position label above box, clamped to video_rect
+            lx = wx1
+            ly = wy1 - text_h
+            if ly < vr.top():
+                ly = wy1  # draw inside box if no room above
+
+            label_bg = QRect(lx, ly, text_w, text_h)
+
+            painter.setPen(Qt.PenStyle.NoPen)
+            painter.setBrush(self._bg_color)
+            painter.drawRect(label_bg)
+
+            painter.setPen(QPen(self._text_color))
+            painter.drawText(
+                lx + 3,
+                ly + fm.ascent() + 1,
+                label_text,
+            )

app/inference/worker.py

@@ -0,0 +1,219 @@
+"""YOLO inference worker — runs in a separate process.
+
+This module contains only plain functions (no Qt, no PySide6) so it can
+safely be imported and executed in a child process via multiprocessing.
+
+IPC protocol
+------------
+input_queue  receives : FramePacket       (frame_id, raw_bytes, width, height, channels)
+output_queue sends    : WorkerReadyPacket (device)  — once after model load
+                      : ResultPacket      (frame_id, detections, width, height, elapsed_ms)
+                      : None              — on fatal load failure
+stop_event           : multiprocessing.Event — set by parent to request clean exit
+
+Detection format (namedtuple-compatible plain tuple):
+    (x1, y1, x2, y2, conf, label)  — all floats/str, x/y in source-frame pixels
+"""
+
+from __future__ import annotations
+
+import logging
+import platform
+import sys
+from multiprocessing import Event, Queue
+from queue import Empty
+from typing import NamedTuple
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Data structures shared between worker and manager
+# ---------------------------------------------------------------------------
+
+class FramePacket(NamedTuple):
+    frame_id: int
+    raw_bytes: bytes       # RGB bytes, row-major, shape = (height, width, channels)
+    width: int
+    height: int
+    channels: int          # always 3 (RGB)
+
+
+class WorkerReadyPacket(NamedTuple):
+    """
+    Sent once by the worker right after the model is loaded.
+    Carries the device string so the GUI can display it.
+    """
+    device: str            # e.g. "cpu", "mps"
+
+
+class ResultPacket(NamedTuple):
+    frame_id: int
+    detections: list       # list of (x1, y1, x2, y2, conf, label) tuples
+    width: int             # source frame width (for overlay scaling)
+    height: int            # source frame height
+    elapsed_ms: float = 0.0  # inference wall-clock time in milliseconds
+
+
+# ---------------------------------------------------------------------------
+# Worker entry point
+# ---------------------------------------------------------------------------
+
+def run_worker(
+    model_path: str,
+    input_queue: Queue,
+    output_queue: Queue,
+    stop_event: Event,
+    log_level: int = logging.WARNING,
+) -> None:
+    """
+    Main loop of the inference worker process.
+
+    Loads the YOLO model once, sends WorkerReadyPacket, then processes
+    frames from input_queue until stop_event is set.
+    Results are posted to output_queue.
+
+    This function is designed to be the target of multiprocessing.Process.
+    It must NOT import PySide6 or any Qt module.
+    """
+    _configure_worker_logging(log_level)
+    logger.info("Inference worker starting (pid=%d)", _getpid())
+
+    # Select device once — never changes during the lifetime of this process
+    device = _select_device()
+
+    try:
+        model = _load_model(model_path, device)
+    except Exception as exc:
+        logger.error("Failed to load model '%s': %s", model_path, exc)
+        # Signal failure by putting None — manager treats it as error
+        output_queue.put(None)
+        return
+
+    logger.info("Model loaded: %s  device=%s", model_path, device)
+
+    # Notify GUI thread of the device being used
+    output_queue.put(WorkerReadyPacket(device=device))
+
+    while not stop_event.is_set():
+        try:
+            packet: FramePacket = input_queue.get(timeout=0.1)
+        except Empty:
+            continue
+        except Exception as exc:
+            logger.error("Error reading input queue: %s", exc)
+            break
+
+        try:
+            result = _infer(model, packet, device)
+            output_queue.put(result)
+        except Exception as exc:
+            logger.error("Inference error (frame %d): %s", packet.frame_id, exc)
+            # Put empty result so manager knows we're still alive
+            output_queue.put(ResultPacket(
+                frame_id=packet.frame_id,
+                detections=[],
+                width=packet.width,
+                height=packet.height,
+            ))
+
+    logger.info("Inference worker stopping")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _load_model(model_path: str, device: str):
+    """Load YOLO model and warm up on the selected device."""
+    from ultralytics import YOLO  # noqa: PLC0415
+
+    logger.info("Loading YOLO model on device='%s'", device)
+    model = YOLO(model_path)
+    # Warm up — run on a tiny dummy to JIT-compile kernels
+    try:
+        import numpy as np  # noqa: PLC0415
+        dummy = np.zeros((64, 64, 3), dtype=np.uint8)
+        model(dummy, device=device, verbose=False)
+    except Exception as exc:
+        logger.warning("Warm-up failed (non-fatal): %s", exc)
+    return model
+
+
+def _select_device() -> str:
+    """
+    Choose the best available inference device.
+
+    Priority:
+      - macOS  → "mps" if torch.backends.mps.is_available(), else "cpu"
+      - others → "cpu"
+
+    Called once at worker startup — not per frame.
+    """
+    system = platform.system()
+    if system == "Darwin":
+        try:
+            import torch  # noqa: PLC0415
+            if torch.backends.mps.is_available():
+                logger.info("MPS (Metal) available — using GPU")
+                return "mps"
+        except Exception:
+            pass
+        logger.info("MPS not available — using CPU")
+    return "cpu"
+
+
+def _infer(model, packet: FramePacket, device: str) -> ResultPacket:
+    """Run model on one frame, return ResultPacket with elapsed_ms."""
+    import time  # noqa: PLC0415
+
+    import numpy as np  # noqa: PLC0415
+
+    frame_np = np.frombuffer(packet.raw_bytes, dtype=np.uint8).reshape(
+        (packet.height, packet.width, packet.channels)
+    )
+
+    t0 = time.perf_counter()
+    results = model(frame_np, device=device, verbose=False)
+    elapsed_ms = (time.perf_counter() - t0) * 1000.0
+
+    detections = []
+    for r in results:
+        if r.boxes is None:
+            continue
+        boxes = r.boxes
+        for i in range(len(boxes)):
+            xyxy = boxes.xyxy[i].tolist()   # [x1, y1, x2, y2] in source pixels
+            conf = float(boxes.conf[i])
+            cls_idx = int(boxes.cls[i])
+            label = (
+                r.names[cls_idx]
+                if r.names and cls_idx in r.names
+                else str(cls_idx)
+            )
+            detections.append((
+                float(xyxy[0]), float(xyxy[1]),
+                float(xyxy[2]), float(xyxy[3]),
+                conf, label,
+            ))
+
+    return ResultPacket(
+        frame_id=packet.frame_id,
+        detections=detections,
+        width=packet.width,
+        height=packet.height,
+        elapsed_ms=elapsed_ms,
+    )
+
+
+def _configure_worker_logging(level: int) -> None:
+    logging.basicConfig(
+        level=level,
+        format="[worker %(process)d] %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+
+def _getpid() -> int:
+    import os  # noqa: PLC0415
+    return os.getpid()

app/inference/worker_manager.py

@@ -0,0 +1,401 @@
+"""InferenceManager — orchestrates the YOLO worker process from the GUI thread.
+
+Responsibilities:
+  - Start / stop the worker process
+  - Submit frames (with drop-if-busy logic)
+  - Poll result queue via QTimer (never blocks the GUI thread)
+  - Watch process health via QTimer (auto-restart on crash)
+  - Emit Qt signals with results for BboxOverlay and TelemetryCollector
+"""
+
+from __future__ import annotations
+
+import collections
+import logging
+import multiprocessing
+import time
+from pathlib import Path
+
+from PySide6.QtCore import QObject, QTimer, Signal, Slot
+from PySide6.QtMultimedia import QVideoFrame
+
+from app.config import (
+    INFERENCE_MAX_RESTARTS,
+    INFERENCE_POLL_INTERVAL_MS,
+    INFERENCE_WATCHDOG_INTERVAL_MS,
+    INFERENCE_WORKER_TIMEOUT_S,
+)
+from app.inference.bbox_overlay import Detection
+from app.inference.worker import FramePacket, ResultPacket, WorkerReadyPacket, run_worker
+
+logger = logging.getLogger(__name__)
+
+# Number of recent inference times to average for the overlay display
+_ELAPSED_WINDOW = 10
+
+
+class InferenceManager(QObject):
+    """
+    Manages the YOLO worker subprocess.
+
+    Signals:
+        detections_ready(detections, source_size)
+            Emitted in the GUI thread when a result arrives.
+            detections   : list[Detection]
+            source_size  : tuple[int, int] — (width, height) of inferred frame
+
+        detection_count_updated(int)
+            Total number of frames on which at least one detection occurred.
+
+        inference_stats_updated(device, avg_ms)
+            Emitted after every result packet.
+            device  : str   — e.g. "cpu", "mps"
+            avg_ms  : float — rolling average of inference time (last 10 frames)
+
+        inference_device_changed(str)
+            Emitted once when the worker reports its device after model load.
+
+        inference_started()   — worker is up and model is loaded
+        inference_stopped()   — worker has exited cleanly
+        inference_error(str)  — fatal error (max restarts exceeded)
+    """
+
+    detections_ready = Signal(object, object)   # list[Detection], tuple[int,int]
+    detection_count_updated = Signal(int)       # total frames with detections so far
+    inference_stats_updated = Signal(str, float)  # device, avg_elapsed_ms
+    inference_device_changed = Signal(str)      # emitted once on WorkerReadyPacket
+    inference_started = Signal()
+    inference_stopped = Signal()
+    inference_error = Signal(str)
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+
+        self._model_path: str | None = None
+        self._process: multiprocessing.Process | None = None
+        self._input_queue: multiprocessing.Queue | None = None
+        self._output_queue: multiprocessing.Queue | None = None
+        self._stop_event: multiprocessing.Event | None = None
+
+        # Drop-if-busy flag — True while worker is processing a frame
+        self._busy: bool = False
+        self._frame_id: int = 0
+
+        # Restart tracking
+        self._restart_count: int = 0
+        self._last_result_time: float = 0.0
+
+        # Paused flag — inference can be suspended without stopping the process
+        self._paused: bool = False
+
+        # Detection counter — frames on which at least one detection occurred
+        self._detection_frame_count: int = 0
+
+        # Device reported by the worker after model load
+        self._current_device: str = "cpu"
+
+        # Rolling window of recent elapsed_ms values for averaging
+        self._elapsed_window: collections.deque[float] = collections.deque(
+            maxlen=_ELAPSED_WINDOW
+        )
+
+        # QTimers (GUI thread)
+        self._poll_timer = QTimer(self)
+        self._poll_timer.setInterval(INFERENCE_POLL_INTERVAL_MS)
+        self._poll_timer.timeout.connect(self._poll_output)
+
+        self._watchdog_timer = QTimer(self)
+        self._watchdog_timer.setInterval(INFERENCE_WATCHDOG_INTERVAL_MS)
+        self._watchdog_timer.timeout.connect(self._watchdog_check)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def start(self, model_path: str) -> None:
+        """Load model and start the worker process."""
+        if not Path(model_path).exists():
+            msg = f"Model file not found: {model_path}"
+            logger.error(msg)
+            self.inference_error.emit(msg)
+            return
+
+        self._stop_worker()
+        self._model_path = model_path
+        self._restart_count = 0
+        self._paused = False
+        self._detection_frame_count = 0
+        self._elapsed_window.clear()
+        self._current_device = "cpu"
+        self._start_worker()
+
+    def stop(self) -> None:
+        """Stop the worker process and reset state."""
+        self._stop_worker()
+        self._model_path = None
+        self._restart_count = 0
+        self._paused = False
+
+    def pause(self) -> None:
+        """Suspend frame submission without stopping the process."""
+        self._paused = True
+        logger.debug("InferenceManager: paused")
+
+    def resume(self) -> None:
+        """Resume frame submission."""
+        self._paused = False
+        logger.debug("InferenceManager: resumed")
+
+    @property
+    def is_running(self) -> bool:
+        return self._process is not None and self._process.is_alive()
+
+    @property
+    def is_paused(self) -> bool:
+        return self._paused
+
+    @property
+    def model_path(self) -> str | None:
+        return self._model_path
+
+    @property
+    def current_device(self) -> str:
+        return self._current_device
+
+    @Slot(QVideoFrame)
+    def submit_frame(self, frame: QVideoFrame) -> None:
+        """
+        Attempt to submit a frame for inference.
+
+        Drops the frame silently if:
+          - manager is not running
+          - manager is paused
+          - worker is still busy with previous frame (drop_if_busy)
+
+        Frame conversion strategy:
+          Use QVideoFrame.toImage() → QImage.Format_RGB32 → bits().
+          This handles all pixel formats (NV12, YUV420P, BGRA, MJPG, etc.)
+          because Qt decodes them internally.  The cost is a CPU colour-space
+          conversion, but it only happens when the worker is idle (drop_if_busy).
+        """
+        if not self.is_running or self._paused or self._busy:
+            return
+
+        if not frame.isValid():
+            return
+
+        # Convert frame to RGB via Qt's built-in decoder.
+        # toImage() handles NV12, YUV420P, MJPG, BGRA — any pixel format.
+        image = frame.toImage()
+        if image.isNull():
+            logger.warning("InferenceManager: toImage() returned null")
+            return
+
+        width = image.width()
+        height = image.height()
+
+        # Ensure we have packed RGB32 (BGRX on little-endian, 4 bytes/pixel)
+        from PySide6.QtGui import QImage  # noqa: PLC0415
+        if image.format() != QImage.Format.Format_RGB32:
+            image = image.convertToFormat(QImage.Format.Format_RGB32)
+
+        # Extract RGB bytes (drop alpha/padding channel)
+        try:
+            import numpy as np  # noqa: PLC0415
+            # bits() returns BGRX (B G R 0xFF) for Format_RGB32
+            ptr = image.bits()
+            arr = np.frombuffer(ptr, dtype=np.uint8).reshape((height, width, 4))
+            # Swap B↔R and drop X → RGB
+            rgb = arr[:, :, [2, 1, 0]].copy()
+            raw = rgb.tobytes()
+        except Exception as exc:
+            logger.warning("InferenceManager: frame conversion failed: %s", exc)
+            return
+
+        channels = 3
+
+        self._frame_id += 1
+        packet = FramePacket(
+            frame_id=self._frame_id,
+            raw_bytes=raw,
+            width=width,
+            height=height,
+            channels=channels,
+        )
+
+        try:
+            self._input_queue.put_nowait(packet)
+            self._busy = True
+        except Exception as exc:
+            logger.warning("InferenceManager: could not enqueue frame: %s", exc)
+
+    # ------------------------------------------------------------------
+    # Private — worker lifecycle
+    # ------------------------------------------------------------------
+
+    def _start_worker(self) -> None:
+        ctx = multiprocessing.get_context("spawn")
+        self._input_queue = ctx.Queue(maxsize=1)
+        self._output_queue = ctx.Queue(maxsize=4)
+        self._stop_event = ctx.Event()
+
+        self._process = ctx.Process(
+            target=run_worker,
+            args=(
+                self._model_path,
+                self._input_queue,
+                self._output_queue,
+                self._stop_event,
+                logging.WARNING,
+            ),
+            daemon=True,
+            name="inference-worker",
+        )
+        self._process.start()
+        self._busy = False
+        self._last_result_time = time.monotonic()
+
+        self._poll_timer.start()
+        self._watchdog_timer.start()
+        logger.info(
+            "Inference worker started (pid=%d, model=%s)",
+            self._process.pid, self._model_path,
+        )
+        self.inference_started.emit()
+
+    def _stop_worker(self) -> None:
+        self._poll_timer.stop()
+        self._watchdog_timer.stop()
+
+        if self._stop_event is not None:
+            self._stop_event.set()
+
+        if self._process is not None:
+            self._process.join(timeout=3.0)
+            if self._process.is_alive():
+                logger.warning("Worker did not stop cleanly — terminating")
+                self._process.terminate()
+                self._process.join(timeout=2.0)
+            self._process = None
+
+        self._input_queue = None
+        self._output_queue = None
+        self._stop_event = None
+        self._busy = False
+
+        logger.info("Inference worker stopped")
+        self.inference_stopped.emit()
+
+    # ------------------------------------------------------------------
+    # Private — timers
+    # ------------------------------------------------------------------
+
+    @Slot()
+    def _poll_output(self) -> None:
+        """Drain the output queue (called every INFERENCE_POLL_INTERVAL_MS ms)."""
+        if self._output_queue is None:
+            return
+
+        try:
+            while True:
+                item = self._output_queue.get_nowait()
+
+                if item is None:
+                    # Worker signalled a fatal load error
+                    logger.error("Worker reported model load failure")
+                    self._handle_crash("Model failed to load in worker process")
+                    return
+
+                # ----------------------------------------------------------
+                # WorkerReadyPacket — sent once after model load
+                # ----------------------------------------------------------
+                if isinstance(item, WorkerReadyPacket):
+                    self._current_device = item.device
+                    logger.info("Inference device: %s", item.device)
+                    self.inference_device_changed.emit(item.device)
+                    continue
+
+                # ----------------------------------------------------------
+                # ResultPacket — regular inference result
+                # ----------------------------------------------------------
+                packet: ResultPacket = item
+                self._busy = False
+                self._last_result_time = time.monotonic()
+
+                # Update rolling average of elapsed time
+                self._elapsed_window.append(packet.elapsed_ms)
+                avg_ms = sum(self._elapsed_window) / len(self._elapsed_window)
+
+                detections = [
+                    Detection(x1, y1, x2, y2, conf, label)
+                    for x1, y1, x2, y2, conf, label in packet.detections
+                ]
+                source_size = (packet.width, packet.height)
+
+                if detections:
+                    self._detection_frame_count += 1
+                    conf_summary = ", ".join(
+                        f"{d.label} {d.conf:.2f}" for d in detections
+                    )
+                    logger.info(
+                        "frame %d: %d detection(s) in %.1f ms — %s",
+                        packet.frame_id,
+                        len(detections),
+                        packet.elapsed_ms,
+                        conf_summary,
+                    )
+                    self.detection_count_updated.emit(self._detection_frame_count)
+
+                # Always emit stats so overlay stays current
+                self.inference_stats_updated.emit(self._current_device, avg_ms)
+                self.detections_ready.emit(detections, source_size)
+
+        except Exception:
+            # Empty queue — normal
+            pass
+
+    @Slot()
+    def _watchdog_check(self) -> None:
+        """Detect crashed or hung worker process."""
+        if self._process is None:
+            return
+
+        # Process died unexpectedly
+        if not self._process.is_alive():
+            exit_code = self._process.exitcode
+            logger.error("Worker process died (exitcode=%s)", exit_code)
+            self._handle_crash(f"Worker process exited with code {exit_code}")
+            return
+
+        # Worker alive but hasn't responded for too long (hung during inference)
+        if self._busy:
+            elapsed = time.monotonic() - self._last_result_time
+            if elapsed > INFERENCE_WORKER_TIMEOUT_S:
+                logger.error(
+                    "Worker timeout: no response for %.1f s — restarting", elapsed
+                )
+                self._process.terminate()
+                self._process.join(timeout=2.0)
+                self._handle_crash("Worker timed out (hung during inference)")
+
+    def _handle_crash(self, reason: str) -> None:
+        """Decide whether to auto-restart or give up."""
+        self._poll_timer.stop()
+        self._watchdog_timer.stop()
+        self._process = None
+        self._busy = False
+
+        if self._restart_count < INFERENCE_MAX_RESTARTS:
+            self._restart_count += 1
+            logger.warning(
+                "Auto-restarting worker (attempt %d/%d): %s",
+                self._restart_count, INFERENCE_MAX_RESTARTS, reason,
+            )
+            self._start_worker()
+        else:
+            msg = (
+                f"Inference worker failed after {INFERENCE_MAX_RESTARTS} restarts. "
+                f"Last error: {reason}"
+            )
+            logger.error(msg)
+            self.inference_error.emit(msg)

app/overlay/telemetry_overlay.py

@@ -33,6 +33,8 @@ class TelemetryOverlay(IOverlayLayer):
         CPU sys   14.8 %        ← normalised by cpu_count (matches Task Manager)
         CPU core 118.4 %        ← per single core (can exceed 100%)
         Mem        68 MB
+        Inf.dev  mps            ← inference device (only when model loaded)
+        Inf.time  87 ms         ← rolling average of model() call time
     """
 
     def __init__(self) -> None:
@@ -106,4 +108,10 @@ class TelemetryOverlay(IOverlayLayer):
         if snap.memory_mb is not None:
             lines.append(f"Mem      {snap.memory_mb:>5.0f} MB")
 
+        if snap.inference_device is not None:
+            lines.append(f"Inf.dev  {snap.inference_device:>6s}")
+
+        if snap.inference_time_ms is not None:
+            lines.append(f"Inf.time {snap.inference_time_ms:>5.0f} ms")
+
         return lines

app/pipeline/frame_dispatcher.py

@@ -69,7 +69,7 @@ class FrameDispatcher(QObject):
         if len(self._subscribers) < before:
             logger.debug("Subscriber removed: %r", callback)
         else:
-            logger.warning("Subscriber not found for removal: %r", callback)
+            logger.debug("Subscriber not found for removal: %r", callback)
 
     def subscriber_count(self) -> int:
         return len(self._subscribers)

app/telemetry/telemetry_collector.py

@@ -26,6 +26,9 @@ class TelemetrySnapshot:
     cpu_percent_core: float       # process CPU per single core — can exceed 100%
     memory_mb: float | None       # process private working set in MB
     timestamp: float              # time.perf_counter() when snapshot was taken
+    # Inference fields — None when inference is disabled / model not loaded
+    inference_device: str | None = None   # e.g. "cpu", "mps"
+    inference_time_ms: float | None = None  # rolling average of model() call time
 
 
 class TelemetryCollector(QObject):
@@ -69,6 +72,10 @@ class TelemetryCollector(QObject):
         self._process.cpu_percent()  # first call always returns 0.0; discard
         self._cpu_count: int = max(psutil.cpu_count(logical=True) or 1, 1)
 
+        # Inference stats (updated externally via set_inference_stats)
+        self._inference_device: str | None = None
+        self._inference_time_ms: float | None = None
+
         # periodic snapshot timer
         self._timer = QTimer(self)
         self._timer.setInterval(update_interval_ms)
@@ -85,6 +92,16 @@ class TelemetryCollector(QObject):
         """Record the FPS that was requested from the camera."""
         self._target_fps = fps
 
+    def set_inference_stats(self, device: str, avg_ms: float) -> None:
+        """Update inference device and average inference time (called from MainWindow)."""
+        self._inference_device: str | None = device
+        self._inference_time_ms: float | None = avg_ms
+
+    def clear_inference_stats(self) -> None:
+        """Clear inference stats when inference is disabled."""
+        self._inference_device = None
+        self._inference_time_ms = None
+
     # ------------------------------------------------------------------
     # Frame subscriber callback
     # ------------------------------------------------------------------
@@ -175,6 +192,12 @@ class TelemetryCollector(QObject):
             cpu_percent_core=round(cpu_core, 1),
             memory_mb=round(mem_mb, 1) if mem_mb is not None else None,
             timestamp=now,
+            inference_device=self._inference_device,
+            inference_time_ms=(
+                round(self._inference_time_ms, 1)
+                if self._inference_time_ms is not None
+                else None
+            ),
         )
 
     def _make_empty_snapshot(self) -> TelemetrySnapshot:
@@ -187,4 +210,6 @@ class TelemetryCollector(QObject):
             cpu_percent_core=0.0,
             memory_mb=None,
             timestamp=time.perf_counter(),
+            inference_device=None,
+            inference_time_ms=None,
         )

app/ui/main_window.py

@@ -6,7 +6,7 @@ import logging
 from pathlib import Path
 
 from PySide6.QtCore import QTimer
-from PySide6.QtWidgets import QLabel, QMainWindow, QSizePolicy, QStatusBar
+from PySide6.QtWidgets import QLabel, QMainWindow, QMessageBox, QSizePolicy, QStatusBar
 
 from app.camera.camera_enumerator import CameraEnumerator, CameraFormat, CameraInfo
 from app.camera.camera_service import CameraService
@@ -14,6 +14,8 @@ from app.camera.uvc import make_uvc_controller
 from app.camera.uvc.base import UvcControllerBase
 from app.camera.uvc.stub import NullUvcController
 from app.config import APP_NAME, APP_VERSION
+from app.inference.bbox_overlay import BboxOverlay
+from app.inference.worker_manager import InferenceManager
 from app.overlay.telemetry_overlay import TelemetryOverlay
 from app.pipeline.frame_dispatcher import FrameDispatcher
 from app.telemetry.csv_logger import CsvTelemetryLogger
@@ -21,6 +23,7 @@ from app.telemetry.telemetry_collector import TelemetryCollector
 from app.ui.camera_settings_dialog import CameraSettingsDialog
 from app.ui.camera_view import CameraView
 from app.ui.menu_bar import AppMenuBar
+from app.video.video_player import VideoPlayer
 
 logger = logging.getLogger(__name__)
 
@@ -29,19 +32,25 @@ class MainWindow(QMainWindow):
     """
     Top-level application window.
 
-    Rendering architecture:
-        QVideoWidget is intentionally NOT used — on Windows its native HWND
-        surface occludes all sibling/child QWidgets regardless of z-order.
-        CameraView is a plain QWidget that renders frames and overlay layers
-        in a single paintEvent pass.
+    Frame source (exclusive):
+        • CameraService  — live camera (default)
+        • VideoPlayer    — local video file
+
+    Inference pipeline (optional):
+        InferenceManager runs YOLO in a separate process.
+        Frames submitted via FrameDispatcher subscriber (drop_if_busy).
+        Results displayed by BboxOverlay.
 
     Signal flow:
-        CameraService.frame_ready
+        [CameraService | VideoPlayer].frame_ready(QVideoFrame)
             → FrameDispatcher.dispatch
-                → CameraView.on_frame             (render frame)
-                → TelemetryCollector.on_frame     (measure metrics)
-                    → TelemetryOverlay.on_metrics_updated   (overlay data)
-                    → CsvTelemetryLogger.on_metrics_updated (CSV file)
+                → CameraView.on_frame             (render)
+                → TelemetryCollector.on_frame     (metrics)
+                    → TelemetryOverlay            (HUD)
+                    → CsvTelemetryLogger          (CSV)
+                → InferenceManager.submit_frame   (drop_if_busy, optional)
+                    → [worker process] YOLO
+                    → BboxOverlay.on_detections   (draw boxes)
     """
 
     def __init__(self, log_path: Path | None = None) -> None:
@@ -51,22 +60,28 @@ class MainWindow(QMainWindow):
         self.setMinimumSize(640, 480)
         self.resize(1280, 720)
 
-        # --- Core pipeline components ---
+        # --- Core pipeline ---
         self._camera_service = CameraService(self)
+        self._video_player = VideoPlayer(self)
         self._dispatcher = FrameDispatcher(self)
         self._telemetry = TelemetryCollector(parent=self)
+        self._inference = InferenceManager(self)
 
-        # --- UVC controller (platform-specific, lazy-opened per camera) ---
+        # Track which source is active
+        self._video_source_active: bool = False
+        self._current_camera: CameraInfo | None = None
+
+        # --- UVC ---
         self._uvc: UvcControllerBase = NullUvcController()
 
-        # --- CSV telemetry logger ---
+        # --- CSV logger ---
         self._csv_logger: CsvTelemetryLogger | None = None
         if log_path is not None:
             csv_path = log_path.with_suffix(".csv")
             self._csv_logger = CsvTelemetryLogger(csv_path)
             logger.info("Telemetry CSV: %s", csv_path.resolve())
 
-        # --- Camera view (central widget) ---
+        # --- Camera view ---
         self._camera_view = CameraView(self)
         self._camera_view.setSizePolicy(
             QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Expanding
@@ -75,7 +90,10 @@ class MainWindow(QMainWindow):
 
         # --- Overlay layers ---
         self._telemetry_overlay = TelemetryOverlay()
+        self._bbox_overlay = BboxOverlay()
         self._camera_view.add_overlay_layer(self._telemetry_overlay)
+        self._camera_view.add_overlay_layer(self._bbox_overlay)
+        self._bbox_overlay.visible = False   # hidden until inference enabled
 
         # --- Menu bar ---
         self._menu = AppMenuBar(self)
@@ -87,12 +105,15 @@ class MainWindow(QMainWindow):
         self._status_bar = QStatusBar(self)
         self.setStatusBar(self._status_bar)
         self._status_label = QLabel("Initialising\u2026")
-        self._status_bar.addWidget(self._status_label)
+        self._status_bar.addWidget(self._status_label, stretch=1)
+        # Detection counter — right-aligned permanent widget
+        self._detection_label = QLabel("")
+        self._detection_label.setVisible(False)
+        self._status_bar.addPermanentWidget(self._detection_label)
 
         # --- Wire signals ---
         self._wire_signals()
 
-        # --- Enumerate cameras and start ---
         QTimer.singleShot(0, self._initialise_cameras)
 
     # ------------------------------------------------------------------
@@ -101,21 +122,19 @@ class MainWindow(QMainWindow):
 
     def _initialise_cameras(self) -> None:
         cameras = CameraEnumerator.list_cameras()
-
         if not cameras:
             self._status_label.setText("No cameras found")
             logger.warning("No cameras detected")
             return
 
         self._menu.populate_cameras(cameras)
-
         default = CameraEnumerator.default_camera()
         start_cam = default if default is not None else cameras[0]
-
         self._menu.populate_formats(start_cam)
         self._start_camera(start_cam)
 
     def _start_camera(self, cam: CameraInfo) -> None:
+        self._current_camera = cam
         self._telemetry.reset_counters()
         self._camera_service.start(cam)
         self._menu.set_active_camera(cam)
@@ -123,12 +142,10 @@ class MainWindow(QMainWindow):
         self._open_uvc(cam)
 
     def _open_uvc(self, cam: CameraInfo) -> None:
-        """Open or reopen the UVC controller for the given camera."""
         if self._uvc.is_open():
             self._uvc.close()
         ctrl = make_uvc_controller(cam.name)
         if not ctrl.is_open():
-            # factory may return a pre-opened controller or a NullUvcController
             ctrl.open(cam.name)
         self._uvc = ctrl
 
@@ -137,38 +154,75 @@ class MainWindow(QMainWindow):
     # ------------------------------------------------------------------
 
     def _wire_signals(self) -> None:
-        # CameraService → FrameDispatcher
+        # ---- Active source → dispatcher ----
+        # (connected dynamically in _switch_to_camera / _switch_to_video)
         self._camera_service.frame_ready.connect(self._dispatcher.dispatch)
 
-        # FrameDispatcher → CameraView (render) — drop if busy
+        # ---- Dispatcher fans out to all consumers ----
         self._dispatcher.subscribe(self._camera_view.on_frame, drop_if_busy=True)
-
-        # FrameDispatcher → TelemetryCollector — never drop
         self._dispatcher.subscribe(self._telemetry.on_frame, drop_if_busy=False)
+        # InferenceManager subscriber added/removed dynamically on toggle
 
-        # TelemetryCollector → overlay
+        # ---- Telemetry ----
         self._telemetry.metrics_updated.connect(
             self._telemetry_overlay.on_metrics_updated
         )
-
-        # TelemetryCollector → CSV logger (throttled internally)
         if self._csv_logger is not None:
             self._telemetry.metrics_updated.connect(self._csv_logger.on_metrics_updated)
-
-        # CameraService → TelemetryCollector: keep target FPS in sync
         self._camera_service.format_changed.connect(self._telemetry.set_target_fps)
 
-        # CameraService status
+        # ---- Camera service status ----
         self._camera_service.camera_started.connect(self._on_camera_started)
         self._camera_service.camera_stopped.connect(self._on_camera_stopped)
         self._camera_service.camera_error.connect(self._on_camera_error)
 
-        # Menu signals
+        # ---- Video player status ----
+        self._video_player.playback_started.connect(self._on_playback_started)
+        self._video_player.playback_stopped.connect(self._on_playback_stopped)
+        self._video_player.playback_error.connect(self._on_playback_error)
+
+        # ---- InferenceManager ----
+        self._inference.detections_ready.connect(self._bbox_overlay.on_detections)
+        self._inference.detection_count_updated.connect(self._on_detection_count_updated)
+        self._inference.inference_stats_updated.connect(self._on_inference_stats_updated)
+        self._inference.inference_started.connect(self._on_inference_started)
+        self._inference.inference_stopped.connect(self._on_inference_stopped)
+        self._inference.inference_error.connect(self._on_inference_error)
+
+        # ---- Menu ----
         self._menu.camera_selected.connect(self._on_camera_selected)
         self._menu.format_selected.connect(self._on_format_selected)
         self._menu.reconnect_requested.connect(self._camera_service.reconnect)
         self._menu.overlay_toggled.connect(self._camera_view.set_all_overlays_visible)
         self._menu.camera_settings_requested.connect(self._on_settings_requested)
+        self._menu.video_file_selected.connect(self._on_video_selected)
+        self._menu.video_closed.connect(self._on_video_closed)
+        self._menu.model_file_selected.connect(self._on_model_selected)
+        self._menu.inference_toggled.connect(self._on_inference_toggled)
+
+    # ------------------------------------------------------------------
+    # Source switching
+    # ------------------------------------------------------------------
+
+    def _switch_to_camera(self) -> None:
+        """Disconnect VideoPlayer, connect CameraService to dispatcher."""
+        try:
+            self._video_player.frame_ready.disconnect(self._dispatcher.dispatch)
+        except RuntimeError:
+            pass
+        self._camera_service.frame_ready.connect(self._dispatcher.dispatch)
+        self._video_source_active = False
+        self._menu.set_video_source_active(False)
+
+    def _switch_to_video(self) -> None:
+        """Disconnect CameraService, connect VideoPlayer to dispatcher."""
+        try:
+            self._camera_service.frame_ready.disconnect(self._dispatcher.dispatch)
+        except RuntimeError:
+            pass
+        self._video_player.frame_ready.connect(self._dispatcher.dispatch)
+        self._video_source_active = True
+        self._menu.set_video_source_active(True)
 
     # ------------------------------------------------------------------
     # Camera status slots
@@ -187,11 +241,56 @@ class MainWindow(QMainWindow):
         self._status_label.setText(f"Error: {message}")
         logger.error("Camera error: %s", message)
 
+    # ------------------------------------------------------------------
+    # Video player slots
+    # ------------------------------------------------------------------
+
+    def _on_playback_started(self) -> None:
+        path = self._video_player.current_path or ""
+        name = Path(path).name if path else "video"
+        self._status_label.setText(f"Playing: {name}")
+
+    def _on_playback_stopped(self) -> None:
+        self._status_label.setText("Playback finished")
+
+    def _on_playback_error(self, message: str) -> None:
+        self._status_label.setText(f"Video error: {message}")
+        logger.error(message)
+
+    # ------------------------------------------------------------------
+    # Inference slots
+    # ------------------------------------------------------------------
+
+    def _on_inference_started(self) -> None:
+        self._status_label.setText("Inference running")
+        self._menu.set_inference_checked(True)
+
+    def _on_detection_count_updated(self, count: int) -> None:
+        self._detection_label.setText(f"Detections: {count} frames")
+
+    def _on_inference_stats_updated(self, device: str, avg_ms: float) -> None:
+        self._telemetry.set_inference_stats(device, avg_ms)
+
+    def _on_inference_stopped(self) -> None:
+        self._bbox_overlay.clear()
+
+    def _on_inference_error(self, message: str) -> None:
+        logger.error("Inference: %s", message)
+        self._menu.set_inference_available(False)
+        self._menu.set_inference_checked(False)
+        self._bbox_overlay.visible = False
+        self._detection_label.setVisible(False)
+        self._telemetry.clear_inference_stats()
+        QMessageBox.critical(self, "Inference Error", message)
+
     # ------------------------------------------------------------------
     # Menu action slots
     # ------------------------------------------------------------------
 
     def _on_camera_selected(self, cam: CameraInfo) -> None:
+        if self._video_source_active:
+            self._video_player.stop()
+            self._switch_to_camera()
         self._start_camera(cam)
 
     def _on_format_selected(self, fmt: CameraFormat) -> None:
@@ -209,12 +308,65 @@ class MainWindow(QMainWindow):
         dlg = CameraSettingsDialog(qt_cam, self._uvc, parent=self)
         dlg.exec()
 
+    def _on_video_selected(self, path: str) -> None:
+        """Switch source to video file."""
+        self._camera_service.stop()
+        self._switch_to_video()
+        self._video_player.play(path)
+        logger.info("Video source: %s", path)
+
+    def _on_video_closed(self) -> None:
+        """Return to camera source."""
+        self._video_player.stop()
+        self._switch_to_camera()
+        if self._current_camera is not None:
+            self._start_camera(self._current_camera)
+        logger.info("Returned to camera source")
+
+    def _on_model_selected(self, path: str) -> None:
+        """Load YOLO model into inference manager."""
+        name = Path(path).name
+        logger.info("Loading model: %s", path)
+        self._status_label.setText(f"Loading model: {name}\u2026")
+        self._inference.start(path)
+        self._menu.set_model_label(name)
+        self._menu.set_inference_available(True)
+        self._menu.set_inference_checked(False)   # user must explicitly enable
+
+    def _on_inference_toggled(self, enabled: bool) -> None:
+        if enabled:
+            if not self._inference.is_running:
+                # shouldn't happen but be safe
+                logger.warning("Inference toggle on but manager not running")
+                self._menu.set_inference_checked(False)
+                return
+            self._inference.resume()
+            self._dispatcher.subscribe(
+                self._inference.submit_frame, drop_if_busy=True
+            )
+            self._bbox_overlay.visible = True
+            self._detection_label.setText("Detections: 0 frames")
+            self._detection_label.setVisible(True)
+            self._status_label.setText("Inference enabled")
+            logger.info("Inference enabled")
+        else:
+            self._inference.pause()
+            self._dispatcher.unsubscribe(self._inference.submit_frame)
+            self._bbox_overlay.clear()
+            self._bbox_overlay.visible = False
+            self._detection_label.setVisible(False)
+            self._telemetry.clear_inference_stats()
+            self._status_label.setText("Inference disabled")
+            logger.info("Inference disabled")
+
     # ------------------------------------------------------------------
     # Qt overrides
     # ------------------------------------------------------------------
 
     def closeEvent(self, event) -> None:  # noqa: N802
+        self._inference.stop()
         self._camera_service.stop()
+        self._video_player.stop()
         if self._uvc.is_open():
             self._uvc.close()
         if self._csv_logger is not None:

app/ui/menu_bar.py

@@ -1,4 +1,4 @@
-"""Menu bar — camera, video format and debug controls."""
+"""Menu bar — File, Camera, Video format, Image, Model and Debug controls."""
 
 from __future__ import annotations
 
@@ -6,9 +6,10 @@ import logging
 
 from PySide6.QtCore import Signal
 from PySide6.QtGui import QAction, QActionGroup
-from PySide6.QtWidgets import QMenuBar, QWidget
+from PySide6.QtWidgets import QFileDialog, QMenuBar, QWidget
 
 from app.camera.camera_enumerator import CameraFormat, CameraInfo
+from app.config import MODEL_FILE_EXTENSIONS, VIDEO_FILE_EXTENSIONS
 from app.logging_setup import set_console_level
 
 logger = logging.getLogger(__name__)
@@ -19,17 +20,32 @@ class AppMenuBar(QMenuBar):
     Application menu bar.
 
     Signals:
-        camera_selected(CameraInfo)   — user picked a camera
-        format_selected(CameraFormat) — user picked a full format (res+fps+pixel)
-        reconnect_requested()         — user hit Reconnect
-        overlay_toggled(bool)         — overlay show/hide
-        log_toggled(bool)             — console logging on/off
-        camera_settings_requested()   — user opened Image Settings dialog
+        video_file_selected(str)    — user picked a video file path
+        video_closed()              — user chose to close video and return to camera
+        model_file_selected(str)    — user picked a .pt model file path
+        inference_toggled(bool)     — user toggled inference on/off
+        camera_selected(CameraInfo)
+        format_selected(CameraFormat)
+        reconnect_requested()
+        overlay_toggled(bool)
+        log_toggled(bool)
+        camera_settings_requested()
     """
 
+    # File / video
+    video_file_selected = Signal(str)
+    video_closed = Signal()
+
+    # Model / inference
+    model_file_selected = Signal(str)
+    inference_toggled = Signal(bool)
+
+    # Camera
     camera_selected = Signal(object)        # CameraInfo
     format_selected = Signal(object)        # CameraFormat
     reconnect_requested = Signal()
+
+    # View / debug
     overlay_toggled = Signal(bool)
     log_toggled = Signal(bool)
     camera_settings_requested = Signal()
@@ -48,7 +64,6 @@ class AppMenuBar(QMenuBar):
     # ------------------------------------------------------------------
 
     def populate_cameras(self, cameras: list[CameraInfo]) -> None:
-        """Populate the Camera menu with discovered devices."""
         self._cameras = cameras
         menu = self._camera_menu
 
@@ -71,7 +86,6 @@ class AppMenuBar(QMenuBar):
             self._camera_group.actions()[0].setChecked(True)
 
     def populate_formats(self, camera_info: CameraInfo) -> None:
-        """Populate the Resolution submenu with full format entries."""
         self._populate_format_menu(camera_info)
 
     def set_active_camera(self, camera_info: CameraInfo) -> None:
@@ -83,7 +97,6 @@ class AppMenuBar(QMenuBar):
                 return
 
     def set_active_format(self, fmt: CameraFormat) -> None:
-        """Mark the given format as checked in the Resolution menu."""
         if self._format_group is None:
             return
         for action in self._format_group.actions():
@@ -98,34 +111,80 @@ class AppMenuBar(QMenuBar):
                 return
 
     def set_log_file_path(self, path: str) -> None:
-        """Display the log file path as a disabled menu item in Debug menu."""
         display = path if len(path) <= 60 else "\u2026" + path[-57:]
         self._log_file_action.setText(f"Log: {display}")
         self._log_file_action.setToolTip(path)
 
+    def set_video_source_active(self, is_video: bool) -> None:
+        """Update File menu state when source switches between camera and video."""
+        self._close_video_action.setEnabled(is_video)
+
+    def set_inference_available(self, available: bool) -> None:
+        """Enable/disable the inference toggle (requires model to be loaded)."""
+        self._inference_toggle_action.setEnabled(available)
+
+    def set_inference_checked(self, checked: bool) -> None:
+        self._inference_toggle_action.setChecked(checked)
+
+    def set_model_label(self, name: str) -> None:
+        """Show loaded model name as disabled info item."""
+        self._model_info_action.setText(f"Model: {name}")
+
     # ------------------------------------------------------------------
     # Menu construction
     # ------------------------------------------------------------------
 
     def _build_menus(self) -> None:
-        # Camera menu
+        # --- File menu ---
+        file_menu = self.addMenu("File")
+
+        open_video_action = QAction("Open Video\u2026", self)
+        open_video_action.triggered.connect(self._on_open_video)
+        file_menu.addAction(open_video_action)
+
+        self._close_video_action = QAction("Close Video", self)
+        self._close_video_action.setEnabled(False)
+        self._close_video_action.triggered.connect(self.video_closed)
+        file_menu.addAction(self._close_video_action)
+
+        # --- Camera menu ---
         self._camera_menu = self.addMenu("Camera")
         self._cam_separator = self._camera_menu.addSeparator()
         self._reconnect_action = QAction("Reconnect", self)
         self._reconnect_action.triggered.connect(self.reconnect_requested)
         self._camera_menu.addAction(self._reconnect_action)
 
-        # Video menu
+        # --- Video menu ---
         self._video_menu = self.addMenu("Video")
         self._res_menu = self._video_menu.addMenu("Resolution")
 
-        # Image menu (camera controls)
+        # --- Image menu ---
         self._image_menu = self.addMenu("Image")
         self._settings_action = QAction("Camera Settings\u2026", self)
         self._settings_action.triggered.connect(self.camera_settings_requested)
         self._image_menu.addAction(self._settings_action)
 
-        # Debug menu
+        # --- Model menu ---
+        model_menu = self.addMenu("Model")
+
+        load_model_action = QAction("Load Model\u2026", self)
+        load_model_action.triggered.connect(self._on_load_model)
+        model_menu.addAction(load_model_action)
+
+        self._inference_toggle_action = QAction("Enable Inference", self)
+        self._inference_toggle_action.setCheckable(True)
+        self._inference_toggle_action.setChecked(False)
+        self._inference_toggle_action.setEnabled(False)   # enabled after model loaded
+        self._inference_toggle_action.toggled.connect(self.inference_toggled)
+        model_menu.addAction(self._inference_toggle_action)
+
+        model_menu.addSeparator()
+
+        self._model_info_action = QAction("Model: (none)", self)
+        self._model_info_action.setEnabled(False)
+        model_menu.addAction(self._model_info_action)
+
+        # --- Debug menu ---
         debug_menu = self.addMenu("Debug")
 
         self._overlay_action = QAction("Show Overlay", self)
@@ -147,7 +206,6 @@ class AppMenuBar(QMenuBar):
         debug_menu.addAction(self._log_file_action)
 
     def _populate_format_menu(self, camera_info: CameraInfo) -> None:
-        """Build Resolution submenu: one action per unique (W, H, FPS, pixel_format)."""
         self._res_menu.clear()
         self._format_group = QActionGroup(self)
         self._format_group.setExclusive(True)
@@ -173,6 +231,28 @@ class AppMenuBar(QMenuBar):
     # Slots
     # ------------------------------------------------------------------
 
+    def _on_open_video(self) -> None:
+        path, _ = QFileDialog.getOpenFileName(
+            self.parentWidget(),
+            "Open Video File",
+            "",
+            VIDEO_FILE_EXTENSIONS,
+        )
+        if path:
+            logger.debug("Video file selected: %s", path)
+            self.video_file_selected.emit(path)
+
+    def _on_load_model(self) -> None:
+        path, _ = QFileDialog.getOpenFileName(
+            self.parentWidget(),
+            "Load YOLO Model",
+            "",
+            MODEL_FILE_EXTENSIONS,
+        )
+        if path:
+            logger.debug("Model file selected: %s", path)
+            self.model_file_selected.emit(path)
+
     def _on_camera_action(self) -> None:
         action = self.sender()
         if action is None:

app/video/video_player.py

@@ -0,0 +1,117 @@
+"""VideoPlayer — plays a local video file and delivers frames via frame_ready signal.
+
+The public interface mirrors CameraService so MainWindow can treat both
+interchangeably: both emit frame_ready(QVideoFrame).
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from PySide6.QtCore import QObject, QUrl, Signal, Slot
+from PySide6.QtMultimedia import (
+    QMediaPlayer,
+    QVideoFrame,
+    QVideoSink,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class VideoPlayer(QObject):
+    """
+    Wraps QMediaPlayer + QVideoSink to replay a local video file.
+
+    Signal flow (identical interface to CameraService):
+        VideoPlayer.frame_ready(QVideoFrame) → FrameDispatcher
+
+    Notes:
+        - Playback is real-time (1×) — no seek/pause in this version.
+        - At end-of-file: emits playback_stopped() and stops.
+        - On any error: emits playback_error(str) then playback_stopped().
+    """
+
+    frame_ready = Signal(QVideoFrame)
+    playback_started = Signal()
+    playback_stopped = Signal()
+    playback_error = Signal(str)
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+
+        self._player = QMediaPlayer(self)
+        self._sink = QVideoSink(self)
+
+        self._player.setVideoSink(self._sink)
+
+        self._sink.videoFrameChanged.connect(self._on_frame)
+        self._player.playbackStateChanged.connect(self._on_playback_state_changed)
+        self._player.errorOccurred.connect(self._on_error)
+
+        self._current_path: str | None = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def play(self, path: str) -> None:
+        """Open and start playing a video file."""
+        self.stop()
+        p = Path(path)
+        if not p.exists():
+            msg = f"Video file not found: {path}"
+            logger.error(msg)
+            self.playback_error.emit(msg)
+            return
+
+        self._current_path = path
+        url = QUrl.fromLocalFile(str(p.resolve()))
+        self._player.setSource(url)
+        self._player.play()
+        logger.info("VideoPlayer: starting playback of '%s'", p.name)
+
+    def stop(self) -> None:
+        """Stop playback and clear source."""
+        if self._player.playbackState() != QMediaPlayer.PlaybackState.StoppedState:
+            self._player.stop()
+        self._player.setSource(QUrl())
+        self._current_path = None
+
+    @property
+    def is_playing(self) -> bool:
+        return (
+            self._player.playbackState()
+            == QMediaPlayer.PlaybackState.PlayingState
+        )
+
+    @property
+    def current_path(self) -> str | None:
+        return self._current_path
+
+    # ------------------------------------------------------------------
+    # Private slots
+    # ------------------------------------------------------------------
+
+    @Slot(QVideoFrame)
+    def _on_frame(self, frame: QVideoFrame) -> None:
+        if frame.isValid():
+            self.frame_ready.emit(frame)
+
+    @Slot(QMediaPlayer.PlaybackState)
+    def _on_playback_state_changed(self, state: QMediaPlayer.PlaybackState) -> None:
+        if state == QMediaPlayer.PlaybackState.PlayingState:
+            logger.info("VideoPlayer: playing")
+            self.playback_started.emit()
+        elif state == QMediaPlayer.PlaybackState.StoppedState:
+            logger.info("VideoPlayer: stopped")
+            self.playback_stopped.emit()
+
+    @Slot(QMediaPlayer.Error, str)
+    def _on_error(self, error: QMediaPlayer.Error, error_string: str) -> None:
+        if error == QMediaPlayer.Error.NoError:
+            return
+        msg = f"VideoPlayer error: {error_string}"
+        logger.error(msg)
+        self.playback_error.emit(msg)
+        self.playback_stopped.emit()

models/.gitkeep

@@ -0,0 +1 @@
+

notes/05-mvp-yolo.md

@@ -0,0 +1,505 @@
+# Stan projektu po sesji: YOLO inference + odtwarzanie wideo
+
+Poprzedni stan: `04-mvp-uvc.md`
+
+---
+
+## Kontekst
+
+Po uruchomieniu aplikacji na Mac Mini z kamerą ELP, kolejny krok to weryfikacja
+wytrenowanego modelu YOLO. Wymagania:
+
+- Model działa w **osobnym procesie** — crash workera nie wywala GUI
+- Inference **nie blokuje** i **nie spowalnia** podglądu kamery
+- Worker **ignoruje klatki** dopóki analizuje poprzednią (drop-if-busy)
+- Możliwość wczytania **pliku wideo** zamiast kamery do oceny modelu
+- Bbox narysowany na nowej **warstwie overlay**
+- W przyszłości OCR będzie działał w tym samym procesie co YOLO
+
+---
+
+## Nowe pakiety
+
+### `app/video/`
+
+```
+app/video/
+├── __init__.py
+└── video_player.py
+```
+
+### `app/inference/`
+
+```
+app/inference/
+├── __init__.py
+├── worker.py           # funkcja uruchamiana w subprocess
+├── worker_manager.py   # InferenceManager (QObject) — IPC, polling, auto-restart
+└── bbox_overlay.py     # BboxOverlay(IOverlayLayer) — rysuje bbox+label+conf
+```
+
+---
+
+## Szczegółowy opis zmian
+
+### 1. `app/video/video_player.py` — `VideoPlayer`
+
+Nowa klasa `VideoPlayer(QObject)` — identyczny interfejs sygnałowy jak `CameraService`:
+
+```python
+frame_ready     = Signal(QVideoFrame)
+playback_started = Signal()
+playback_stopped = Signal()
+playback_error   = Signal(str)
+```
+
+Wewnętrznie: `QMediaPlayer` + `QVideoSink`. Obsługuje formaty: `.mp4`, `.avi`,
+`.mov`, `.mkv`, `.m4v`, `.webm` (cokolwiek obsługuje FFmpeg backend Qt).
+
+Odtwarzanie w czasie rzeczywistym (1×). Brak seek/pauzy — tylko Open + Stop.
+
+`MainWindow` podłącza do `FrameDispatcher` albo `CameraService.frame_ready`,
+albo `VideoPlayer.frame_ready` — nigdy obu naraz. Przełączanie przez
+`_switch_to_camera()` / `_switch_to_video()`.
+
+---
+
+### 2. `app/inference/worker.py` — worker process
+
+#### Struktury IPC (NamedTuple — pickle-safe)
+
+```python
+class FramePacket(NamedTuple):
+    frame_id: int
+    raw_bytes: bytes    # RGB, (H×W×3)
+    width: int
+    height: int
+    channels: int       # zawsze 3
+
+class WorkerReadyPacket(NamedTuple):
+    device: str         # "cpu" | "mps" — wysyłany raz po załadowaniu modelu
+
+class ResultPacket(NamedTuple):
+    frame_id: int
+    detections: list    # list of (x1, y1, x2, y2, conf, label)
+    width: int
+    height: int
+    elapsed_ms: float   # czas wywołania model() w ms
+```
+
+#### Protokół IPC
+
+```
+input_queue  ← FramePacket
+output_queue → WorkerReadyPacket  (raz, zaraz po załadowaniu modelu)
+             → ResultPacket       (po każdej analizowanej klatce)
+             → None               (tylko przy błędzie ładowania modelu)
+```
+
+#### `_select_device()` — wybór urządzenia
+
+Wywoływany **raz przy starcie workera** (nie per-frame jak wcześniej):
+
+```python
+def _select_device() -> str:
+    if platform.system() == "Darwin":
+        if torch.backends.mps.is_available():
+            return "mps"   # Metal GPU na macOS
+    return "cpu"
+```
+
+`device` jest przekazywany do `_load_model()` i do każdego wywołania `_infer()`.
+Eliminuje redundantne wykrywanie urządzenia przy każdej klatce.
+
+#### `_infer()` — pomiar czasu
+
+```python
+t0 = time.perf_counter()
+results = model(frame_np, device=device, verbose=False)
+elapsed_ms = (time.perf_counter() - t0) * 1000.0
+```
+
+`elapsed_ms` trafia do `ResultPacket` i jest logowany w managerze przy detekcjach.
+
+---
+
+### 3. `app/inference/worker_manager.py` — `InferenceManager`
+
+#### Sygnały
+
+```python
+detections_ready      = Signal(object, object)  # list[Detection], tuple[int,int]
+detection_count_updated = Signal(int)           # łączna liczba klatek z detekcją
+inference_stats_updated = Signal(str, float)    # device, avg_elapsed_ms
+inference_device_changed = Signal(str)          # emitowany raz po WorkerReadyPacket
+inference_started     = Signal()
+inference_stopped     = Signal()
+inference_error       = Signal(str)
+```
+
+#### Mechanizm drop-if-busy
+
+```python
+def submit_frame(self, frame: QVideoFrame) -> None:
+    if not self.is_running or self._paused or self._busy:
+        return   # klatka odrzucona cicho
+    # konwersja + put_nowait → self._busy = True
+```
+
+`self._busy` wraca do `False` dopiero gdy `_poll_output()` odbierze `ResultPacket`.
+Gwarantuje że nigdy nie ma więcej niż jedna klatka w locie.
+
+#### Konwersja klatki w GUI thread
+
+Zamiast `frame.bits(0)` (dawało tylko płaszczyznę Y dla NV12):
+
+```python
+image = frame.toImage()                           # Qt dekoduje NV12/YUV/MJPG → RGB
+image = image.convertToFormat(Format_RGB32)       # packed BGRX
+arr = np.frombuffer(image.bits(), dtype=np.uint8).reshape((H, W, 4))
+rgb = arr[:, :, [2, 1, 0]].copy()                # BGRX → RGB, drop X
+```
+
+Obsługuje każdy pixel format jaki kamera może dostarczyć.
+
+#### Rolling average elapsed_ms
+
+```python
+_elapsed_window: deque[float]  # maxlen=10
+avg_ms = sum(_elapsed_window) / len(_elapsed_window)
+```
+
+Emitowany przez `inference_stats_updated(device, avg_ms)` po każdym `ResultPacket`.
+
+#### `_poll_output()` — obsługa `WorkerReadyPacket`
+
+```python
+if isinstance(item, WorkerReadyPacket):
+    self._current_device = item.device
+    self.inference_device_changed.emit(item.device)
+    continue
+```
+
+Odróżnienie od `ResultPacket` przez `isinstance` — nie wymaga sentinel wartości.
+
+#### Auto-restart
+
+- Watchdog co 2s sprawdza `process.is_alive()`
+- Timeout 10s bez odpowiedzi → terminate + restart
+- Max 3 restartów (konfigurowalny przez `INFERENCE_MAX_RESTARTS`)
+- Po przekroczeniu: `QMessageBox.critical` + overlay wyłączony
+
+#### Logowanie — tylko detekcje
+
+```python
+if detections:
+    logger.info(
+        "frame %d: %d detection(s) in %.1f ms — %s",
+        packet.frame_id, len(detections), packet.elapsed_ms, conf_summary,
+    )
+```
+
+Klatki bez detekcji: brak logu. `conf_summary = "label 0.94, label 0.81"`.
+
+---
+
+### 4. `app/inference/bbox_overlay.py` — `BboxOverlay`
+
+```python
+class Detection(NamedTuple):
+    x1: float; y1: float; x2: float; y2: float
+    conf: float
+    label: str
+```
+
+Współrzędne w pikselach **oryginalnej klatki**. `paint()` skaluje do `video_rect`:
+
+```python
+scale_x = video_rect.width() / src_w
+scale_y = video_rect.height() / src_h
+wx1 = video_rect.x() + int(det.x1 * scale_x)
+# ...
+```
+
+Każdy bbox: prostokąt w kolorze `BBOX_COLOR` + label `"label 0.87"` na tle
+`BBOX_LABEL_BG_COLOR` nad lewym górnym rogiem boxa (lub wewnątrz gdy brakuje miejsca).
+
+`BboxOverlay.visible = False` domyślnie — pojawia się dopiero po włączeniu inference toggle.
+
+---
+
+### 5. Menu — zmiany w `app/ui/menu_bar.py`
+
+Dodano dwa nowe menu przed istniejącymi:
+
+```
+File
+  ├── Open Video…         QFileDialog (.mp4 .avi .mov .mkv .m4v .webm)
+  └── Close Video         disabled gdy źródło = kamera
+
+Model
+  ├── Load Model…         QFileDialog (.pt .pth)
+  ├── Enable Inference    QAction checkable, disabled do momentu załadowania modelu
+  └── Model: (none)       disabled — info o załadowanym pliku
+```
+
+Nowe sygnały:
+- `video_file_selected(str)` — ścieżka pliku wideo
+- `video_closed()` — powrót do kamery
+- `model_file_selected(str)` — ścieżka modelu
+- `inference_toggled(bool)` — włącz/wyłącz inference
+
+---
+
+### 6. `app/ui/main_window.py` — integracja
+
+#### Przełączanie źródła klatek
+
+```python
+def _switch_to_camera(self):
+    video_player.frame_ready.disconnect(dispatcher.dispatch)
+    camera_service.frame_ready.connect(dispatcher.dispatch)
+
+def _switch_to_video(self):
+    camera_service.frame_ready.disconnect(dispatcher.dispatch)
+    video_player.frame_ready.connect(dispatcher.dispatch)
+```
+
+Dispatcher i wszyscy subskrybenci (CameraView, TelemetryCollector,
+InferenceManager) są podłączeni do dispatchera — źródło klatek jest dla nich
+transparentne.
+
+#### Inference toggle
+
+```python
+def _on_inference_toggled(self, enabled: bool):
+    if enabled:
+        inference.resume()
+        dispatcher.subscribe(inference.submit_frame, drop_if_busy=True)
+        bbox_overlay.visible = True
+        detection_label.setVisible(True)
+    else:
+        inference.pause()
+        dispatcher.unsubscribe(inference.submit_frame)
+        bbox_overlay.clear()
+        bbox_overlay.visible = False
+        detection_label.setVisible(False)
+        telemetry.clear_inference_stats()
+```
+
+`pause()` nie zatrzymuje procesu — tylko blokuje `submit_frame`. Proces
+pozostaje załadowany w pamięci.
+
+#### Status bar — counter detekcji
+
+```python
+self._detection_label = QLabel("")   # addPermanentWidget (prawa strona)
+```
+
+Pokazywany tylko gdy inference włączone. Aktualizowany przez
+`inference.detection_count_updated(int)` → `"Detections: 17 frames"`.
+
+---
+
+### 7. Telemetria + overlay — nowe pola inference
+
+#### `TelemetrySnapshot` — nowe pola
+
+```python
+@dataclass
+class TelemetrySnapshot:
+    # ... istniejące pola ...
+    inference_device: str | None = None    # "cpu" | "mps" | None
+    inference_time_ms: float | None = None  # rolling avg, None gdy wyłączone
+```
+
+#### `TelemetryCollector` — nowe metody
+
+```python
+def set_inference_stats(self, device: str, avg_ms: float) -> None: ...
+def clear_inference_stats(self) -> None: ...
+```
+
+Wywoływane z `MainWindow` przy każdym `inference_stats_updated` i przy
+wyłączeniu inference.
+
+#### `TelemetryOverlay` — nowe wiersze
+
+```
+FPS req   30.0
+FPS got   29.8
+Frame     33.5 ms
+Drop         0
+CPU sys    8.2 %
+CPU core  65.7 %
+Mem        71 MB
+Inf.dev    mps        ← widoczny tylko gdy model załadowany
+Inf.time   87 ms      ← rolling avg ostatnich 10 klatek
+```
+
+Wiersze `Inf.dev` i `Inf.time` znikają gdy inference jest wyłączone
+(`clear_inference_stats()` → pola `None` → `_format_lines` ich nie emituje).
+
+---
+
+### 8. Bugfixes (zidentyfikowane po uruchomieniu)
+
+#### `Unexpected frame size: 921600 bytes for 1280×720`
+
+**Przyczyna:** `frame.bits(0)` zwraca tylko płaszczyznę 0 (luma Y) dla formatów
+planarnych NV12/YUV420P — `1280 × 720 × 1 = 921600` zamiast `1280 × 720 × 3`.
+
+**Naprawa:** zamiana na `frame.toImage() → Format_RGB32 → bits()`. Qt dekoduje
+każdy format wewnętrznie. Identyczna ścieżka jak `CameraView.on_frame()`.
+
+#### `Subscriber not found for removal` (WARNING w logu)
+
+**Przyczyna:** `_on_inference_toggled(False)` wywoływał `dispatcher.unsubscribe()`
+zanim subscriber był dodany (pierwsze wyłączenie przed włączeniem).
+
+**Naprawa:** zmiana poziomu logu z `WARNING` na `DEBUG` w
+`FrameDispatcher.unsubscribe()` — brak subscribera nie jest błędem.
+
+---
+
+## Decyzje architektoniczne
+
+### Osobny proces zamiast wątku
+
+`multiprocessing.Process(context="spawn")` zamiast `QThread` lub `threading.Thread`:
+- Osobny GIL — inference nie blokuje Python event loop GUI
+- Crash workera (segfault, OOM) nie wywala aplikacji
+- `spawn` zamiast `fork` — wymagane na macOS od Python 3.12 (Apple deprecuje `fork`)
+
+### `toImage()` zamiast `bits(0)`
+
+`QVideoFrame.bits(plane)` daje surowe bajty jednej płaszczyzny. W formatach
+planarnych (NV12: Y w plane 0, UV w plane 1) to tylko część obrazu. `toImage()`
+wywołuje wewnętrzny dekoder Qt i zawsze zwraca kompletny obraz niezależnie od
+pixel formatu.
+
+### `WorkerReadyPacket` zamiast osobnego IPC kanału
+
+Worker wysyła `WorkerReadyPacket(device)` do tej samej `output_queue` zaraz
+po załadowaniu modelu. Manager odróżnia go przez `isinstance`. Eliminuje
+potrzebę dodatkowej kolejki lub pipe tylko dla metadanych startu.
+
+### Inference stats przez `TelemetryCollector`, nie bezpośrednio do overlay
+
+`InferenceManager.inference_stats_updated` → `MainWindow._on_inference_stats_updated`
+→ `TelemetryCollector.set_inference_stats()` → `TelemetrySnapshot.inference_*`
+→ `TelemetryOverlay.paint()`.
+
+Alternatywa: bezpośrednie połączenie `InferenceManager → TelemetryOverlay`.
+Wybrano pośrednie przez `TelemetryCollector` bo:
+- `TelemetrySnapshot` jest jedyną strukturą danych opisującą stan systemu
+- CSV logger automatycznie dostaje inference stats bez dodatkowego kodu
+- Overlay ma jeden spójny model danych
+
+---
+
+## Pliki dodane
+
+| Plik | Zawartość |
+|---|---|
+| `app/video/__init__.py` | pusty |
+| `app/video/video_player.py` | `VideoPlayer(QObject)` |
+| `app/inference/__init__.py` | pusty |
+| `app/inference/worker.py` | `run_worker()`, `FramePacket`, `WorkerReadyPacket`, `ResultPacket`, `_select_device()`, `_infer()` |
+| `app/inference/worker_manager.py` | `InferenceManager(QObject)` |
+| `app/inference/bbox_overlay.py` | `Detection(NamedTuple)`, `BboxOverlay(IOverlayLayer)` |
+| `tests/test_bbox_overlay.py` | 16 testów — `Detection`, stan overlay, mapowanie współrzędnych bbox |
+| `tests/test_inference_manager.py` | 13 testów — drop-if-busy, pause/resume, restart counter, is_running |
+
+## Pliki zmienione
+
+| Plik | Co zmieniono |
+|---|---|
+| `app/config.py` | `INFERENCE_WORKER_TIMEOUT_S`, `INFERENCE_MAX_RESTARTS`, `INFERENCE_POLL_INTERVAL_MS`, `INFERENCE_WATCHDOG_INTERVAL_MS`, `BBOX_COLOR`, `BBOX_LABEL_BG_COLOR`, `BBOX_LABEL_TEXT_COLOR`, `BBOX_LINE_WIDTH`, `BBOX_FONT_SIZE`, `VIDEO_FILE_EXTENSIONS`, `MODEL_FILE_EXTENSIONS` |
+| `app/ui/menu_bar.py` | Menu `File` (Open Video…, Close Video), menu `Model` (Load Model…, Enable Inference, Model info) |
+| `app/ui/main_window.py` | `VideoPlayer` lifecycle, `InferenceManager` lifecycle, source switching, detection counter w statusbar, `_on_inference_stats_updated` |
+| `app/telemetry/telemetry_collector.py` | `TelemetrySnapshot.inference_device`, `TelemetrySnapshot.inference_time_ms`, `set_inference_stats()`, `clear_inference_stats()` |
+| `app/overlay/telemetry_overlay.py` | Wiersze `Inf.dev` i `Inf.time` w `_format_lines()` |
+| `app/pipeline/frame_dispatcher.py` | `unsubscribe()` brak subscribera: WARNING → DEBUG |
+| `pyproject.toml` | `[project.optional-dependencies] inference = ["ultralytics>=8.0", "numpy>=1.24"]` |
+| `tests/test_telemetry_collector.py` | `_make_collector()` uzupełniony o `_inference_device=None`, `_inference_time_ms=None` |
+
+---
+
+## Łączna liczba testów
+
+**69 testów, wszystkie zielone.**
+
+| Plik | Liczba testów |
+|---|---|
+| `test_frame_dispatcher.py` | 8 |
+| `test_telemetry_collector.py` | 12 |
+| `test_uvc.py` | 15 |
+| `test_bbox_overlay.py` | 16 |
+| `test_inference_manager.py` | 18 |
+
+---
+
+## Instalacja
+
+```bash
+# Wymagane do inference:
+pip install ultralytics numpy
+# lub:
+pip install -e ".[inference]"
+```
+
+Aplikacja startuje bez tych pakietów — `Load Model…` zostaje aktywne, ale
+`InferenceManager.start()` zgłosi błąd jeśli `ultralytics` nie jest zainstalowany
+(obsłużony przez `try/except ImportError` w workerze → `output_queue.put(None)`
+→ manager emituje `inference_error`).
+
+---
+
+## Uruchamianie
+
+```bash
+# Windows dev
+.venv-win\Scripts\python.exe -m app.main
+
+# Mac Mini
+.venv/bin/python -m app.main
+
+# Mac Mini z plikiem wideo od razu (CLI nie zaimplementowany — użyj File → Open Video…)
+.venv/bin/python -m app.main
+```
+
+---
+
+## Next Steps
+
+1. Przetestować na Mac Mini z kamerą ELP:
+   - czy `_select_device()` wykrywa MPS i loguje `"MPS (Metal) available"`
+   - czy `Inf.dev mps` pojawia się w overlayzie
+   - czy `Inf.time` jest znacząco niższy niż na CPU
+
+2. OCR w tym samym procesie co YOLO:
+   - Worker process może obsługiwać wiele zadań — dodać `OcrTask` do `FramePacket`
+   - lub uruchomić OCR jako osobny subscriber `FrameDispatcher` w osobnym procesie
+
+3. Dodać możliwość regulacji progu confidence (`conf_threshold`) przez menu/dialog
+   — przekazać jako parametr do `run_worker()` w `FramePacket` lub przy starcie
+
+4. `set_active_format()` call po `_log_actual_format()` żeby menu zaznaczało
+   faktycznie działający format (nie żądany) — z poprzedniej sesji
+
+---
+
+## Critical Context
+
+- `WorkerReadyPacket` jest rozróżniany od `ResultPacket` przez `isinstance` —
+  nie używaj `None` jako sentinela dla obu typów
+- `_select_device()` wywołany raz przy starcie — jeśli zmienisz device w trakcie
+  działania, trzeba zrestartować workera
+- `BboxOverlay.on_detections(detections, source_size)` — `source_size` to
+  `tuple[int, int]` (width, height) klatki która była inferowana, nie aktualnego
+  widgetu; potrzebne do poprawnego skalowania przy zmianie rozdzielczości
+- `InferenceManager.pause()` nie zatrzymuje procesu — `submit_frame` tylko
+  sprawdza flagę; model pozostaje załadowany, można szybko wznowić
+- `multiprocessing.get_context("spawn")` — wymagane na macOS/Windows;
+  `fork` jest domyślny na Linux ale niebezpieczny z Qt

pyproject.toml

@@ -8,6 +8,14 @@ dependencies = [
     "psutil>=6.0",
 ]
 
+[project.optional-dependencies]
+# Install inference support: pip install -e ".[inference]"
+# or: pip install ultralytics numpy
+inference = [
+    "ultralytics>=8.0",
+    "numpy>=1.24",
+]
+
 [project.scripts]
 duck-preview = "app.main:main"
 

tests/test_bbox_overlay.py

@@ -0,0 +1,180 @@
+"""Tests for BboxOverlay — coordinate mapping and state management."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+from PySide6.QtCore import QRect, QSize
+
+from app.inference.bbox_overlay import BboxOverlay, Detection
+
+
+class TestDetection:
+    def test_namedtuple_fields(self) -> None:
+        d = Detection(x1=10.0, y1=20.0, x2=100.0, y2=200.0, conf=0.87, label="label")
+        assert d.x1 == 10.0
+        assert d.label == "label"
+        assert d.conf == pytest.approx(0.87)
+
+    def test_immutable(self) -> None:
+        d = Detection(0, 0, 1, 1, 0.5, "x")
+        with pytest.raises(AttributeError):
+            d.conf = 0.9  # type: ignore[misc]
+
+
+class TestBboxOverlayState:
+    def setup_method(self) -> None:
+        self.overlay = BboxOverlay()
+
+    def test_initially_no_detections(self) -> None:
+        assert self.overlay._detections == []
+
+    def test_initially_source_size_empty(self) -> None:
+        assert self.overlay._source_size.isEmpty()
+
+    def test_on_detections_stores_data(self) -> None:
+        dets = [Detection(0, 0, 100, 100, 0.9, "label")]
+        self.overlay.on_detections(dets, (640, 480))
+        assert self.overlay._detections == dets
+        assert self.overlay._source_size == QSize(640, 480)
+
+    def test_clear_removes_detections(self) -> None:
+        self.overlay.on_detections([Detection(0, 0, 10, 10, 0.5, "x")], (100, 100))
+        self.overlay.clear()
+        assert self.overlay._detections == []
+
+    def test_visible_by_default(self) -> None:
+        assert self.overlay.visible is True
+
+    def test_multiple_detections_stored(self) -> None:
+        dets = [
+            Detection(0, 0, 50, 50, 0.9, "label"),
+            Detection(100, 100, 200, 200, 0.75, "label"),
+        ]
+        self.overlay.on_detections(dets, (640, 480))
+        assert len(self.overlay._detections) == 2
+
+    def test_replace_detections_on_new_call(self) -> None:
+        self.overlay.on_detections([Detection(0, 0, 10, 10, 0.5, "x")], (100, 100))
+        self.overlay.on_detections([], (100, 100))
+        assert self.overlay._detections == []
+
+
+class TestBboxOverlayCoordinateMapping:
+    """
+    Verify that BboxOverlay correctly maps source-frame pixel coordinates
+    onto the letterboxed video_rect when painting.
+
+    We don't test actual QPainter output — instead we verify that the
+    QRect values passed to painter.drawRect() correspond to the expected
+    scaled coordinates.
+    """
+
+    def setup_method(self) -> None:
+        self.overlay = BboxOverlay()
+
+    def _make_painter_mock(self):
+        painter = MagicMock()
+        fm = MagicMock()
+        fm.height.return_value = 14
+        fm.ascent.return_value = 11
+        fm.horizontalAdvance.return_value = 60
+        painter.fontMetrics.return_value = fm
+        return painter
+
+    def test_paint_skips_when_no_detections(self) -> None:
+        painter = self._make_painter_mock()
+        self.overlay.paint(painter, QRect(0, 0, 640, 480))
+        painter.drawRect.assert_not_called()
+
+    def test_paint_skips_when_source_size_empty(self) -> None:
+        # detections present but source_size not set
+        self.overlay._detections = [Detection(0, 0, 100, 100, 0.9, "label")]
+        painter = self._make_painter_mock()
+        self.overlay.paint(painter, QRect(0, 0, 640, 480))
+        painter.drawRect.assert_not_called()
+
+    def test_bbox_scaled_to_full_video_rect(self) -> None:
+        """
+        Source: 640×480, covers full frame.
+        video_rect: 640×480 at origin.
+        Detection: full-frame box → should map 1:1.
+        """
+        self.overlay.on_detections(
+            [Detection(0.0, 0.0, 640.0, 480.0, 0.99, "label")],
+            (640, 480),
+        )
+        painter = self._make_painter_mock()
+        video_rect = QRect(0, 0, 640, 480)
+        self.overlay.paint(painter, video_rect)
+
+        # First drawRect call = the bounding box
+        first_call_rect: QRect = painter.drawRect.call_args_list[0][0][0]
+        assert first_call_rect.x() == 0
+        assert first_call_rect.y() == 0
+        assert first_call_rect.width() == 640
+        assert first_call_rect.height() == 480
+
+    def test_bbox_scaled_with_half_size_video_rect(self) -> None:
+        """
+        Source: 640×480, video_rect: 320×240 at origin (0.5× scale).
+        Detection at (64, 48)→(128, 96) should map to (32, 24)→(64, 48).
+        """
+        self.overlay.on_detections(
+            [Detection(64.0, 48.0, 128.0, 96.0, 0.8, "label")],
+            (640, 480),
+        )
+        painter = self._make_painter_mock()
+        video_rect = QRect(0, 0, 320, 240)
+        self.overlay.paint(painter, video_rect)
+
+        first_call_rect: QRect = painter.drawRect.call_args_list[0][0][0]
+        assert first_call_rect.x() == 32
+        assert first_call_rect.y() == 24
+        assert first_call_rect.width() == 32   # (128-64) * 0.5
+        assert first_call_rect.height() == 24  # (96-48) * 0.5
+
+    def test_bbox_offset_by_video_rect_origin(self) -> None:
+        """
+        video_rect at (100, 50) — letterboxed with margins.
+        Detection at origin of source should map to (100, 50).
+        """
+        self.overlay.on_detections(
+            [Detection(0.0, 0.0, 100.0, 100.0, 0.9, "label")],
+            (640, 480),
+        )
+        painter = self._make_painter_mock()
+        # video_rect 320×240 starting at (100, 50)
+        video_rect = QRect(100, 50, 320, 240)
+        self.overlay.paint(painter, video_rect)
+
+        first_call_rect: QRect = painter.drawRect.call_args_list[0][0][0]
+        # x: 100 + int(0 * 320/640) = 100
+        # y:  50 + int(0 * 240/480) =  50
+        assert first_call_rect.x() == 100
+        assert first_call_rect.y() == 50
+
+
+class TestBboxOverlayWorkerPacket:
+    """Test FramePacket and ResultPacket data structures."""
+
+    def test_frame_packet_fields(self) -> None:
+        from app.inference.worker import FramePacket
+        pkt = FramePacket(
+            frame_id=1,
+            raw_bytes=b"\x00" * 12,
+            width=2,
+            height=2,
+            channels=3,
+        )
+        assert pkt.frame_id == 1
+        assert pkt.width == 2
+        assert pkt.channels == 3
+
+    def test_result_packet_fields(self) -> None:
+        from app.inference.worker import ResultPacket
+        pkt = ResultPacket(frame_id=5, detections=[], width=640, height=480)
+        assert pkt.frame_id == 5
+        assert pkt.detections == []
+        assert pkt.width == 640

tests/test_inference_manager.py

@@ -0,0 +1,238 @@
+"""Tests for InferenceManager — drop-if-busy, restart counter, model validation."""
+
+from __future__ import annotations
+
+import sys
+from unittest.mock import MagicMock, patch
+
+import pytest
+from PySide6.QtWidgets import QApplication
+
+from app.inference.worker_manager import InferenceManager
+
+# Ensure a QApplication exists for tests that create Qt objects
+_app = QApplication.instance() or QApplication(sys.argv)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_manager() -> InferenceManager:
+    """Return an InferenceManager without starting any process."""
+    mgr = InferenceManager.__new__(InferenceManager)
+    mgr._model_path = None
+    mgr._process = None
+    mgr._input_queue = None
+    mgr._output_queue = None
+    mgr._stop_event = None
+    mgr._busy = False
+    mgr._frame_id = 0
+    mgr._restart_count = 0
+    mgr._last_result_time = 0.0
+    mgr._paused = False
+    return mgr
+
+
+# ---------------------------------------------------------------------------
+# Model path validation
+# ---------------------------------------------------------------------------
+
+class TestModelPathValidation:
+    def test_start_emits_error_for_missing_file(self, tmp_path) -> None:
+        """start() with non-existent path must NOT spawn a process."""
+        mgr = InferenceManager()
+        errors: list[str] = []
+        mgr.inference_error.connect(errors.append)
+
+        mgr.start(str(tmp_path / "nonexistent.pt"))
+
+        assert errors, "Expected inference_error signal"
+        assert mgr._process is None
+
+    def test_start_does_not_raise_for_existing_file(self, tmp_path) -> None:
+        """start() with existing file should attempt to start (we mock _start_worker)."""
+        model_file = tmp_path / "model.pt"
+        model_file.write_bytes(b"fake")
+
+        mgr = InferenceManager()
+        with patch.object(mgr, "_start_worker") as mock_start:
+            mgr.start(str(model_file))
+            mock_start.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# Drop-if-busy logic
+# ---------------------------------------------------------------------------
+
+class TestDropIfBusy:
+    def test_submit_frame_drops_when_busy(self) -> None:
+        """submit_frame must not enqueue when _busy is True."""
+        mgr = _make_manager()
+        mgr._busy = True
+        mgr._process = MagicMock()
+        mgr._process.is_alive.return_value = True
+        mgr._input_queue = MagicMock()
+
+        frame = MagicMock()
+        frame.isValid.return_value = True
+        mgr.submit_frame(frame)
+
+        mgr._input_queue.put_nowait.assert_not_called()
+
+    def test_submit_frame_drops_when_paused(self) -> None:
+        mgr = _make_manager()
+        mgr._paused = True
+        mgr._process = MagicMock()
+        mgr._process.is_alive.return_value = True
+        mgr._input_queue = MagicMock()
+
+        frame = MagicMock()
+        frame.isValid.return_value = True
+        mgr.submit_frame(frame)
+
+        mgr._input_queue.put_nowait.assert_not_called()
+
+    def test_submit_frame_drops_when_not_running(self) -> None:
+        mgr = _make_manager()
+        mgr._process = None
+        mgr._input_queue = MagicMock()
+
+        frame = MagicMock()
+        frame.isValid.return_value = True
+        mgr.submit_frame(frame)
+
+        mgr._input_queue.put_nowait.assert_not_called()
+
+    def test_submit_frame_drops_invalid_frame(self) -> None:
+        mgr = _make_manager()
+        mgr._process = MagicMock()
+        mgr._process.is_alive.return_value = True
+        mgr._input_queue = MagicMock()
+
+        frame = MagicMock()
+        frame.isValid.return_value = False
+        mgr.submit_frame(frame)
+
+        mgr._input_queue.put_nowait.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# Pause / resume
+# ---------------------------------------------------------------------------
+
+class TestPauseResume:
+    def test_pause_sets_flag(self) -> None:
+        mgr = _make_manager()
+        assert mgr._paused is False
+        mgr.pause()
+        assert mgr._paused is True
+
+    def test_resume_clears_flag(self) -> None:
+        mgr = _make_manager()
+        mgr.pause()
+        mgr.resume()
+        assert mgr._paused is False
+
+    def test_is_paused_property(self) -> None:
+        mgr = _make_manager()
+        assert mgr.is_paused is False
+        mgr.pause()
+        assert mgr.is_paused is True
+
+
+# ---------------------------------------------------------------------------
+# Restart counter
+# ---------------------------------------------------------------------------
+
+class TestRestartCounter:
+    def test_handle_crash_increments_counter(self) -> None:
+        mgr = InferenceManager()
+        mgr._model_path = "fake.pt"
+        mgr._restart_count = 0
+
+        with (
+            patch.object(mgr, "_start_worker"),
+            patch.object(mgr._poll_timer, "stop"),
+            patch.object(mgr._watchdog_timer, "stop"),
+        ):
+            mgr._handle_crash("test crash")
+
+        assert mgr._restart_count == 1
+
+    def test_handle_crash_emits_error_after_max_restarts(self) -> None:
+        from app.config import INFERENCE_MAX_RESTARTS
+
+        mgr = InferenceManager()
+        mgr._model_path = "fake.pt"
+        mgr._restart_count = INFERENCE_MAX_RESTARTS
+
+        errors: list[str] = []
+        mgr.inference_error.connect(errors.append)
+
+        with (
+            patch.object(mgr, "_start_worker") as mock_start,
+            patch.object(mgr._poll_timer, "stop"),
+            patch.object(mgr._watchdog_timer, "stop"),
+        ):
+            mgr._handle_crash("final crash")
+
+        assert errors, "Expected inference_error signal after max restarts"
+        mock_start.assert_not_called()
+
+    def test_stop_resets_restart_count(self) -> None:
+        mgr = InferenceManager()
+        mgr._restart_count = 2
+
+        with patch.object(mgr, "_stop_worker"):
+            mgr.stop()
+
+        assert mgr._restart_count == 0
+
+
+# ---------------------------------------------------------------------------
+# is_running property
+# ---------------------------------------------------------------------------
+
+class TestIsRunning:
+    def test_not_running_when_process_is_none(self) -> None:
+        mgr = _make_manager()
+        assert mgr.is_running is False
+
+    def test_not_running_when_process_dead(self) -> None:
+        mgr = _make_manager()
+        proc = MagicMock()
+        proc.is_alive.return_value = False
+        mgr._process = proc
+        assert mgr.is_running is False
+
+    def test_running_when_process_alive(self) -> None:
+        mgr = _make_manager()
+        proc = MagicMock()
+        proc.is_alive.return_value = True
+        mgr._process = proc
+        assert mgr.is_running is True
+
+
+# ---------------------------------------------------------------------------
+# Worker data structures
+# ---------------------------------------------------------------------------
+
+class TestWorkerDataStructures:
+    def test_frame_packet_is_immutable(self) -> None:
+        from app.inference.worker import FramePacket
+        pkt = FramePacket(1, b"", 640, 480, 3)
+        with pytest.raises(AttributeError):
+            pkt.frame_id = 2  # type: ignore[misc]
+
+    def test_result_packet_is_immutable(self) -> None:
+        from app.inference.worker import ResultPacket
+        pkt = ResultPacket(1, [], 640, 480)
+        with pytest.raises(AttributeError):
+            pkt.frame_id = 2  # type: ignore[misc]
+
+    def test_select_device_returns_string(self) -> None:
+        from app.inference.worker import _select_device
+        device = _select_device()
+        assert isinstance(device, str)
+        assert device in ("cpu", "mps", "cuda")

tests/test_telemetry_collector.py

@@ -33,6 +33,9 @@ class TestTelemetryCollector:
         mem_info.rss = 70 * 1024 * 1024    # RSS (larger, includes shared)
         col._process.memory_info.return_value = mem_info
         col._process.cpu_percent.return_value = 0.0
+        # Inference stats — None by default (inference disabled)
+        col._inference_device = None
+        col._inference_time_ms = None
         return col
 
     def test_initial_snapshot_has_zero_fps(self):