real-time-object-detection 1.1.0__py3-none-any.whl

main.py

@@ -0,0 +1,178 @@
+import os
+os.environ["YOLO_VERBOSE"] = "False"
+import sys
+import argparse
+from src import __version__
+from src.pipeline import run_pipeline
+from src.config_loader import load_config
+from src.model import load_model
+from src.camera import open_camera, open_video
+from src.logger import setup_logger, get_logger
+from src.validation import ValidationError
+from src.device_utils import get_device_info, validate_and_fallback
+
+class CustomHelpFormatter(argparse.RawDescriptionHelpFormatter):
+    def __init__(self, prog):
+        super().__init__(prog, max_help_position=42, width=110)
+
+def parse_args() -> argparse.Namespace:
+    is_uv = any(k.startswith("UV") for k in os.environ)
+    is_rtod = sys.argv[0].endswith("rtod") or sys.argv[0].endswith("rtod.exe")
+    if is_uv:
+        cmd = "uv run rtod" if is_rtod else "uv run main.py"
+    else:
+        cmd = "rtod" if is_rtod else "python main.py"
+    parser = argparse.ArgumentParser(
+        description="Real-Time Object Detection using YOLOv8",
+        formatter_class=CustomHelpFormatter,
+        epilog=f"""
+Examples:
+  {cmd}
+  {cmd} --video video.mp4
+  {cmd} --confidence 0.7
+  {cmd} --headless
+  {cmd} --model models/yolov8s.pt
+        """
+    )
+
+    parser.add_argument("--config", type=str, default="config.yaml",
+                        help="Config file path (default: config.yaml)")
+    parser.add_argument("--mode", type=str, choices=["live", "video", "headless", "benchmark"],
+                        help="Execution mode")
+    parser.add_argument("--confidence", type=float, metavar="[0-1]",
+                        help="Detection confidence threshold")
+    parser.add_argument("--camera", type=int, metavar="INDEX",
+                        help="Camera device index")
+    parser.add_argument("--video", type=str, metavar="PATH",
+                        help="Video file path (sets mode to video)")
+    parser.add_argument("--output", type=str, metavar="DIR",
+                        help="Output directory")
+    parser.add_argument("--model", type=str, metavar="PATH",
+                        help="Model file path")
+    parser.add_argument("--device", type=str, choices=["cpu", "cuda", "mps"],
+                        help="Compute device")
+    parser.add_argument("--max-fps", type=float, metavar="N",
+                        help="Maximum FPS limit")
+    parser.add_argument("--headless", action="store_true",
+                        help="No display window (headless mode)")
+    parser.add_argument("--benchmark", action="store_true",
+                        help="Benchmark mode (no display, print metrics)")
+    parser.add_argument("--save-video", action="store_true",
+                        help="Save annotated video output to file")
+    parser.add_argument("-v", "--version", action="version", version=__version__)
+
+    return parser.parse_args()
+
+def main() -> None:
+    args = parse_args()
+    
+    logger = setup_logger()
+    
+    dev_info = get_device_info()
+    if dev_info["cuda_available"]:
+        logger.info(f"GPU available: {dev_info['cuda_device_name']}")
+    else:
+        logger.info("GPU not available, using CPU")
+    
+    try:
+        logger.info("Loading configuration...")
+        cfg = load_config(args.config)
+        logger.info("Configuration loaded successfully")
+    except FileNotFoundError as e:
+        logger.error(f"Config not found: {e}")
+        sys.exit(1)
+    except ValidationError as e:
+        logger.error(f"Config invalid: {e}")
+        sys.exit(1)
+
+    runtime = cfg.get("runtime", {})
+    model_cfg = cfg.get("model", {})
+
+    if args.mode:
+        runtime["mode"] = args.mode
+    if args.video:
+        runtime["mode"] = "video"
+        runtime["video_path"] = args.video
+    if args.confidence is not None:
+        runtime["confidence"] = args.confidence
+    if args.camera is not None:
+        runtime["camera_index"] = args.camera
+    if args.output:
+        runtime["output_dir"] = args.output
+    if args.max_fps is not None:
+        runtime["max_fps"] = args.max_fps
+    if args.headless:
+        runtime["mode"] = "headless"
+    if args.benchmark:
+        runtime["mode"] = "benchmark"
+    if args.save_video:
+        runtime["save_video"] = True
+    if args.model:
+        model_cfg["path"] = args.model
+    if args.device:
+        model_cfg["device"] = args.device
+
+    mode = runtime.get("mode", "live")
+    conf = runtime.get("confidence", 0.5)
+    max_fps = runtime.get("max_fps")
+    window_name = runtime.get("window_name", "Real-Time Object Detector")
+    output_dir = runtime.get("output_dir") or "runs/latest"
+    save_video = runtime.get("save_video", False)
+
+    logger.info(f"Mode: {mode}, Confidence: {conf}, FPS: {max_fps}")
+
+    allowed_classes = runtime.get("allowed_classes")
+    if isinstance(allowed_classes, (list, tuple, set)):
+        allowed_classes = set(allowed_classes)
+    else:
+        allowed_classes = None
+
+    try:
+        logger.info(f"Loading model from {model_cfg.get('path')}...")
+        model = load_model(cfg)
+        logger.info(f"Model loaded on device: {model_cfg.get('device')}")
+    except (ValidationError, RuntimeError) as e:
+        logger.error(f"Model load failed: {e}")
+        sys.exit(1)
+
+    is_video = mode == "video"
+    headless = mode in ("headless", "benchmark")
+    benchmark = mode == "benchmark"
+
+    try:
+        if mode == "video":
+            logger.info(f"Opening video: {runtime.get('video_path')}")
+            cap = open_video(runtime.get("video_path"))
+        else:
+            logger.info(f"Opening camera at index {runtime.get('camera_index', 0)}")
+            cap = open_camera(runtime.get("camera_index", 0))
+        logger.info("Camera/video opened successfully")
+
+        logger.info("Starting detection pipeline...")
+        run_pipeline(
+            cap=cap,
+            model=model,
+            logger=logger,
+            conf=conf,
+            allowed_classes=allowed_classes,
+            window_name=window_name,
+            output_dir=output_dir,
+            max_fps=max_fps,
+            is_video=is_video,
+            headless=headless,
+            benchmark=benchmark,
+            save_video=save_video,
+        )
+        logger.info("Pipeline completed successfully")
+    except KeyboardInterrupt:
+        logger.info("Keyboard interrupt received (Ctrl+C). Exiting pipeline cleanly.")
+        sys.exit(0)
+    except (ValidationError, RuntimeError) as e:
+        logger.error(f"Failed to open camera/video: {e}")
+        sys.exit(1)
+    except Exception as e:
+        logger.error(f"Pipeline failed: {e}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

real_time_object_detection-1.1.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: real-time-object-detection
+Version: 1.1.0
+Summary: A real-time computer vision project that uses a webcam and the YOLOv8 model to detect and label objects as they appear on screen, drawing bounding boxes around them using OpenCV.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=2.4.1
+Requires-Dist: opencv-python>=4.13.0.90
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: scipy>=1.17.0
+Requires-Dist: ultralytics>=8.4.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# Real-Time Object Detection - Computer Vision & YOLOv8 Inference Pipeline
+
+An intelligent computer vision application built with **Python**, **OpenCV**, **Ultralytics YOLOv8**, **SciPy**, and **PyYAML**. It enables real-time object detection and multi-object centroid tracking across live webcam feeds and video files with full analytics reporting (CSV/JSON), optional annotated video recording, class filtering, and high-performance execution modes (`live`, `video`, `headless`, `benchmark`).
+
+---
+
+## Project Overview & Application Architecture
+
+The **Real-Time Object Detection** system leverages an end-to-end vision pipeline to process video frames, identify multi-class targets using neural networks, track object movement across frames, and export structured operational analytics.
+
+The core application architecture follows a modular vision & tracking pipeline:
+
+1. **Configuration & Validation (`src/config_loader.py` & `src/validation.py`):** Loads and validates YAML settings (`config.yaml`) and CLI parameters, validating confidence thresholds, camera indices, frame rates, image sizes (`imgsz`), model paths, and device parameters (`cpu`, `cuda`, `mps`).
+2. **Device Detection & Fallback (`src/device_utils.py`):** Checks GPU availability (CUDA / Apple Silicon MPS) and automatically selects the optimal hardware compute device with automatic CPU fallback.
+3. **Model Loader & Downloader (`src/model.py`):** Initializes the Ultralytics YOLOv8 architecture (e.g. `yolov8n.pt`, `yolov8s.pt`), automatically fetching standard pretrained weights if missing locally.
+4. **Video Stream Handling (`src/camera.py`):** Wraps OpenCV `VideoCapture` streams for low-latency frame reading from webcams or video files with graceful stream termination.
+5. **Detector Engine & Class Filtering (`src/detector.py`):** Runs YOLOv8 inference per frame, converts bounding box structures, applies confidence thresholds, and filters detections against allowed COCO target classes.
+6. **Centroid Multi-Object Tracker (`src/tracker.py`):** Class-aware and box-aware `CentroidTracker` using SciPy Euclidean distance matrices to track object movement, assign unique IDs, record lifetime durations, and detect frame entry/exit events.
+7. **Runtime Analytics & Serialized Exporter (`src/runtime_tracker.py` & `src/exporter.py`):** Aggregates frame rates, object counts, per-class lifetime statistics, and exports structured reports (`summary.json`, `summary.csv`, `run_index.json`).
+8. **Pipeline Engine & GUI Overlay (`src/pipeline.py` & `main.py`):** Drives the processing loop, renders bounding boxes and performance overlays, records output video (`VideoWriter`), and provides the `main.py` entry point with custom formatted help menus.
+
+---
+
+## Core Modules & Features
+
+* **Real-Time Object Detection:** Powered by Ultralytics YOLOv8 for precise multi-class object detection across live video feeds.
+* **Class-Aware Centroid Tracking:** Stable multi-object tracking with persistent object IDs, entrance/exit event triggers, and lifetime duration monitoring.
+* **Dual Input Sources:** Supports live webcam hardware feeds as well as video file inputs (`--video path/to/video.mp4`).
+* **Flexible Execution Modes:** Four distinct runtime operating modes:
+  * `live`: Interactive GUI window displaying real-time webcam feed with object bounding boxes.
+  * `video`: Processes input video files with on-screen bounding boxes and FPS overlays.
+  * `headless`: Background processing without rendering GUI display windows (ideal for headless servers).
+  * `benchmark`: Automated performance benchmark mode calculating total frames, elapsed time, and average FPS.
+* **Annotated Video Saving (`--save-video`):** Optionally records fully annotated detection feeds to MP4 video files using OpenCV `VideoWriter`.
+* **Configurable Class Filtering:** Filter detections to specific target COCO classes (e.g., `person`, `car`, `dog`) via CLI or configuration.
+* **Automatic Hardware Acceleration:** Auto-detects CUDA GPUs or Apple Silicon MPS, gracefully falling back to CPU when acceleration is unavailable.
+* **Comprehensive Analytics Export:** Automatically generates per-run structured reports (`summary.csv`, `summary.json`, `run_index.json`) containing object statistics, total frames, and lifetime aggregates.
+
+---
+
+## Data & Pipeline Details
+
+The system processes video feeds through structured pipeline modules:
+
+| Component / Module | Implementation File | Description & Functionality |
+| :--- | :--- | :--- |
+| **Config Loader** | `src/config_loader.py` | Parses YAML configurations and merges command-line parameter overrides. |
+| **Validator Engine** | `src/validation.py` | Validates model paths, confidence ranges, device selections, FPS limits, and `imgsz`. |
+| **Device Utility** | `src/device_utils.py` | Detects CUDA/MPS hardware capabilities and enforces CPU fallback when needed. |
+| **Model Loader** | `src/model.py` | Loads YOLO neural network instances and auto-downloads standard pretrained weights. |
+| **Camera Interface** | `src/camera.py` | Opens, reads frames, and safely releases webcam hardware or video file streams. |
+| **Detection Engine** | `src/detector.py` | Performs YOLOv8 object inference, confidence thresholding, and target class filtering. |
+| **Centroid Tracker** | `src/tracker.py` | Associates bounding box centroids across frames using Euclidean distance matrix calculations. |
+| **Runtime Tracker** | `src/runtime_tracker.py` | Tracks object entrance/exit events, active frame counts, and per-class aggregate metrics. |
+| **Results Exporter** | `src/exporter.py` | Serializes session analytics to `summary.csv`, `summary.json`, and `run_index.json`. |
+| **Logger Module** | `src/logger.py` | Configures structured logging to console streams and log files. |
+| **Pipeline Runner** | `src/pipeline.py` | Orchestrates the main execution loop, rendering, video recording, and resource teardown. |
+| **Entry Point** | `main.py` | Development entry point featuring custom help formatting, signal handling, and argument parsing. |
+
+---
+
+## Tech Stack & Specifications
+
+* **Language:** Python `>=3.11`
+* **Computer Vision:** OpenCV (`opencv-python>=4.13.0`)
+* **Deep Learning & Inference:** Ultralytics YOLOv8 (`ultralytics>=8.4.8`), PyTorch
+* **Mathematical Utilities:** SciPy (`scipy>=1.17.0`), NumPy (`numpy>=2.4.1`)
+* **Configuration & Serialization:** PyYAML (`pyyaml>=6.0.3`)
+* **Packaging & Tools:** Setuptools (`setuptools>=61.0`)
+* **Testing Suite:** Pytest (`pytest>=9.0.2`)
+
+---
+
+## Environment Setup & Local Development
+
+Follow these steps to set up the development environment and run the application locally:
+
+### Prerequisites
+* **Python 3.11** or higher installed.
+* **Git** installed.
+* **Webcam** (optional, required for live mode).
+
+### Step 1: Clone the Repository
+```bash
+git clone https://github.com/AP-Abhishek/Real-Time-Object-Detector.git
+cd Real-Time-Object-Detector
+```
+
+### Step 2: Create & Activate Virtual Environment
+```bash
+# On Windows
+python -m venv .venv
+.venv\Scripts\activate
+
+# On macOS / Linux
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+### Step 3: Install Dependencies
+```bash
+pip install -r requirements.txt
+```
+
+### Step 4: Run Development Script (`main.py`)
+
+#### 1. Live Webcam Detection (Default)
+```bash
+python main.py
+```
+
+#### 2. Video File Detection
+```bash
+python main.py --video path/to/video.mp4
+```
+
+#### 3. Save Annotated Video Output
+```bash
+python main.py --save-video --output runs/detection_run
+```
+
+#### 4. Headless & Benchmark Modes
+```bash
+# Run without rendering display window
+python main.py --headless
+
+# Performance benchmark mode
+python main.py --benchmark
+```
+
+#### 5. Custom Model & Confidence Threshold
+```bash
+python main.py --model models/yolov8s.pt --confidence 0.7 --device cpu
+```
+
+### Command Line Arguments Reference
+
+```text
+usage: python main.py [-h] [--config CONFIG] [--mode {live,video,headless,benchmark}] [--confidence [0-1]]
+                      [--camera INDEX] [--video PATH] [--output DIR] [--model PATH] [--device {cpu,cuda,mps}]
+                      [--max-fps N] [--headless] [--benchmark] [--save-video] [-v]
+
+Real-Time Object Detection using YOLOv8
+
+options:
+  -h, --help                              show this help message and exit
+  --config CONFIG                         Config file path (default: config.yaml)
+  --mode {live,video,headless,benchmark}  Execution mode
+  --confidence [0-1]                      Detection confidence threshold
+  --camera INDEX                          Camera device index
+  --video PATH                            Video file path (sets mode to video)
+  --output DIR                            Output directory
+  --model PATH                            Model file path
+  --device {cpu,cuda,mps}                 Compute device
+  --max-fps N                             Maximum FPS limit
+  --headless                              No display window (headless mode)
+  --benchmark                             Benchmark mode (no display, print metrics)
+  --save-video                            Save annotated video output to file
+  -v, --version                           show program's version number and exit
+```
+
+### Step 5: Run Automated Test Suite
+```bash
+python -m pytest tests/ -v
+```
+
+---
+
+## Project Structure
+
+```text
+Real-Time-Object-Detector/
+├── models/                            # YOLOv8 model weights (.pt files)
+├── src/
+│   ├── __init__.py                    # Package initializer
+│   ├── camera.py                      # OpenCV VideoCapture wrappers for camera and video
+│   ├── config.py                      # Config dataclass and schema definitions
+│   ├── config_loader.py               # YAML config loader and validator integration
+│   ├── detector.py                    # YOLOv8 inference engine and class filtering
+│   ├── device_utils.py                # CUDA / MPS hardware detection and CPU fallback
+│   ├── exporter.py                    # Export summary JSON, CSV, and index files
+│   ├── logger.py                      # Logging setup and stream/file handler configuration
+│   ├── model.py                       # Ultralytics model loader and auto-downloader
+│   ├── pipeline.py                    # Main detection pipeline, rendering, and recording
+│   ├── runtime_tracker.py             # Per-session object lifecycle and class aggregate tracker
+│   ├── tracker.py                     # CentroidTracker for multi-object tracking and distance association
+│   └── validation.py                  # Input validation rules and ValidationError exception
+├── tests/                             # Automated test suite
+│   ├── __init__.py
+│   ├── conftest.py                    # Pytest fixtures and mock objects
+│   ├── test_config_loader.py          # Config loading and schema validation tests
+│   ├── test_detector.py              # YOLO inference wrapper tests
+│   ├── test_exporter.py              # CSV/JSON summary export tests
+│   ├── test_logger.py                # Logging output tests
+│   ├── test_tracker.py               # Centroid tracker association tests
+│   └── test_validation.py            # Input parameter validation tests
+├── config.yaml                        # Default system configuration file
+├── main.py                            # Development entry point and argument parser
+├── pyproject.toml                     # Project dependencies and metadata manifest
+├── requirements.txt                   # Dependency requirements list
+├── verify_setup.py                    # Setup verification utility script
+└── README.md                          # Comprehensive project documentation
+```

real_time_object_detection-1.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+main.py,sha256=3lOh4_Gv-vknASipKxpdpNYeI1zF-TthKez7k5OoJzo,6575
+src/__init__.py,sha256=LGVQyDsWifdACo7qztwb8RWWHds1E7uQ-ZqD8SAjyw4,22
+src/camera.py,sha256=JqlBHHIlgjXjcbjOThSGcF2wLuOcBuvfCIA2eYc3OpA,1505
+src/config.py,sha256=mQI6YGULx5o3CT9CSsGOnCRYxZaO122uYirTuv4LAtM,749
+src/config_loader.py,sha256=wmoBANwUGlWXj3rZWPoIuxcmEKEG6xFhVhG7im13SWw,618
+src/detector.py,sha256=v5jca3hTYggIxF4dvzLcXtJ68UTBN8iNaiMEMF11w0Q,1420
+src/device_utils.py,sha256=X_SHq_xMiqwO6QYq3-2cT0k3GljVfh2IMLVGIhiHvjI,1189
+src/exporter.py,sha256=CP05b_7Z9qbKNlq1WYeq-lWDREXPw5196bzPMpdhWXc,2857
+src/logger.py,sha256=Od97RKQV0IZuiLN9xnjjG3F2QHxYJqVhU7Th6uPlkpY,1027
+src/model.py,sha256=7-Nud-iuRdGcgu8Q2530rdy-TrsX09rLVaYX-1g5qq4,906
+src/pipeline.py,sha256=xsuDiLD4IjOXGkwTE4UgZG2hsj90P_xQjIkuYDB2Pc8,7512
+src/runtime_tracker.py,sha256=dKfYLsJHlhzsEHe6JssR_GuULK1eTzt13026vKjON3w,5134
+src/tracker.py,sha256=84t_x8O1nVxVl2vJ0lJ8F21kkpoQNHke3BzEncvL3S0,6085
+src/validation.py,sha256=i3jm7yTONR3f5jObqRcyqMGelLlmlOaVww6W2Ipvl-E,4062
+tests/__init__.py,sha256=XRNuNflqPDQupfhmPTpojlgPyH5Gk0mLKdV9cdeZTPU,17
+tests/conftest.py,sha256=-RBG04ukzjTqZiokH_163lVp8N6vQ97u_IMz4ixOK4c,138
+tests/test_config_loader.py,sha256=j3cvszd_gJUiJ2fbUadpNITBvp1FBxmDVYBd94V-b2M,2448
+tests/test_detector.py,sha256=h9zQm-MUk65VOY4A1Qg7SNnCf96R5hcUbSsewOXMwkQ,2581
+tests/test_exporter.py,sha256=g4PHevVzgypxNhlMKSuAONX-EohJMbpyT4gGiFRryDI,2780
+tests/test_logger.py,sha256=14J6fLqEaNcyMXPocDXy8k1R8QzCyh7F5eB781X4tFs,958
+tests/test_tracker.py,sha256=gYtxY6FWi9TWLpydWn9zYsgUruAaNKDyTQzQX9ou1NA,1361
+tests/test_validation.py,sha256=q91weipSkpurB2uDhCct-2PsbxvPDrClw7jAtCrWUGQ,2725
+real_time_object_detection-1.1.0.dist-info/METADATA,sha256=B2j3OHcuIFc8XM8mJjn3xlj7rYB42I4gGm91M_w3iCE,12601
+real_time_object_detection-1.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+real_time_object_detection-1.1.0.dist-info/entry_points.txt,sha256=mvAEkIsyHtgbrChMQJwAnd6AvUWp3JfmGp1V4srBHSk,35
+real_time_object_detection-1.1.0.dist-info/top_level.txt,sha256=GiEHYkrw-QVC6VaRiNrxR8m0WWJ4uZnbZKcsPEHplD4,15
+real_time_object_detection-1.1.0.dist-info/RECORD,,

real_time_object_detection-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

real_time_object_detection-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rtod = main:main

real_time_object_detection-1.1.0.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+main
+src
+tests

src/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.1.0"

src/camera.py

@@ -0,0 +1,46 @@
+import cv2
+from typing import Tuple, Optional, Any
+from src.validation import ValidationError, validate_video_path
+
+def open_camera(index: int = 0) -> cv2.VideoCapture:
+    if not isinstance(index, int) or index < 0:
+        raise ValidationError(f"Camera index must be non-negative int")
+    
+    cap = cv2.VideoCapture(index)
+    if not cap.isOpened():
+        raise RuntimeError(f"Unable to open camera at index {index}")
+    
+    ret, frame = cap.read()
+    if not ret or frame is None:
+        cap.release()
+        raise RuntimeError(f"Camera opened but failed to read frames")
+    
+    return cap
+
+def open_video(path: str) -> cv2.VideoCapture:
+    validate_video_path(path)
+    cap = cv2.VideoCapture(path)
+    if not cap.isOpened():
+        raise RuntimeError(f"Unable to open video: {path}")
+    
+    ret, frame = cap.read()
+    if not ret or frame is None:
+        cap.release()
+        raise RuntimeError(f"Video opened but contains no readable frames: {path}")
+    
+    cap.set(cv2.CAP_PROP_POS_FRAMES, 0)
+    return cap
+
+def read_frame(cap: cv2.VideoCapture) -> Tuple[bool, Optional[Any]]:
+    try:
+        ret, frame = cap.read()
+        return ret, frame
+    except Exception as e:
+        raise RuntimeError(f"Error reading frame: {e}")
+
+def release_camera(cap: cv2.VideoCapture) -> None:
+    if cap is not None:
+        try:
+            cap.release()
+        except Exception as e:
+            print(f"Warning: Error releasing camera: {e}")

src/config.py

@@ -0,0 +1,25 @@
+import yaml
+from pathlib import Path
+
+class Config:
+    def __init__(self, path):
+        self.path = Path(path)
+        if not self.path.exists():
+            raise FileNotFoundError(f"Config not found: {path}")
+        with open(self.path, "r") as f:
+            self.data = yaml.safe_load(f)
+        self._validate()
+
+    def _validate(self):
+        required = ["model", "input", "output", "runtime"]
+        for k in required:
+            if k not in self.data:
+                raise ValueError(f"Missing config section: {k}")
+
+    def get(self, *keys, default=None):
+        ref = self.data
+        for k in keys:
+            if k not in ref:
+                return default
+            ref = ref[k]
+        return ref

src/config_loader.py

@@ -0,0 +1,21 @@
+import yaml
+from pathlib import Path
+from typing import Dict, Any
+from src.validation import validate_config, ValidationError
+
+def load_config(path: str = "config.yaml") -> Dict[str, Any]:
+    config_path = Path(path)
+    
+    if not config_path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+    
+    try:
+        with open(config_path, "r") as f:
+            config = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        raise ValidationError(f"Failed to parse YAML: {e}")
+    
+    if config is None:
+        config = {}
+    
+    return validate_config(config)

src/detector.py

@@ -0,0 +1,43 @@
+from typing import List, Tuple, Optional, Set
+import numpy as np
+from ultralytics import YOLO
+from pathlib import Path
+from src.validation import ValidationError, validate_model_path, validate_frame
+from src.device_utils import validate_and_fallback
+
+from src.model import load_model
+
+def detect(model: YOLO, frame: np.ndarray, conf_threshold: float = 0.5, allowed_classes: Optional[Set] = None) -> List[Tuple[int, int, int, int, str, float]]:
+    validate_frame(frame)
+    
+    if not (0 <= conf_threshold <= 1):
+        raise ValidationError(f"Confidence must be 0-1")
+    
+    try:
+        results = model(frame, conf=conf_threshold, verbose=False)
+    except Exception as e:
+        raise RuntimeError(f"Inference failed: {e}")
+
+    if not results or results[0].boxes is None:
+        return []
+    
+    boxes = results[0].boxes
+    names = model.names
+    detections = []
+
+    for box in boxes:
+        cls_id = int(box.cls[0])
+        label = names.get(cls_id, f"Unknown({cls_id})")
+
+        if allowed_classes is not None and label not in allowed_classes and cls_id not in allowed_classes and str(cls_id) not in allowed_classes:
+            continue
+
+        conf = float(box.conf[0])
+        x1, y1, x2, y2 = map(int, box.xyxy[0])
+
+        if x2 <= x1 or y2 <= y1:
+            continue
+
+        detections.append((x1, y1, x2, y2, label, conf))
+    
+    return detections

src/device_utils.py

@@ -0,0 +1,36 @@
+import torch
+from typing import Literal
+
+def detect_available_device() -> Literal["cpu", "cuda", "mps"]:
+    if torch.cuda.is_available():
+        return "cuda"
+    elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        return "mps"
+    return "cpu"
+
+def get_device_info() -> dict:
+    info = {
+        "cuda_available": torch.cuda.is_available(),
+        "cuda_count": torch.cuda.device_count() if torch.cuda.is_available() else 0,
+        "mps_available": hasattr(torch.backends, "mps") and torch.backends.mps.is_available(),
+        "torch_version": torch.__version__,
+    }
+    
+    if torch.cuda.is_available():
+        info["cuda_device"] = torch.cuda.current_device()
+        info["cuda_device_name"] = torch.cuda.get_device_name(0)
+    
+    return info
+
+def validate_and_fallback(device: str) -> str:
+    if device == "cuda":
+        if torch.cuda.is_available():
+            return "cuda"
+        else:
+            return "cpu"
+    elif device == "mps":
+        if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+            return "mps"
+        else:
+            return "cpu"
+    return "cpu"