# YOLO Overlay
**YOLO Overlay** is a robust Python package that seamlessly integrates YOLOv8 object detection with a custom C DLL to overlay real-time detection boxes directly onto a Windows display. Designed for applications requiring on-screen visualization of object detections in real-time, YOLO Overlay is ideal for live monitoring systems, gaming enhancements, augmented reality applications, and more.
**Disclaimer:** *YOLO Overlay is not affiliated with or endorsed by Ultralytics.*
---
## Table of Contents
1. [Introduction](#introduction)
2. [Features](#features)
3. [Architecture Overview](#architecture-overview)
4. [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Step-by-Step Installation](#step-by-step-installation)
5. [Quick Start Guide](#quick-start-guide)
6. [Detailed Usage](#detailed-usage)
- [Initializing YOLO Overlay](#initializing-yolo-overlay)
- [Running the Overlay](#running-the-overlay)
- [Stopping the Overlay](#stopping-the-overlay)
7. [Configuration](#configuration)
- [Parameters](#parameters)
- [Advanced Configuration](#advanced-configuration)
8. [Customization](#customization)
- [Using a Custom DLL](#using-a-custom-dll)
- [Customizing Detection Colors and Labels](#customizing-detection-colors-and-labels)
9. [Underlying Architecture](#underlying-architecture)
- [Python Components](#python-components)
- [C DLL Components](#c-dll-components)
- [Inter-Process Communication](#inter-process-communication)
10. [Development Guide](#development-guide)
- [Setting Up the Development Environment](#setting-up-the-development-environment)
- [Building the C DLL](#building-the-c-dll)
- [Contributing to the Project](#contributing-to-the-project)
11. [Troubleshooting](#troubleshooting)
- [Common Issues and Solutions](#common-issues-and-solutions)
- [Debugging Techniques](#debugging-techniques)
12. [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq)
13. [Best Practices](#best-practices)
14. [Performance Optimization](#performance-optimization)
15. [Security Considerations](#security-considerations)
16. [License](#license)
17. [Acknowledgements](#acknowledgements)
18. [Contact](#contact)
19. [Appendix](#appendix)
- [Source Code Overview](#source-code-overview)
- [Glossary](#glossary)
---
## Introduction
YOLO Overlay bridges the gap between powerful object detection capabilities provided by YOLOv8 and real-time visualization on Windows displays. By leveraging a custom C DLL, the package efficiently renders detection boxes overlaid on the user's screen with minimal latency, ensuring a smooth and responsive user experience.
### Key Objectives
- **Real-Time Visualization:** Display object detections instantaneously as they are processed.
- **High Performance:** Utilize efficient screen capturing and rendering techniques to maintain system responsiveness.
- **Flexibility:** Support multiple monitors, custom configurations, and optional DLL customization.
- **Ease of Use:** Provide a straightforward API for quick integration into various projects.
---
## Features
YOLO Overlay boasts a range of features designed to provide flexibility, performance, and ease of use:
- **Real-Time Object Detection:**
- Integrates YOLOv8 for state-of-the-art object detection.
- Displays detection boxes in real-time directly on the user's display.
- **Adjustable Parameters:**
- Configure confidence thresholds to filter detections based on certainty.
- Set maximum bounding boxes to control overlay density.
- **Multi-Monitor Support:**
- Automatically detects and supports multiple monitors with varying resolutions.
- Allows selection of target monitor for overlay.
- **Lightweight and Efficient:**
- Utilizes `ctypes` for seamless interaction between Python and the C DLL.
- Minimal resource consumption ensures system performance remains unaffected.
- **Customizable Overlay:**
- Option to use a custom DLL for tailored overlay behaviors and functionalities.
- **Thread-Safe Operations:**
- Ensures smooth multi-threaded operations between detection processing and overlay rendering.
- **Comprehensive Logging:**
- Debugging logs assist in monitoring the overlay's operations and troubleshooting issues.
---
## Architecture Overview
Understanding the architecture of YOLO Overlay provides insights into how different components interact to deliver real-time object detection overlays.
### 1. Python Components
- **YOLO Overlay Package (`yolo_overlay`):**
- **`overlay.py`:** Manages the lifecycle of the overlay, including initialization, starting, and stopping the overlay.
- **`detection.py`:** Handles screen capturing, performs YOLOv8 detections, and communicates detection data to the C DLL.
- **`utils.py`:** Contains utility functions for color conversion, label encoding, and bounding box sanitization.
### 2. C DLL Components
- **`overlay-yolo.dll`:**
- **Overlay Window Management:** Creates and manages a transparent, topmost window for rendering detection boxes.
- **Rendering Engine:** Draws bounding boxes and labels based on detection data received from Python.
- **Thread Management:** Ensures thread-safe operations for concurrent access to detection data.
- **Exported Functions:** Provides functions like `StartOverlay`, `StopOverlay`, `UpdateDetections`, etc., for interaction with Python.
### 3. Inter-Process Communication
- **`ctypes`:** Facilitates communication between Python and the C DLL, allowing Python to invoke DLL functions and pass detection data structures.
### Data Flow
1. **Screen Capture:** Python captures the screen using `mss`.
2. **Object Detection:** YOLOv8 processes the captured image to identify objects.
3. **Data Preparation:** Detection results are formatted into `DetectionBox` structures.
4. **Data Transmission:** Python sends detection data to the C DLL via `ctypes`.
5. **Overlay Rendering:** The C DLL receives the data and renders detection boxes on the overlay window in real-time.
---
## Installation
Setting up YOLO Overlay involves several steps, from installing the package to ensuring all dependencies are correctly configured.
### Prerequisites
Before installing YOLO Overlay, ensure the following prerequisites are met:
- **Operating System:** Windows (due to reliance on Windows APIs for overlay rendering).
- **Python Version:** Python 3.8 or later.
- **YOLOv8 Model:** A trained YOLOv8 `.pt` model file.
- **System Requirements:**
- Adequate CPU and GPU resources for real-time object detection.
- Sufficient memory to handle detection processes and overlay rendering.
### Step-by-Step Installation
#### 1. Install the YOLO Overlay Package
Use `pip` to install the package from PyPI:
```bash
pip install yolo-overlay
```
*Alternatively, install directly from the GitHub repository for the latest features:*
```bash
pip install git+https://github.com/wuhplaptop/yolo_overlay.git
```
#### 2. Verify DLL Availability
- **Default DLL (`overlay-yolo.dll`):**
- Included in the package under the `resources` folder.
- Automatically loaded during package initialization.
- **Using a Custom DLL (Optional):**
- Ensure your custom DLL exports the required functions:
- `StartOverlay()`
- `StopOverlay()`
- `UpdateDetections(DetectionBox*, int)`
- `SetTargetMonitorRect(int, int, int, int)`
- `SetMaxDetections(int)`
- Place the custom DLL in a directory included in your system's `PATH` environment variable.
- Alternatively, specify the custom DLL's path during YOLO Overlay initialization.
#### 3. Install Required Python Dependencies
YOLO Overlay automatically installs necessary dependencies during the package installation. These include:
- `ultralytics`: Provides YOLOv8 functionalities.
- `mss`: Facilitates high-performance screen capturing.
- `Pillow`: Handles image processing.
- `screeninfo`: Detects and manages multiple monitors.
*Ensure that `pip` is up-to-date to avoid installation issues:*
```bash
pip install --upgrade pip
```
#### 4. Additional Dependencies (If Needed)
- **C++ Redistributable:**
- The C DLL may require the Microsoft Visual C++ Redistributable. If you encounter DLL loading errors, download and install the [latest C++ Redistributable](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads).
- **CUDA (For GPU Acceleration):**
- If you wish to leverage GPU acceleration for YOLOv8, ensure that CUDA is installed and properly configured on your system.
---
## Quick Start Guide
Kickstart your journey with YOLO Overlay by following this quick start guide. This section provides a minimal example to get you up and running swiftly.
### 1. Prepare Your YOLOv8 Model
Ensure you have a trained YOLOv8 `.pt` model. If you don't have one, you can train a model using the [Ultralytics YOLOv8 documentation](https://docs.ultralytics.com/).
### 2. Sample Script
Create a Python script (e.g., `run_overlay.py`) with the following content:
```python
from yolo_overlay import YOLOOverlay
# Specify the path to your YOLOv8 model
model_path = "path/to/yolo_model.pt"
# Initialize YOLO Overlay
overlay = YOLOOverlay(
model_path=model_path,
dll_path=None, # Optional: Specify a custom DLL path if needed
max_detections=100,
conf_threshold=0.5,
monitor_index=0 # Index of the monitor to overlay on (0 for primary)
)
try:
print("YOLO Overlay is running. Press Ctrl+C to stop.")
while True:
pass # Keep the script running
except KeyboardInterrupt:
overlay.stop()
print("YOLO Overlay has been stopped.")
```
### 3. Run the Script
Execute the script using Python:
```bash
python run_overlay.py
```
Upon execution:
- The overlay window will appear on the specified monitor, displaying detection boxes in real-time.
- Press `Ctrl+C` in the terminal to gracefully stop the overlay.
### 4. Expected Output
- **Terminal:**
```
[INFO] DLL loaded and functions configured successfully.
[DEBUG] Initializing YOLO model with path: path/to/yolo_model.pt
[INFO] YOLO model successfully loaded from: path/to/yolo_model.pt
[INFO] Selected monitor 0: Monitor(x=0, y=0, width=1920, height=1080)
[INFO] Set target monitor rectangle to: Left=0, Top=0, Right=1920, Bottom=1080
[INFO] Set maximum detections to: 100
[INFO] Overlay started successfully.
[INFO] Detection thread started.
YOLO Overlay is running. Press Ctrl+C to stop.
```
- **Overlay Window:**
- A transparent window displaying bounding boxes and labels over detected objects in real-time.
---
## Detailed Usage
Dive deeper into YOLO Overlay's functionalities with detailed usage instructions. This section covers initialization, running, stopping the overlay, and explains all available parameters.
### Initializing YOLO Overlay
To begin using YOLO Overlay, initialize the `YOLOOverlay` class with the desired configurations.
```python
from yolo_overlay import YOLOOverlay
# Initialize YOLO Overlay with custom parameters
overlay = YOLOOverlay(
model_path="path/to/yolo_model.pt", # Required: Path to YOLOv8 model
dll_path="path/to/custom_overlay.dll", # Optional: Custom DLL path
max_detections=50, # Optional: Maximum detection boxes
conf_threshold=0.6, # Optional: Confidence threshold
monitor_index=1 # Optional: Target monitor index
)
```
### Running the Overlay
Once initialized, the overlay starts automatically and begins rendering detection boxes in real-time. Ensure that your script remains active to keep the overlay running.
```python
try:
print("YOLO Overlay is running. Press Ctrl+C to stop.")
while True:
pass # Keep the script running
except KeyboardInterrupt:
overlay.stop()
print("YOLO Overlay has been stopped.")
```
### Stopping the Overlay
To gracefully stop the overlay and release resources, invoke the `stop()` method.
```python
overlay.stop()
print("YOLO Overlay has been stopped.")
```
### Parameters
#### `YOLOOverlay` Class Initialization Parameters
- **`model_path`** (`str`, **required**):
- **Description:** Path to the YOLOv8 `.pt` model file.
- **Example:** `"models/yolov8n.pt"`
- **`dll_path`** (`str`, *optional*):
- **Description:** Path to a custom DLL. If `None`, the default `overlay-yolo.dll` included in the package is used.
- **Example:** `"custom_dlls/my_overlay.dll"`
- **`max_detections`** (`int`, *optional*, default=`100`):
- **Description:** Maximum number of simultaneous detection boxes to display.
- **Usage:** Limits the number of detections rendered to prevent clutter.
- **Example:** `max_detections=50`
- **`conf_threshold`** (`float`, *optional*, default=`0.5`):
- **Description:** Minimum confidence score required for detections to be displayed.
- **Usage:** Filters out low-confidence detections to enhance overlay quality.
- **Example:** `conf_threshold=0.7`
- **`monitor_index`** (`int`, *optional*, default=`0`):
- **Description:** Index of the monitor to target for the overlay. `0` corresponds to the primary monitor.
- **Usage:** Selects the desired monitor in multi-monitor setups.
- **Example:** `monitor_index=1`
---
## Configuration
YOLO Overlay provides several configuration options to tailor its behavior to specific requirements. This section elaborates on available parameters and advanced configuration settings.
### Parameters
All configuration parameters can be set during the initialization of the `YOLOOverlay` class. Below is a detailed explanation of each parameter:
- **`model_path`** (`str`):
- **Purpose:** Specifies the path to the YOLOv8 model used for object detection.
- **Considerations:** Ensure the model is compatible with YOLOv8 and is properly trained for your use case.
- **`dll_path`** (`str`, optional):
- **Purpose:** Allows the use of a custom C DLL for overlay rendering.
- **Usage:** If not provided, the default `overlay-yolo.dll` is used. Useful for extending functionalities or integrating with other systems.
- **`max_detections`** (`int`, optional):
- **Purpose:** Limits the number of detection boxes displayed to prevent visual clutter and manage performance.
- **Default Value:** `100`
- **Recommendation:** Adjust based on the typical number of objects detected in your application.
- **`conf_threshold`** (`float`, optional):
- **Purpose:** Sets the minimum confidence level for detections to be visualized.
- **Default Value:** `0.5`
- **Recommendation:** Increase for higher precision or decrease to include more detections.
- **`monitor_index`** (`int`, optional):
- **Purpose:** Selects which monitor the overlay should appear on, especially in multi-monitor setups.
- **Default Value:** `0` (primary monitor)
- **Recommendation:** Enumerate available monitors to choose the desired target.
### Advanced Configuration
Beyond the basic parameters, YOLO Overlay offers advanced configuration options to fine-tune its operations.
#### 1. **Adjusting Detection Timeout**
- **Description:** Controls how long a detection remains active before being considered outdated.
- **Implementation:** Modify the `detectionTimeoutMs` variable in the C DLL.
- **Default Value:** `2000` milliseconds (2 seconds)
- **Use Case:** Prevents stale detections from lingering on the screen.
#### 2. **Customizing Overlay Appearance**
- **Transparent Color:** Define the color key used for the transparent background.
- **Default Value:** Bright magenta (`RGB(255, 0, 255)`)
- **Modification:** Change the `transparentColor` variable in the C DLL to use a different color key.
- **Label Display:** Toggle the display of labels alongside bounding boxes.
- **Default Value:** Enabled (`showLabels = 1`)
- **Modification:** Set `showLabels` to `0` in the C DLL to hide labels.
#### 3. **Optimizing Overlay Performance**
- **Reduce Maximum Detections:** Lower `max_detections` to decrease rendering load.
- **Use Lightweight Models:** Opt for smaller YOLOv8 variants (e.g., YOLOv8n) to enhance processing speed.
- **Adjust Frame Rate:** Modify the detection loop's sleep time to control processing frequency.
---
## Customization
YOLO Overlay is designed with flexibility in mind, allowing users to customize various aspects to suit their specific needs. This section explores customization options, including using a custom DLL and tailoring detection colors and labels.
### Using a Custom DLL
If the default overlay behaviors provided by `overlay-yolo.dll` do not meet your requirements, you can integrate a custom C DLL to extend or modify functionalities.
#### Steps to Use a Custom DLL:
1. **Develop Your Custom DLL:**
- Ensure your DLL exports the necessary functions:
- `StartOverlay()`
- `StopOverlay()`
- `UpdateDetections(DetectionBox*, int)`
- `SetTargetMonitorRect(int, int, int, int)`
- `SetMaxDetections(int)`
- Maintain compatibility with the data structures expected by the Python package.
2. **Place the DLL:**
- Save your custom DLL in a directory accessible by your system.
- Optionally, add the directory to your system's `PATH` environment variable.
3. **Specify DLL Path During Initialization:**
- When initializing `YOLOOverlay`, provide the path to your custom DLL.
```python
overlay = YOLOOverlay(
model_path="path/to/yolo_model.pt",
dll_path="path/to/custom_overlay.dll"
)
```
4. **Ensure Compatibility:**
- Verify that your custom DLL adheres to the required function signatures and data structures.
- Test the overlay to ensure detections are rendered correctly.
### Customizing Detection Colors and Labels
Enhance the visual appeal and clarity of detection boxes by customizing colors and labels.
#### 1. **Customizing Detection Colors**
- **Purpose:** Differentiate object types or importance levels using distinct colors.
- **Implementation:**
- Modify the `color` attribute in the `DetectionBox` structure before sending it to the DLL.
- Use the `rgb_to_colorref` utility function to convert RGB values to `COLORREF` format.
```python
from yolo_overlay.utils import rgb_to_colorref
# Define custom colors
COLORS = {
"person": rgb_to_colorref(0, 255, 0), # Green
"vehicle": rgb_to_colorref(0, 0, 255), # Blue
"animal": rgb_to_colorref(255, 0, 0), # Red
# Add more as needed
}
# Assign colors based on label
label = "person"
color = COLORS.get(label, rgb_to_colorref(255, 255, 255)) # Default to white
```
#### 2. **Customizing Detection Labels**
- **Purpose:** Display meaningful or localized labels for detected objects.
- **Implementation:**
- Modify the `label` attribute in the `DetectionBox` structure.
- Use the `encode_label` utility to ensure labels are properly formatted.
```python
from yolo_overlay.utils import encode_label
# Define custom labels
label = "Person"
encoded_label = encode_label(label)
# Assign to DetectionBox
detection_box.label = encoded_label
```
---
## Underlying Architecture
A thorough understanding of YOLO Overlay's architecture facilitates effective utilization and potential customization. This section delves into the interactions between Python components, the C DLL, and the communication mechanisms that enable real-time overlay rendering.
### Python Components
1. **`overlay.py`:**
- **Functionality:** Orchestrates the overlay lifecycle, including initialization, starting, and stopping the overlay.
- **Key Components:**
- **`YOLOOverlay` Class:** Central class managing model loading, DLL interactions, monitor selection, and threading.
- **Thread Management:** Initiates and manages a separate thread for processing detections to ensure non-blocking operations.
2. **`detection.py`:**
- **Functionality:** Handles screen capturing, performs object detection using YOLOv8, and communicates detection data to the C DLL.
- **Key Components:**
- **`DetectionBox` Structure:** Defines the data structure for individual detections, mirroring the C `DetectionBox`.
- **`process_detections` Function:** Core function that captures the screen, processes detections, and updates the overlay.
3. **`utils.py`:**
- **Functionality:** Provides utility functions for color conversion, label encoding, and bounding box sanitization.
- **Key Functions:**
- **`rgb_to_colorref`:** Converts RGB values to `COLORREF` format for the C DLL.
- **`encode_label`:** Encodes labels to a fixed byte length suitable for the C structure.
- **`sanitize_bounding_box`:** Ensures bounding boxes are within monitor bounds and have valid dimensions.
### C DLL Components
1. **`overlay-yolo.dll`:**
- **Functionality:** Manages the creation of the overlay window and renders detection boxes based on data received from Python.
- **Key Components:**
- **Window Management:** Creates a transparent, topmost window using Windows APIs.
- **Rendering Engine:** Draws bounding boxes and labels using GDI functions.
- **Thread Management:** Runs the overlay in a separate thread to handle window messages and rendering.
- **Exported Functions:** Exposes functions (`StartOverlay`, `StopOverlay`, `UpdateDetections`, etc.) for interaction with Python.
2. **Key Data Structures:**
- **`DetectionBox`:**
- **Fields:** `id`, `x`, `y`, `width`, `height`, `color`, `label`, `lastSeen`, `paused`.
- **Purpose:** Represents individual object detections with tracking and rendering information.
### Inter-Process Communication
- **`ctypes`:**
- **Role:** Bridges Python and the C DLL, allowing Python to call DLL functions and pass complex data structures.
- **Usage:**
- **Loading the DLL:** Using `ctypes.WinDLL` to load `overlay-yolo.dll`.
- **Defining Function Signatures:** Specifying argument and return types for DLL functions to ensure correct data transmission.
- **Passing Structures:** Sending arrays of `DetectionBox` structures to the DLL for rendering.
### Data Flow
1. **Screen Capture and Detection:**
- The Python `detection.py` module captures the screen using `mss`.
- The captured image is processed by YOLOv8 to detect objects.
- Detection results are formatted into `DetectionBox` structures.
2. **Data Transmission:**
- Detection data is sent to the C DLL via the `UpdateDetections` function using `ctypes`.
- The DLL receives the data and updates its internal detection array.
3. **Overlay Rendering:**
- The DLL's overlay window retrieves the latest detection data.
- Bounding boxes and labels are drawn over the target monitor in real-time.
- The overlay window is transparent, allowing seamless integration with the user's display.
4. **Thread Management:**
- Python manages detection processing in a separate thread to maintain performance.
- The DLL runs its own message loop in another thread to handle window events and rendering.
---
## Development Guide
For developers interested in contributing to YOLO Overlay or customizing its functionalities, this section provides a comprehensive guide on setting up the development environment, building the C DLL, and contributing to the project.
### Setting Up the Development Environment
1. **Clone the Repository:**
```bash
git clone https://github.com/wuhplaptop/yolo_overlay.git
cd yolo_overlay
```
2. **Create a Virtual Environment:**
```bash
python -m venv venv
venv\Scripts\activate # On Windows
```
3. **Install Python Dependencies:**
```bash
pip install -r requirements.txt
```
4. **Install Development Dependencies:**
```bash
pip install -r dev-requirements.txt
```
### Building the C DLL
To modify or build the C DLL (`overlay-yolo.dll`), follow these steps:
1. **Navigate to the C Source Directory:**
```bash
cd src/c_dll
```
2. **Ensure Necessary Tools are Installed:**
- **Compiler:** Visual Studio with C/C++ development tools.
- **SDKs:** Windows SDK for access to necessary headers and libraries.
3. **Build the DLL:**
- **Using Visual Studio:**
- Open the solution file (`YOLOOverlay.sln`).
- Configure the build (Release/Debug) and platform (x64).
- Build the solution to generate `overlay-yolo.dll`.
- **Using Command Line (MSVC):**
```bash
cl /LD overlay.c /Feoverlay-yolo.dll
```
*Ensure environment variables for MSVC are set correctly.*
4. **Place the DLL:**
- Copy the built `overlay-yolo.dll` to the `resources` folder or a directory accessible by the Python package.
### Contributing to the Project
Contributions enhance the project's robustness and feature set. Here's how you can contribute:
1. **Fork the Repository:**
- Navigate to the [YOLO Overlay GitHub repository](https://github.com/wuhplaptop/yolo_overlay).
- Click on the "Fork" button to create a personal copy.
2. **Clone Your Fork:**
```bash
git clone https://github.com/wuhplaptop/yolo_overlay.git
cd yolo_overlay
```
3. **Create a New Branch:**
```bash
git checkout -b feature/YourFeatureName
```
4. **Implement Your Feature or Fix:**
- Make changes to the Python modules, C DLL, or documentation as needed.
- Ensure adherence to the project's coding standards and guidelines.
5. **Commit Your Changes:**
```bash
git add .
git commit -m "Add [Your Feature]: Brief description"
```
6. **Push to Your Fork:**
```bash
git push origin feature/YourFeatureName
```
7. **Submit a Pull Request:**
- Navigate to your fork on GitHub.
- Click on "Compare & pull request."
- Provide a detailed description of your changes and their purpose.
- Submit the pull request for review.
8. **Address Feedback:**
- Collaborate with maintainers to refine your contribution.
- Make necessary adjustments based on feedback.
### Code Standards and Guidelines
- **Python Code:**
- Follow [PEP 8](https://pep8.org/) style guidelines.
- Write clear, concise, and well-documented code.
- Include docstrings for all public modules, classes, and functions.
- **C Code:**
- Maintain consistent indentation and formatting.
- Use descriptive variable and function names.
- Comment complex logic and important sections for clarity.
- **Documentation:**
- Ensure all new features or changes are reflected in the documentation.
- Maintain clarity and comprehensiveness in explanations.
### Testing
- **Unit Tests:**
- Write unit tests for new functionalities.
- Ensure existing tests pass after changes.
- **Integration Tests:**
- Verify that Python and C components interact seamlessly.
- Test multi-monitor setups and various configurations.
- **Performance Tests:**
- Assess the impact of changes on detection speed and overlay rendering.
- Optimize as necessary to maintain high performance.
---
## Troubleshooting
Encountering issues is common during the development and usage of complex systems like YOLO Overlay. This section provides solutions to common problems and debugging techniques to help you resolve issues effectively.
### Common Issues and Solutions
#### 1. **No Overlay Displayed**
**Symptoms:**
- The overlay window does not appear.
- No detection boxes are rendered on the screen.
**Possible Causes & Solutions:**
- **Operating System Compatibility:**
- **Cause:** Running the package on a non-Windows OS.
- **Solution:** YOLO Overlay is Windows-only. Ensure you're using a compatible Windows version.
- **DLL Path Issues:**
- **Cause:** Incorrect path to `overlay-yolo.dll` or missing DLL.
- **Solution:** Verify that the DLL exists in the specified path. If using a custom DLL, ensure it's correctly referenced.
- **Monitor Index Misconfiguration:**
- **Cause:** Specified `monitor_index` does not correspond to any connected monitor.
- **Solution:** Enumerate available monitors using `screeninfo.get_monitors()` and set a valid `monitor_index`.
- **Insufficient Permissions:**
- **Cause:** Lack of necessary permissions to create overlay windows.
- **Solution:** Run the script with administrative privileges.
- **Background Processes Blocking Overlay:**
- **Cause:** Other applications or overlays may interfere.
- **Solution:** Close conflicting applications and retry.
#### 2. **Performance Degradation**
**Symptoms:**
- High CPU or GPU usage.
- Laggy or unresponsive overlay rendering.
**Possible Causes & Solutions:**
- **High Number of Detections:**
- **Cause:** `max_detections` set too high.
- **Solution:** Lower `max_detections` to reduce rendering load.
- **Heavy YOLO Model:**
- **Cause:** Using a large YOLOv8 variant (e.g., YOLOv8x) increases processing time.
- **Solution:** Switch to a lighter model (e.g., YOLOv8n) for faster detections.
- **High Frame Rate:**
- **Cause:** Excessive detection frequency.
- **Solution:** Adjust the detection loop's sleep time to reduce FPS (e.g., from 30 FPS to 5 FPS).
- **Inefficient Code in Custom DLL:**
- **Cause:** Suboptimal rendering logic.
- **Solution:** Profile and optimize the C DLL's rendering functions.
#### 3. **DLL Loading Errors**
**Symptoms:**
- Python raises `OSError` related to DLL loading.
- Missing or incompatible DLL functions.
**Possible Causes & Solutions:**
- **Incorrect DLL Path:**
- **Cause:** Provided `dll_path` is incorrect.
- **Solution:** Verify the DLL path and ensure it points to a valid `overlay-yolo.dll` or custom DLL.
- **Missing Dependencies:**
- **Cause:** The DLL depends on other libraries not present on the system.
- **Solution:** Install required dependencies, such as the Microsoft Visual C++ Redistributable.
- **Architecture Mismatch:**
- **Cause:** Using a 32-bit DLL with a 64-bit Python interpreter, or vice versa.
- **Solution:** Ensure the DLL architecture matches the Python interpreter's architecture.
- **Exported Functions Missing:**
- **Cause:** Custom DLL does not export required functions.
- **Solution:** Ensure your custom DLL exports all necessary functions with correct signatures.
#### 4. **Model Loading Failures**
**Symptoms:**
- Errors related to loading the YOLOv8 model.
- `ModuleNotFoundError` or similar exceptions.
**Possible Causes & Solutions:**
- **Invalid Model Path:**
- **Cause:** `model_path` does not point to a valid `.pt` file.
- **Solution:** Confirm the model path and file integrity.
- **Unsupported Model Format:**
- **Cause:** Providing a model trained with an unsupported YOLO version.
- **Solution:** Use models trained with YOLOv8 for compatibility.
- **Missing Ultralytics Package:**
- **Cause:** `ultralytics` not installed or improperly installed.
- **Solution:** Reinstall the package using `pip install ultralytics`.
#### 5. **Overlay Window Not Transparent**
**Symptoms:**
- The overlay window has an opaque background, obscuring underlying content.
**Possible Causes & Solutions:**
- **Incorrect Transparent Color:**
- **Cause:** Mismatch between the transparent color key in Python and the C DLL.
- **Solution:** Ensure both Python and DLL use the same `transparentColor` value.
- **Layered Window Attributes Not Set:**
- **Cause:** Failure to set layered window attributes correctly in the DLL.
- **Solution:** Verify that `SetLayeredWindowAttributes` is called with the correct parameters.
---
### Debugging Techniques
Effective debugging is crucial for identifying and resolving issues. Below are techniques and tools to assist in debugging YOLO Overlay.
#### 1. **Enable Debug Logging**
YOLO Overlay includes debug logs to trace operations and identify issues.
- **Default Behavior:**
- Debugging is enabled by default (`debugMode = 1` in the C DLL).
- **Viewing Logs:**
- Use tools like [DebugView](https://docs.microsoft.com/en-us/sysinternals/downloads/debugview) to monitor `OutputDebugStringA` messages emitted by the DLL.
#### 2. **Python Logging**
Enhance visibility into Python-side operations by integrating Python's logging module.
```python
import logging
# Configure logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)
# Use logger instead of print statements
logger.debug("Debugging message")
```
#### 3. **Check System Resources**
Monitor CPU and GPU usage using Task Manager or Resource Monitor to identify performance bottlenecks.
#### 4. **Validate Data Structures**
Ensure that `DetectionBox` structures are correctly formatted and populated before transmission to the DLL.
```python
from yolo_overlay.detection import DetectionBox
# Example validation
detection_box = DetectionBox(
id=1,
x=100,
y=150,
width=200,
height=250,
color=0x00FF00FF, # Example COLORREF
label=b"Person\x00" + b'\x00' * 49,
lastSeen=123456789,
paused=0
)
# Verify fields
assert detection_box.id == 1
assert detection_box.label.startswith(b"Person")
```
#### 5. **Use Breakpoints in C Code**
If you have access to the C source code:
- **Set Breakpoints:** Use Visual Studio to set breakpoints in critical functions.
- **Step Through Code:** Debug the DLL by stepping through the code to observe its behavior.
#### 6. **Validate Monitor Selection**
Ensure the correct monitor is targeted by printing monitor details.
```python
from screeninfo import get_monitors
for idx, monitor in enumerate(get_monitors()):
print(f"Monitor {idx}: {monitor}")
```
---
## Frequently Asked Questions (FAQ)
### 1. **Is YOLO Overlay compatible with all versions of YOLO?**
**Answer:** YOLO Overlay is specifically designed to work with YOLOv8 models. Compatibility with other YOLO versions has not been tested and may require modifications.
### 2. **Can I use YOLO Overlay on operating systems other than Windows?**
**Answer:** Currently, YOLO Overlay is exclusive to Windows due to its reliance on Windows-specific APIs for overlay rendering. Support for other operating systems is not available.
### 3. **How can I improve detection accuracy?**
**Answer:**
- **Use a High-Quality Model:** Ensure your YOLOv8 model is well-trained and appropriate for your use case.
- **Increase `conf_threshold`:** Setting a higher confidence threshold can reduce false positives.
- **Enhance Image Quality:** Ensure that screen captures are clear and free from obstructions.
### 4. **Why are some detections missing or not displayed?**
**Answer:** Possible reasons include:
- **Confidence Threshold Too High:** Lowering `conf_threshold` may include more detections.
- **Maximum Detections Limit Reached:** Increase `max_detections` if necessary.
- **Bounding Box Sanitization:** Ensure that detected bounding boxes fit within monitor bounds.
### 5. **Can YOLO Overlay run in the background without a visible window?**
**Answer:** YOLO Overlay's overlay window is necessary for rendering detections. However, you can minimize the window or adjust its properties to reduce its visibility while maintaining functionality.
### 6. **How do I select a different monitor for the overlay?**
**Answer:** Use the `monitor_index` parameter during initialization to specify the target monitor. Monitor indices start at `0` for the primary monitor.
```python
overlay = YOLOOverlay(
model_path="path/to/yolo_model.pt",
monitor_index=1 # Selects the second monitor
)
```
### 7. **Can I customize the appearance of detection boxes and labels?**
**Answer:** Yes, you can customize colors and labels by modifying the `color` and `label` fields in the `DetectionBox` structure before sending them to the DLL. Refer to the [Customization](#customization) section for detailed instructions.
### 8. **Is GPU acceleration supported for YOLOv8 in YOLO Overlay?**
**Answer:** YOLOv8 supports GPU acceleration through CUDA. Ensure that your system has a compatible GPU and that CUDA is properly installed and configured to leverage GPU acceleration.
---
## Best Practices
Adhering to best practices ensures optimal performance and reliability when using YOLO Overlay.
### 1. **Use Optimized Models**
- **Select Lightweight Models:** Opt for smaller YOLOv8 variants (e.g., YOLOv8n) to enhance detection speed.
- **Fine-Tune Models:** Train your YOLOv8 model on relevant datasets to improve accuracy for your specific application.
### 2. **Manage Resource Utilization**
- **Monitor System Resources:** Regularly check CPU and GPU usage to prevent system overload.
- **Adjust Parameters:** Fine-tune `max_detections` and `conf_threshold` based on performance metrics.
### 3. **Handle Multi-Monitor Setups Gracefully**
- **Enumerate Monitors:** Use `screeninfo.get_monitors()` to dynamically detect and select monitors.
- **Dynamic Monitor Selection:** Allow users to specify monitor indices via configuration files or command-line arguments.
### 4. **Implement Robust Error Handling**
- **Graceful Degradation:** Ensure the overlay can handle unexpected scenarios without crashing.
- **Informative Logs:** Provide clear and descriptive log messages to aid in troubleshooting.
### 5. **Maintain Up-to-Date Dependencies**
- **Regular Updates:** Keep Python packages and system dependencies updated to benefit from the latest features and security patches.
- **Compatibility Checks:** Verify compatibility when updating major dependencies to prevent breaking changes.
### 6. **Secure Your Overlay**
- **Validate Inputs:** Ensure that data passed between Python and the DLL is properly sanitized to prevent security vulnerabilities.
- **Limit Permissions:** Run scripts with the least required privileges to minimize potential security risks.
---
## Performance Optimization
Optimizing YOLO Overlay's performance is crucial for achieving real-time detection and rendering without compromising system responsiveness.
### 1. **Choose an Appropriate YOLOv8 Model**
- **Lightweight Models:** Use smaller variants like YOLOv8n (nano) or YOLOv8s (small) for faster processing.
- **Model Pruning:** Remove unnecessary layers or reduce model size to enhance speed.
### 2. **Adjust Detection Frequency**
- **Control Frame Rate:** Modify the sleep time in the detection loop to balance between detection accuracy and processing speed.
```python
# Example: Set detection to 5 FPS
sleep_time = max(0, (1/5) - elapsed_time)
time.sleep(sleep_time)
```
### 3. **Optimize Screen Capturing**
- **Limit Capture Area:** If possible, restrict screen capturing to specific regions to reduce processing load.
```python
# Example: Capture a specific region
screenshot = sct.grab({
"left": 100,
"top": 100,
"width": 800,
"height": 600
})
```
- **Reduce Image Resolution:** Downscale captured images before processing to decrease detection time.
### 4. **Enhance DLL Rendering Efficiency**
- **Minimize GDI Calls:** Optimize drawing routines in the C DLL to reduce the number of GDI operations.
- **Batch Rendering:** Group multiple rendering operations to minimize overhead.
### 5. **Leverage Hardware Acceleration**
- **GPU Utilization:** Ensure that YOLOv8 leverages GPU acceleration for faster detections.
- **DLL Optimization:** Utilize GPU-accelerated rendering libraries if applicable.
### 6. **Implement Caching Mechanisms**
- **Detection Caching:** Cache recent detections to avoid redundant processing.
- **Overlay Updates:** Only update portions of the overlay that have changed to reduce rendering load.
### 7. **Profile and Benchmark**
- **Use Profiling Tools:** Identify performance bottlenecks using tools like cProfile (Python) and Visual Studio Profiler (C).
- **Benchmark Different Configurations:** Test various settings to determine optimal parameter values for your system.
---
## Security Considerations
While YOLO Overlay is a powerful tool, it's essential to consider security implications, especially when integrating with system-level components.
### 1. **Secure DLL Interactions**
- **Validate Inputs:** Ensure that all data passed to the DLL is validated and sanitized to prevent buffer overflows or injection attacks.
- **Restrict DLL Sources:** Use only trusted DLLs to avoid introducing malicious code into the system.
### 2. **Manage Permissions Carefully**
- **Run with Least Privileges:** Execute the overlay script with the minimum required permissions to mitigate potential security risks.
- **Avoid Elevated Privileges:** Refrain from running scripts as an administrator unless absolutely necessary.
### 3. **Protect Sensitive Data**
- **Mask Detection Data:** If detections include sensitive information, ensure that it is handled securely.
- **Limit Data Exposure:** Restrict access to detection data and avoid logging sensitive details.
### 4. **Regularly Update Dependencies**
- **Patch Vulnerabilities:** Keep Python packages and system libraries updated to protect against known vulnerabilities.
- **Monitor Security Advisories:** Stay informed about security updates related to the dependencies used by YOLO Overlay.
### 5. **Implement Secure Communication**
- **Integrity Checks:** Ensure that data transmitted between Python and the DLL maintains integrity and is not tampered with.
- **Use Secure Channels:** If extending the communication mechanisms, consider using secure channels to prevent interception.
### 6. **Audit and Review Code**
- **Regular Audits:** Conduct code reviews to identify and rectify potential security flaws.
- **Automated Scanning:** Utilize static and dynamic analysis tools to detect vulnerabilities in the codebase.
---
## License
YOLO Overlay is licensed under the [MIT License](LICENSE), which permits reuse within proprietary software provided all copies include the original license terms and the copyright notice.
---
## Acknowledgements
YOLO Overlay builds upon several outstanding projects and technologies:
- **[YOLOv8 by Ultralytics](https://github.com/ultralytics/yolov8):** Provides the cutting-edge object detection capabilities.
- **[MSS](https://github.com/BoboTiG/python-mss):** Facilitates efficient screen capturing.
- **[Pillow](https://python-pillow.org/):** Handles image processing tasks.
- **[Screeninfo](https://github.com/rr-/screeninfo):** Detects and manages multiple monitors.
- **Windows API:** Powers the overlay window creation and rendering functionalities.
- **[Visual Studio](https://visualstudio.microsoft.com/):** Used for developing and building the C DLL.
---
## Contact
For any questions, issues, or suggestions, please create an issue on our GitHub repository:
- **GitHub Issues:** [YOLO Overlay GitHub Issues](https://github.com/wuhplaptop/yolo_overlay/issues)
---
## Appendix
### Source Code Overview
A deeper understanding of YOLO Overlay's source code can aid in customization and troubleshooting.
#### 1. **`overlay-yolo.dll` (C Code)**
- **Purpose:** Manages the overlay window and renders detection boxes.
- **Key Functionalities:**
- **Window Creation:** Utilizes Windows APIs to create a transparent, topmost window.
- **Rendering:** Draws bounding boxes and labels using GDI functions based on detection data.
- **Thread Management:** Runs the overlay in a separate thread to handle window messages and rendering.
- **Synchronization:** Uses critical sections to ensure thread-safe access to detection data.
- **Exported Functions:**
- `StartOverlay()`: Initializes and starts the overlay window.
- `StopOverlay()`: Terminates the overlay window and cleans up resources.
- `UpdateDetections(DetectionBox*, int)`: Receives detection data from Python to render.
- `SetTargetMonitorRect(int, int, int, int)`: Sets the target monitor's dimensions.
- `SetMaxDetections(int)`: Adjusts the maximum number of detections.
#### 2. **`detection.py`**
- **Purpose:** Handles screen capturing, performs YOLO detections, and communicates with the C DLL.
- **Key Components:**
- **`DetectionBox` Structure:** Mirrors the C `DetectionBox` for data consistency.
- **`process_detections` Function:**
- Captures the screen region.
- Processes the image using YOLOv8 to detect objects.
- Formats detections into `DetectionBox` instances.
- Sends detection data to the DLL via `UpdateDetections`.
#### 3. **`overlay.py`**
- **Purpose:** Coordinates the overlay lifecycle and integrates detections with the overlay.
- **Key Components:**
- **`YOLOOverlay` Class:**
- **Initialization:** Loads the DLL, initializes the YOLO model, and selects the target monitor.
- **Overlay Management:** Starts and stops the overlay, manages detection threads.
- **DLL Interaction:** Configures overlay settings by invoking DLL functions.
#### 4. **`utils.py`**
- **Purpose:** Provides utility functions for internal operations.
- **Key Functions:**
- **`rgb_to_colorref(r, g, b)`**
- Converts RGB color values to `COLORREF` format required by the C DLL.
- **Example:**
```python
colorref = rgb_to_colorref(255, 0, 0) # Red
```
- **`encode_label(label_text)`**
- Encodes label text into a fixed byte format suitable for the C DLL.
- Ensures labels are null-terminated and padded to 50 bytes.
- **Example:**
```python
encoded_label = encode_label("Person")
```
- **`sanitize_bounding_box(x1, y1, x2, y2, monitor_width, monitor_height)`**
- Adjusts bounding box coordinates to fit within monitor bounds.
- Ensures that bounding boxes have valid dimensions (minimum 1 pixel).
- **Example:**
```python
sanitized = sanitize_bounding_box(100, 100, 200, 200, 1920, 1080)
```
### Glossary
- **YOLO (You Only Look Once):** A state-of-the-art, real-time object detection system.
- **DLL (Dynamic-Link Library):** A library that contains code and data used by multiple programs simultaneously.
- **`ctypes`:** A foreign function library for Python that provides C compatible data types and allows calling functions in DLLs or shared libraries.
- **`COLORREF`:** A 32-bit value used in Windows programming to specify an RGB color.
- **GDI (Graphics Device Interface):** A Windows API for representing graphical objects and transmitting them to output devices.
- **`mss`:** A Python library for fast cross-platform screenshots.
- **`screeninfo`:** A Python module to obtain information about connected monitors.
---
# Conclusion
The comprehensive documentation provided above aims to equip users and developers with all the necessary information to effectively utilize, customize, and contribute to the **YOLO Overlay** project. By understanding its features, architecture, and operational mechanisms, users can seamlessly integrate real-time object detection overlays into their Windows applications. Developers, on the other hand, are empowered to extend the project's functionalities, optimize performance, and ensure its continued robustness and relevance.
Feel free to revisit and expand upon these sections as the project evolves, ensuring that the documentation remains up-to-date and continues to serve the needs of its user base.
---
Raw data
{
"_id": null,
"home_page": "https://github.com/wuhplaptop/yolo_overlay",
"name": "yolo-overlay",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "yolo overlay detection computer-vision",
"author": "wuhp",
"author_email": "your.email@example.com",
"download_url": "https://files.pythonhosted.org/packages/a0/f0/e156ec6db0b93c544bde3b07ed807be5c08416d18f13f23485cb75f4ea84/yolo-overlay-0.1.2.tar.gz",
"platform": null,
"description": "# YOLO Overlay\r\n\r\n**YOLO Overlay** is a robust Python package that seamlessly integrates YOLOv8 object detection with a custom C DLL to overlay real-time detection boxes directly onto a Windows display. Designed for applications requiring on-screen visualization of object detections in real-time, YOLO Overlay is ideal for live monitoring systems, gaming enhancements, augmented reality applications, and more.\r\n\r\n**Disclaimer:** *YOLO Overlay is not affiliated with or endorsed by Ultralytics.*\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n1. [Introduction](#introduction)\r\n2. [Features](#features)\r\n3. [Architecture Overview](#architecture-overview)\r\n4. [Installation](#installation)\r\n - [Prerequisites](#prerequisites)\r\n - [Step-by-Step Installation](#step-by-step-installation)\r\n5. [Quick Start Guide](#quick-start-guide)\r\n6. [Detailed Usage](#detailed-usage)\r\n - [Initializing YOLO Overlay](#initializing-yolo-overlay)\r\n - [Running the Overlay](#running-the-overlay)\r\n - [Stopping the Overlay](#stopping-the-overlay)\r\n7. [Configuration](#configuration)\r\n - [Parameters](#parameters)\r\n - [Advanced Configuration](#advanced-configuration)\r\n8. [Customization](#customization)\r\n - [Using a Custom DLL](#using-a-custom-dll)\r\n - [Customizing Detection Colors and Labels](#customizing-detection-colors-and-labels)\r\n9. [Underlying Architecture](#underlying-architecture)\r\n - [Python Components](#python-components)\r\n - [C DLL Components](#c-dll-components)\r\n - [Inter-Process Communication](#inter-process-communication)\r\n10. [Development Guide](#development-guide)\r\n - [Setting Up the Development Environment](#setting-up-the-development-environment)\r\n - [Building the C DLL](#building-the-c-dll)\r\n - [Contributing to the Project](#contributing-to-the-project)\r\n11. [Troubleshooting](#troubleshooting)\r\n - [Common Issues and Solutions](#common-issues-and-solutions)\r\n - [Debugging Techniques](#debugging-techniques)\r\n12. [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq)\r\n13. [Best Practices](#best-practices)\r\n14. [Performance Optimization](#performance-optimization)\r\n15. [Security Considerations](#security-considerations)\r\n16. [License](#license)\r\n17. [Acknowledgements](#acknowledgements)\r\n18. [Contact](#contact)\r\n19. [Appendix](#appendix)\r\n - [Source Code Overview](#source-code-overview)\r\n - [Glossary](#glossary)\r\n\r\n---\r\n\r\n## Introduction\r\n\r\nYOLO Overlay bridges the gap between powerful object detection capabilities provided by YOLOv8 and real-time visualization on Windows displays. By leveraging a custom C DLL, the package efficiently renders detection boxes overlaid on the user's screen with minimal latency, ensuring a smooth and responsive user experience.\r\n\r\n### Key Objectives\r\n\r\n- **Real-Time Visualization:** Display object detections instantaneously as they are processed.\r\n- **High Performance:** Utilize efficient screen capturing and rendering techniques to maintain system responsiveness.\r\n- **Flexibility:** Support multiple monitors, custom configurations, and optional DLL customization.\r\n- **Ease of Use:** Provide a straightforward API for quick integration into various projects.\r\n\r\n---\r\n\r\n## Features\r\n\r\nYOLO Overlay boasts a range of features designed to provide flexibility, performance, and ease of use:\r\n\r\n- **Real-Time Object Detection:**\r\n - Integrates YOLOv8 for state-of-the-art object detection.\r\n - Displays detection boxes in real-time directly on the user's display.\r\n\r\n- **Adjustable Parameters:**\r\n - Configure confidence thresholds to filter detections based on certainty.\r\n - Set maximum bounding boxes to control overlay density.\r\n\r\n- **Multi-Monitor Support:**\r\n - Automatically detects and supports multiple monitors with varying resolutions.\r\n - Allows selection of target monitor for overlay.\r\n\r\n- **Lightweight and Efficient:**\r\n - Utilizes `ctypes` for seamless interaction between Python and the C DLL.\r\n - Minimal resource consumption ensures system performance remains unaffected.\r\n\r\n- **Customizable Overlay:**\r\n - Option to use a custom DLL for tailored overlay behaviors and functionalities.\r\n\r\n- **Thread-Safe Operations:**\r\n - Ensures smooth multi-threaded operations between detection processing and overlay rendering.\r\n\r\n- **Comprehensive Logging:**\r\n - Debugging logs assist in monitoring the overlay's operations and troubleshooting issues.\r\n\r\n---\r\n\r\n## Architecture Overview\r\n\r\nUnderstanding the architecture of YOLO Overlay provides insights into how different components interact to deliver real-time object detection overlays.\r\n\r\n### 1. Python Components\r\n\r\n- **YOLO Overlay Package (`yolo_overlay`):**\r\n - **`overlay.py`:** Manages the lifecycle of the overlay, including initialization, starting, and stopping the overlay.\r\n - **`detection.py`:** Handles screen capturing, performs YOLOv8 detections, and communicates detection data to the C DLL.\r\n - **`utils.py`:** Contains utility functions for color conversion, label encoding, and bounding box sanitization.\r\n\r\n### 2. C DLL Components\r\n\r\n- **`overlay-yolo.dll`:**\r\n - **Overlay Window Management:** Creates and manages a transparent, topmost window for rendering detection boxes.\r\n - **Rendering Engine:** Draws bounding boxes and labels based on detection data received from Python.\r\n - **Thread Management:** Ensures thread-safe operations for concurrent access to detection data.\r\n - **Exported Functions:** Provides functions like `StartOverlay`, `StopOverlay`, `UpdateDetections`, etc., for interaction with Python.\r\n\r\n### 3. Inter-Process Communication\r\n\r\n- **`ctypes`:** Facilitates communication between Python and the C DLL, allowing Python to invoke DLL functions and pass detection data structures.\r\n\r\n### Data Flow\r\n\r\n1. **Screen Capture:** Python captures the screen using `mss`.\r\n2. **Object Detection:** YOLOv8 processes the captured image to identify objects.\r\n3. **Data Preparation:** Detection results are formatted into `DetectionBox` structures.\r\n4. **Data Transmission:** Python sends detection data to the C DLL via `ctypes`.\r\n5. **Overlay Rendering:** The C DLL receives the data and renders detection boxes on the overlay window in real-time.\r\n\r\n---\r\n\r\n## Installation\r\n\r\nSetting up YOLO Overlay involves several steps, from installing the package to ensuring all dependencies are correctly configured.\r\n\r\n### Prerequisites\r\n\r\nBefore installing YOLO Overlay, ensure the following prerequisites are met:\r\n\r\n- **Operating System:** Windows (due to reliance on Windows APIs for overlay rendering).\r\n- **Python Version:** Python 3.8 or later.\r\n- **YOLOv8 Model:** A trained YOLOv8 `.pt` model file.\r\n- **System Requirements:**\r\n - Adequate CPU and GPU resources for real-time object detection.\r\n - Sufficient memory to handle detection processes and overlay rendering.\r\n\r\n### Step-by-Step Installation\r\n\r\n#### 1. Install the YOLO Overlay Package\r\n\r\nUse `pip` to install the package from PyPI:\r\n\r\n```bash\r\npip install yolo-overlay\r\n```\r\n\r\n*Alternatively, install directly from the GitHub repository for the latest features:*\r\n\r\n```bash\r\npip install git+https://github.com/wuhplaptop/yolo_overlay.git\r\n```\r\n\r\n#### 2. Verify DLL Availability\r\n\r\n- **Default DLL (`overlay-yolo.dll`):**\r\n - Included in the package under the `resources` folder.\r\n - Automatically loaded during package initialization.\r\n\r\n- **Using a Custom DLL (Optional):**\r\n - Ensure your custom DLL exports the required functions:\r\n - `StartOverlay()`\r\n - `StopOverlay()`\r\n - `UpdateDetections(DetectionBox*, int)`\r\n - `SetTargetMonitorRect(int, int, int, int)`\r\n - `SetMaxDetections(int)`\r\n - Place the custom DLL in a directory included in your system's `PATH` environment variable.\r\n - Alternatively, specify the custom DLL's path during YOLO Overlay initialization.\r\n\r\n#### 3. Install Required Python Dependencies\r\n\r\nYOLO Overlay automatically installs necessary dependencies during the package installation. These include:\r\n\r\n- `ultralytics`: Provides YOLOv8 functionalities.\r\n- `mss`: Facilitates high-performance screen capturing.\r\n- `Pillow`: Handles image processing.\r\n- `screeninfo`: Detects and manages multiple monitors.\r\n\r\n*Ensure that `pip` is up-to-date to avoid installation issues:*\r\n\r\n```bash\r\npip install --upgrade pip\r\n```\r\n\r\n#### 4. Additional Dependencies (If Needed)\r\n\r\n- **C++ Redistributable:**\r\n - The C DLL may require the Microsoft Visual C++ Redistributable. If you encounter DLL loading errors, download and install the [latest C++ Redistributable](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads).\r\n\r\n- **CUDA (For GPU Acceleration):**\r\n - If you wish to leverage GPU acceleration for YOLOv8, ensure that CUDA is installed and properly configured on your system.\r\n\r\n---\r\n\r\n## Quick Start Guide\r\n\r\nKickstart your journey with YOLO Overlay by following this quick start guide. This section provides a minimal example to get you up and running swiftly.\r\n\r\n### 1. Prepare Your YOLOv8 Model\r\n\r\nEnsure you have a trained YOLOv8 `.pt` model. If you don't have one, you can train a model using the [Ultralytics YOLOv8 documentation](https://docs.ultralytics.com/).\r\n\r\n### 2. Sample Script\r\n\r\nCreate a Python script (e.g., `run_overlay.py`) with the following content:\r\n\r\n```python\r\nfrom yolo_overlay import YOLOOverlay\r\n\r\n# Specify the path to your YOLOv8 model\r\nmodel_path = \"path/to/yolo_model.pt\"\r\n\r\n# Initialize YOLO Overlay\r\noverlay = YOLOOverlay(\r\n model_path=model_path,\r\n dll_path=None, # Optional: Specify a custom DLL path if needed\r\n max_detections=100,\r\n conf_threshold=0.5,\r\n monitor_index=0 # Index of the monitor to overlay on (0 for primary)\r\n)\r\n\r\ntry:\r\n print(\"YOLO Overlay is running. Press Ctrl+C to stop.\")\r\n while True:\r\n pass # Keep the script running\r\nexcept KeyboardInterrupt:\r\n overlay.stop()\r\n print(\"YOLO Overlay has been stopped.\")\r\n```\r\n\r\n### 3. Run the Script\r\n\r\nExecute the script using Python:\r\n\r\n```bash\r\npython run_overlay.py\r\n```\r\n\r\nUpon execution:\r\n\r\n- The overlay window will appear on the specified monitor, displaying detection boxes in real-time.\r\n- Press `Ctrl+C` in the terminal to gracefully stop the overlay.\r\n\r\n### 4. Expected Output\r\n\r\n- **Terminal:**\r\n ```\r\n [INFO] DLL loaded and functions configured successfully.\r\n [DEBUG] Initializing YOLO model with path: path/to/yolo_model.pt\r\n [INFO] YOLO model successfully loaded from: path/to/yolo_model.pt\r\n [INFO] Selected monitor 0: Monitor(x=0, y=0, width=1920, height=1080)\r\n [INFO] Set target monitor rectangle to: Left=0, Top=0, Right=1920, Bottom=1080\r\n [INFO] Set maximum detections to: 100\r\n [INFO] Overlay started successfully.\r\n [INFO] Detection thread started.\r\n YOLO Overlay is running. Press Ctrl+C to stop.\r\n ```\r\n\r\n- **Overlay Window:**\r\n - A transparent window displaying bounding boxes and labels over detected objects in real-time.\r\n\r\n---\r\n\r\n## Detailed Usage\r\n\r\nDive deeper into YOLO Overlay's functionalities with detailed usage instructions. This section covers initialization, running, stopping the overlay, and explains all available parameters.\r\n\r\n### Initializing YOLO Overlay\r\n\r\nTo begin using YOLO Overlay, initialize the `YOLOOverlay` class with the desired configurations.\r\n\r\n```python\r\nfrom yolo_overlay import YOLOOverlay\r\n\r\n# Initialize YOLO Overlay with custom parameters\r\noverlay = YOLOOverlay(\r\n model_path=\"path/to/yolo_model.pt\", # Required: Path to YOLOv8 model\r\n dll_path=\"path/to/custom_overlay.dll\", # Optional: Custom DLL path\r\n max_detections=50, # Optional: Maximum detection boxes\r\n conf_threshold=0.6, # Optional: Confidence threshold\r\n monitor_index=1 # Optional: Target monitor index\r\n)\r\n```\r\n\r\n### Running the Overlay\r\n\r\nOnce initialized, the overlay starts automatically and begins rendering detection boxes in real-time. Ensure that your script remains active to keep the overlay running.\r\n\r\n```python\r\ntry:\r\n print(\"YOLO Overlay is running. Press Ctrl+C to stop.\")\r\n while True:\r\n pass # Keep the script running\r\nexcept KeyboardInterrupt:\r\n overlay.stop()\r\n print(\"YOLO Overlay has been stopped.\")\r\n```\r\n\r\n### Stopping the Overlay\r\n\r\nTo gracefully stop the overlay and release resources, invoke the `stop()` method.\r\n\r\n```python\r\noverlay.stop()\r\nprint(\"YOLO Overlay has been stopped.\")\r\n```\r\n\r\n### Parameters\r\n\r\n#### `YOLOOverlay` Class Initialization Parameters\r\n\r\n- **`model_path`** (`str`, **required**):\r\n - **Description:** Path to the YOLOv8 `.pt` model file.\r\n - **Example:** `\"models/yolov8n.pt\"`\r\n\r\n- **`dll_path`** (`str`, *optional*):\r\n - **Description:** Path to a custom DLL. If `None`, the default `overlay-yolo.dll` included in the package is used.\r\n - **Example:** `\"custom_dlls/my_overlay.dll\"`\r\n\r\n- **`max_detections`** (`int`, *optional*, default=`100`):\r\n - **Description:** Maximum number of simultaneous detection boxes to display.\r\n - **Usage:** Limits the number of detections rendered to prevent clutter.\r\n - **Example:** `max_detections=50`\r\n\r\n- **`conf_threshold`** (`float`, *optional*, default=`0.5`):\r\n - **Description:** Minimum confidence score required for detections to be displayed.\r\n - **Usage:** Filters out low-confidence detections to enhance overlay quality.\r\n - **Example:** `conf_threshold=0.7`\r\n\r\n- **`monitor_index`** (`int`, *optional*, default=`0`):\r\n - **Description:** Index of the monitor to target for the overlay. `0` corresponds to the primary monitor.\r\n - **Usage:** Selects the desired monitor in multi-monitor setups.\r\n - **Example:** `monitor_index=1`\r\n\r\n---\r\n\r\n## Configuration\r\n\r\nYOLO Overlay provides several configuration options to tailor its behavior to specific requirements. This section elaborates on available parameters and advanced configuration settings.\r\n\r\n### Parameters\r\n\r\nAll configuration parameters can be set during the initialization of the `YOLOOverlay` class. Below is a detailed explanation of each parameter:\r\n\r\n- **`model_path`** (`str`):\r\n - **Purpose:** Specifies the path to the YOLOv8 model used for object detection.\r\n - **Considerations:** Ensure the model is compatible with YOLOv8 and is properly trained for your use case.\r\n\r\n- **`dll_path`** (`str`, optional):\r\n - **Purpose:** Allows the use of a custom C DLL for overlay rendering.\r\n - **Usage:** If not provided, the default `overlay-yolo.dll` is used. Useful for extending functionalities or integrating with other systems.\r\n\r\n- **`max_detections`** (`int`, optional):\r\n - **Purpose:** Limits the number of detection boxes displayed to prevent visual clutter and manage performance.\r\n - **Default Value:** `100`\r\n - **Recommendation:** Adjust based on the typical number of objects detected in your application.\r\n\r\n- **`conf_threshold`** (`float`, optional):\r\n - **Purpose:** Sets the minimum confidence level for detections to be visualized.\r\n - **Default Value:** `0.5`\r\n - **Recommendation:** Increase for higher precision or decrease to include more detections.\r\n\r\n- **`monitor_index`** (`int`, optional):\r\n - **Purpose:** Selects which monitor the overlay should appear on, especially in multi-monitor setups.\r\n - **Default Value:** `0` (primary monitor)\r\n - **Recommendation:** Enumerate available monitors to choose the desired target.\r\n\r\n### Advanced Configuration\r\n\r\nBeyond the basic parameters, YOLO Overlay offers advanced configuration options to fine-tune its operations.\r\n\r\n#### 1. **Adjusting Detection Timeout**\r\n\r\n- **Description:** Controls how long a detection remains active before being considered outdated.\r\n- **Implementation:** Modify the `detectionTimeoutMs` variable in the C DLL.\r\n- **Default Value:** `2000` milliseconds (2 seconds)\r\n- **Use Case:** Prevents stale detections from lingering on the screen.\r\n\r\n#### 2. **Customizing Overlay Appearance**\r\n\r\n- **Transparent Color:** Define the color key used for the transparent background.\r\n - **Default Value:** Bright magenta (`RGB(255, 0, 255)`)\r\n - **Modification:** Change the `transparentColor` variable in the C DLL to use a different color key.\r\n\r\n- **Label Display:** Toggle the display of labels alongside bounding boxes.\r\n - **Default Value:** Enabled (`showLabels = 1`)\r\n - **Modification:** Set `showLabels` to `0` in the C DLL to hide labels.\r\n\r\n#### 3. **Optimizing Overlay Performance**\r\n\r\n- **Reduce Maximum Detections:** Lower `max_detections` to decrease rendering load.\r\n- **Use Lightweight Models:** Opt for smaller YOLOv8 variants (e.g., YOLOv8n) to enhance processing speed.\r\n- **Adjust Frame Rate:** Modify the detection loop's sleep time to control processing frequency.\r\n\r\n---\r\n\r\n## Customization\r\n\r\nYOLO Overlay is designed with flexibility in mind, allowing users to customize various aspects to suit their specific needs. This section explores customization options, including using a custom DLL and tailoring detection colors and labels.\r\n\r\n### Using a Custom DLL\r\n\r\nIf the default overlay behaviors provided by `overlay-yolo.dll` do not meet your requirements, you can integrate a custom C DLL to extend or modify functionalities.\r\n\r\n#### Steps to Use a Custom DLL:\r\n\r\n1. **Develop Your Custom DLL:**\r\n - Ensure your DLL exports the necessary functions:\r\n - `StartOverlay()`\r\n - `StopOverlay()`\r\n - `UpdateDetections(DetectionBox*, int)`\r\n - `SetTargetMonitorRect(int, int, int, int)`\r\n - `SetMaxDetections(int)`\r\n - Maintain compatibility with the data structures expected by the Python package.\r\n\r\n2. **Place the DLL:**\r\n - Save your custom DLL in a directory accessible by your system.\r\n - Optionally, add the directory to your system's `PATH` environment variable.\r\n\r\n3. **Specify DLL Path During Initialization:**\r\n - When initializing `YOLOOverlay`, provide the path to your custom DLL.\r\n\r\n ```python\r\n overlay = YOLOOverlay(\r\n model_path=\"path/to/yolo_model.pt\",\r\n dll_path=\"path/to/custom_overlay.dll\"\r\n )\r\n ```\r\n\r\n4. **Ensure Compatibility:**\r\n - Verify that your custom DLL adheres to the required function signatures and data structures.\r\n - Test the overlay to ensure detections are rendered correctly.\r\n\r\n### Customizing Detection Colors and Labels\r\n\r\nEnhance the visual appeal and clarity of detection boxes by customizing colors and labels.\r\n\r\n#### 1. **Customizing Detection Colors**\r\n\r\n- **Purpose:** Differentiate object types or importance levels using distinct colors.\r\n- **Implementation:**\r\n - Modify the `color` attribute in the `DetectionBox` structure before sending it to the DLL.\r\n - Use the `rgb_to_colorref` utility function to convert RGB values to `COLORREF` format.\r\n\r\n ```python\r\n from yolo_overlay.utils import rgb_to_colorref\r\n\r\n # Define custom colors\r\n COLORS = {\r\n \"person\": rgb_to_colorref(0, 255, 0), # Green\r\n \"vehicle\": rgb_to_colorref(0, 0, 255), # Blue\r\n \"animal\": rgb_to_colorref(255, 0, 0), # Red\r\n # Add more as needed\r\n }\r\n\r\n # Assign colors based on label\r\n label = \"person\"\r\n color = COLORS.get(label, rgb_to_colorref(255, 255, 255)) # Default to white\r\n ```\r\n\r\n#### 2. **Customizing Detection Labels**\r\n\r\n- **Purpose:** Display meaningful or localized labels for detected objects.\r\n- **Implementation:**\r\n - Modify the `label` attribute in the `DetectionBox` structure.\r\n - Use the `encode_label` utility to ensure labels are properly formatted.\r\n\r\n ```python\r\n from yolo_overlay.utils import encode_label\r\n\r\n # Define custom labels\r\n label = \"Person\"\r\n encoded_label = encode_label(label)\r\n\r\n # Assign to DetectionBox\r\n detection_box.label = encoded_label\r\n ```\r\n\r\n---\r\n\r\n## Underlying Architecture\r\n\r\nA thorough understanding of YOLO Overlay's architecture facilitates effective utilization and potential customization. This section delves into the interactions between Python components, the C DLL, and the communication mechanisms that enable real-time overlay rendering.\r\n\r\n### Python Components\r\n\r\n1. **`overlay.py`:**\r\n - **Functionality:** Orchestrates the overlay lifecycle, including initialization, starting, and stopping the overlay.\r\n - **Key Components:**\r\n - **`YOLOOverlay` Class:** Central class managing model loading, DLL interactions, monitor selection, and threading.\r\n - **Thread Management:** Initiates and manages a separate thread for processing detections to ensure non-blocking operations.\r\n\r\n2. **`detection.py`:**\r\n - **Functionality:** Handles screen capturing, performs object detection using YOLOv8, and communicates detection data to the C DLL.\r\n - **Key Components:**\r\n - **`DetectionBox` Structure:** Defines the data structure for individual detections, mirroring the C `DetectionBox`.\r\n - **`process_detections` Function:** Core function that captures the screen, processes detections, and updates the overlay.\r\n\r\n3. **`utils.py`:**\r\n - **Functionality:** Provides utility functions for color conversion, label encoding, and bounding box sanitization.\r\n - **Key Functions:**\r\n - **`rgb_to_colorref`:** Converts RGB values to `COLORREF` format for the C DLL.\r\n - **`encode_label`:** Encodes labels to a fixed byte length suitable for the C structure.\r\n - **`sanitize_bounding_box`:** Ensures bounding boxes are within monitor bounds and have valid dimensions.\r\n\r\n### C DLL Components\r\n\r\n1. **`overlay-yolo.dll`:**\r\n - **Functionality:** Manages the creation of the overlay window and renders detection boxes based on data received from Python.\r\n - **Key Components:**\r\n - **Window Management:** Creates a transparent, topmost window using Windows APIs.\r\n - **Rendering Engine:** Draws bounding boxes and labels using GDI functions.\r\n - **Thread Management:** Runs the overlay in a separate thread to handle window messages and rendering.\r\n - **Exported Functions:** Exposes functions (`StartOverlay`, `StopOverlay`, `UpdateDetections`, etc.) for interaction with Python.\r\n\r\n2. **Key Data Structures:**\r\n - **`DetectionBox`:**\r\n - **Fields:** `id`, `x`, `y`, `width`, `height`, `color`, `label`, `lastSeen`, `paused`.\r\n - **Purpose:** Represents individual object detections with tracking and rendering information.\r\n\r\n### Inter-Process Communication\r\n\r\n- **`ctypes`:**\r\n - **Role:** Bridges Python and the C DLL, allowing Python to call DLL functions and pass complex data structures.\r\n - **Usage:**\r\n - **Loading the DLL:** Using `ctypes.WinDLL` to load `overlay-yolo.dll`.\r\n - **Defining Function Signatures:** Specifying argument and return types for DLL functions to ensure correct data transmission.\r\n - **Passing Structures:** Sending arrays of `DetectionBox` structures to the DLL for rendering.\r\n\r\n### Data Flow\r\n\r\n1. **Screen Capture and Detection:**\r\n - The Python `detection.py` module captures the screen using `mss`.\r\n - The captured image is processed by YOLOv8 to detect objects.\r\n - Detection results are formatted into `DetectionBox` structures.\r\n\r\n2. **Data Transmission:**\r\n - Detection data is sent to the C DLL via the `UpdateDetections` function using `ctypes`.\r\n - The DLL receives the data and updates its internal detection array.\r\n\r\n3. **Overlay Rendering:**\r\n - The DLL's overlay window retrieves the latest detection data.\r\n - Bounding boxes and labels are drawn over the target monitor in real-time.\r\n - The overlay window is transparent, allowing seamless integration with the user's display.\r\n\r\n4. **Thread Management:**\r\n - Python manages detection processing in a separate thread to maintain performance.\r\n - The DLL runs its own message loop in another thread to handle window events and rendering.\r\n\r\n---\r\n\r\n## Development Guide\r\n\r\nFor developers interested in contributing to YOLO Overlay or customizing its functionalities, this section provides a comprehensive guide on setting up the development environment, building the C DLL, and contributing to the project.\r\n\r\n### Setting Up the Development Environment\r\n\r\n1. **Clone the Repository:**\r\n\r\n ```bash\r\n git clone https://github.com/wuhplaptop/yolo_overlay.git\r\n cd yolo_overlay\r\n ```\r\n\r\n2. **Create a Virtual Environment:**\r\n\r\n ```bash\r\n python -m venv venv\r\n venv\\Scripts\\activate # On Windows\r\n ```\r\n\r\n3. **Install Python Dependencies:**\r\n\r\n ```bash\r\n pip install -r requirements.txt\r\n ```\r\n\r\n4. **Install Development Dependencies:**\r\n\r\n ```bash\r\n pip install -r dev-requirements.txt\r\n ```\r\n\r\n### Building the C DLL\r\n\r\nTo modify or build the C DLL (`overlay-yolo.dll`), follow these steps:\r\n\r\n1. **Navigate to the C Source Directory:**\r\n\r\n ```bash\r\n cd src/c_dll\r\n ```\r\n\r\n2. **Ensure Necessary Tools are Installed:**\r\n - **Compiler:** Visual Studio with C/C++ development tools.\r\n - **SDKs:** Windows SDK for access to necessary headers and libraries.\r\n\r\n3. **Build the DLL:**\r\n\r\n - **Using Visual Studio:**\r\n - Open the solution file (`YOLOOverlay.sln`).\r\n - Configure the build (Release/Debug) and platform (x64).\r\n - Build the solution to generate `overlay-yolo.dll`.\r\n\r\n - **Using Command Line (MSVC):**\r\n\r\n ```bash\r\n cl /LD overlay.c /Feoverlay-yolo.dll\r\n ```\r\n\r\n *Ensure environment variables for MSVC are set correctly.*\r\n\r\n4. **Place the DLL:**\r\n\r\n - Copy the built `overlay-yolo.dll` to the `resources` folder or a directory accessible by the Python package.\r\n\r\n### Contributing to the Project\r\n\r\nContributions enhance the project's robustness and feature set. Here's how you can contribute:\r\n\r\n1. **Fork the Repository:**\r\n\r\n - Navigate to the [YOLO Overlay GitHub repository](https://github.com/wuhplaptop/yolo_overlay).\r\n - Click on the \"Fork\" button to create a personal copy.\r\n\r\n2. **Clone Your Fork:**\r\n\r\n ```bash\r\n git clone https://github.com/wuhplaptop/yolo_overlay.git\r\n cd yolo_overlay\r\n ```\r\n\r\n3. **Create a New Branch:**\r\n\r\n ```bash\r\n git checkout -b feature/YourFeatureName\r\n ```\r\n\r\n4. **Implement Your Feature or Fix:**\r\n\r\n - Make changes to the Python modules, C DLL, or documentation as needed.\r\n - Ensure adherence to the project's coding standards and guidelines.\r\n\r\n5. **Commit Your Changes:**\r\n\r\n ```bash\r\n git add .\r\n git commit -m \"Add [Your Feature]: Brief description\"\r\n ```\r\n\r\n6. **Push to Your Fork:**\r\n\r\n ```bash\r\n git push origin feature/YourFeatureName\r\n ```\r\n\r\n7. **Submit a Pull Request:**\r\n\r\n - Navigate to your fork on GitHub.\r\n - Click on \"Compare & pull request.\"\r\n - Provide a detailed description of your changes and their purpose.\r\n - Submit the pull request for review.\r\n\r\n8. **Address Feedback:**\r\n\r\n - Collaborate with maintainers to refine your contribution.\r\n - Make necessary adjustments based on feedback.\r\n\r\n### Code Standards and Guidelines\r\n\r\n- **Python Code:**\r\n - Follow [PEP 8](https://pep8.org/) style guidelines.\r\n - Write clear, concise, and well-documented code.\r\n - Include docstrings for all public modules, classes, and functions.\r\n\r\n- **C Code:**\r\n - Maintain consistent indentation and formatting.\r\n - Use descriptive variable and function names.\r\n - Comment complex logic and important sections for clarity.\r\n\r\n- **Documentation:**\r\n - Ensure all new features or changes are reflected in the documentation.\r\n - Maintain clarity and comprehensiveness in explanations.\r\n\r\n### Testing\r\n\r\n- **Unit Tests:**\r\n - Write unit tests for new functionalities.\r\n - Ensure existing tests pass after changes.\r\n\r\n- **Integration Tests:**\r\n - Verify that Python and C components interact seamlessly.\r\n - Test multi-monitor setups and various configurations.\r\n\r\n- **Performance Tests:**\r\n - Assess the impact of changes on detection speed and overlay rendering.\r\n - Optimize as necessary to maintain high performance.\r\n\r\n---\r\n\r\n## Troubleshooting\r\n\r\nEncountering issues is common during the development and usage of complex systems like YOLO Overlay. This section provides solutions to common problems and debugging techniques to help you resolve issues effectively.\r\n\r\n### Common Issues and Solutions\r\n\r\n#### 1. **No Overlay Displayed**\r\n\r\n**Symptoms:**\r\n- The overlay window does not appear.\r\n- No detection boxes are rendered on the screen.\r\n\r\n**Possible Causes & Solutions:**\r\n\r\n- **Operating System Compatibility:**\r\n - **Cause:** Running the package on a non-Windows OS.\r\n - **Solution:** YOLO Overlay is Windows-only. Ensure you're using a compatible Windows version.\r\n\r\n- **DLL Path Issues:**\r\n - **Cause:** Incorrect path to `overlay-yolo.dll` or missing DLL.\r\n - **Solution:** Verify that the DLL exists in the specified path. If using a custom DLL, ensure it's correctly referenced.\r\n\r\n- **Monitor Index Misconfiguration:**\r\n - **Cause:** Specified `monitor_index` does not correspond to any connected monitor.\r\n - **Solution:** Enumerate available monitors using `screeninfo.get_monitors()` and set a valid `monitor_index`.\r\n\r\n- **Insufficient Permissions:**\r\n - **Cause:** Lack of necessary permissions to create overlay windows.\r\n - **Solution:** Run the script with administrative privileges.\r\n\r\n- **Background Processes Blocking Overlay:**\r\n - **Cause:** Other applications or overlays may interfere.\r\n - **Solution:** Close conflicting applications and retry.\r\n\r\n#### 2. **Performance Degradation**\r\n\r\n**Symptoms:**\r\n- High CPU or GPU usage.\r\n- Laggy or unresponsive overlay rendering.\r\n\r\n**Possible Causes & Solutions:**\r\n\r\n- **High Number of Detections:**\r\n - **Cause:** `max_detections` set too high.\r\n - **Solution:** Lower `max_detections` to reduce rendering load.\r\n\r\n- **Heavy YOLO Model:**\r\n - **Cause:** Using a large YOLOv8 variant (e.g., YOLOv8x) increases processing time.\r\n - **Solution:** Switch to a lighter model (e.g., YOLOv8n) for faster detections.\r\n\r\n- **High Frame Rate:**\r\n - **Cause:** Excessive detection frequency.\r\n - **Solution:** Adjust the detection loop's sleep time to reduce FPS (e.g., from 30 FPS to 5 FPS).\r\n\r\n- **Inefficient Code in Custom DLL:**\r\n - **Cause:** Suboptimal rendering logic.\r\n - **Solution:** Profile and optimize the C DLL's rendering functions.\r\n\r\n#### 3. **DLL Loading Errors**\r\n\r\n**Symptoms:**\r\n- Python raises `OSError` related to DLL loading.\r\n- Missing or incompatible DLL functions.\r\n\r\n**Possible Causes & Solutions:**\r\n\r\n- **Incorrect DLL Path:**\r\n - **Cause:** Provided `dll_path` is incorrect.\r\n - **Solution:** Verify the DLL path and ensure it points to a valid `overlay-yolo.dll` or custom DLL.\r\n\r\n- **Missing Dependencies:**\r\n - **Cause:** The DLL depends on other libraries not present on the system.\r\n - **Solution:** Install required dependencies, such as the Microsoft Visual C++ Redistributable.\r\n\r\n- **Architecture Mismatch:**\r\n - **Cause:** Using a 32-bit DLL with a 64-bit Python interpreter, or vice versa.\r\n - **Solution:** Ensure the DLL architecture matches the Python interpreter's architecture.\r\n\r\n- **Exported Functions Missing:**\r\n - **Cause:** Custom DLL does not export required functions.\r\n - **Solution:** Ensure your custom DLL exports all necessary functions with correct signatures.\r\n\r\n#### 4. **Model Loading Failures**\r\n\r\n**Symptoms:**\r\n- Errors related to loading the YOLOv8 model.\r\n- `ModuleNotFoundError` or similar exceptions.\r\n\r\n**Possible Causes & Solutions:**\r\n\r\n- **Invalid Model Path:**\r\n - **Cause:** `model_path` does not point to a valid `.pt` file.\r\n - **Solution:** Confirm the model path and file integrity.\r\n\r\n- **Unsupported Model Format:**\r\n - **Cause:** Providing a model trained with an unsupported YOLO version.\r\n - **Solution:** Use models trained with YOLOv8 for compatibility.\r\n\r\n- **Missing Ultralytics Package:**\r\n - **Cause:** `ultralytics` not installed or improperly installed.\r\n - **Solution:** Reinstall the package using `pip install ultralytics`.\r\n\r\n#### 5. **Overlay Window Not Transparent**\r\n\r\n**Symptoms:**\r\n- The overlay window has an opaque background, obscuring underlying content.\r\n\r\n**Possible Causes & Solutions:**\r\n\r\n- **Incorrect Transparent Color:**\r\n - **Cause:** Mismatch between the transparent color key in Python and the C DLL.\r\n - **Solution:** Ensure both Python and DLL use the same `transparentColor` value.\r\n\r\n- **Layered Window Attributes Not Set:**\r\n - **Cause:** Failure to set layered window attributes correctly in the DLL.\r\n - **Solution:** Verify that `SetLayeredWindowAttributes` is called with the correct parameters.\r\n\r\n---\r\n\r\n### Debugging Techniques\r\n\r\nEffective debugging is crucial for identifying and resolving issues. Below are techniques and tools to assist in debugging YOLO Overlay.\r\n\r\n#### 1. **Enable Debug Logging**\r\n\r\nYOLO Overlay includes debug logs to trace operations and identify issues.\r\n\r\n- **Default Behavior:**\r\n - Debugging is enabled by default (`debugMode = 1` in the C DLL).\r\n\r\n- **Viewing Logs:**\r\n - Use tools like [DebugView](https://docs.microsoft.com/en-us/sysinternals/downloads/debugview) to monitor `OutputDebugStringA` messages emitted by the DLL.\r\n\r\n#### 2. **Python Logging**\r\n\r\nEnhance visibility into Python-side operations by integrating Python's logging module.\r\n\r\n```python\r\nimport logging\r\n\r\n# Configure logging\r\nlogging.basicConfig(level=logging.DEBUG)\r\nlogger = logging.getLogger(__name__)\r\n\r\n# Use logger instead of print statements\r\nlogger.debug(\"Debugging message\")\r\n```\r\n\r\n#### 3. **Check System Resources**\r\n\r\nMonitor CPU and GPU usage using Task Manager or Resource Monitor to identify performance bottlenecks.\r\n\r\n#### 4. **Validate Data Structures**\r\n\r\nEnsure that `DetectionBox` structures are correctly formatted and populated before transmission to the DLL.\r\n\r\n```python\r\nfrom yolo_overlay.detection import DetectionBox\r\n\r\n# Example validation\r\ndetection_box = DetectionBox(\r\n id=1,\r\n x=100,\r\n y=150,\r\n width=200,\r\n height=250,\r\n color=0x00FF00FF, # Example COLORREF\r\n label=b\"Person\\x00\" + b'\\x00' * 49,\r\n lastSeen=123456789,\r\n paused=0\r\n)\r\n\r\n# Verify fields\r\nassert detection_box.id == 1\r\nassert detection_box.label.startswith(b\"Person\")\r\n```\r\n\r\n#### 5. **Use Breakpoints in C Code**\r\n\r\nIf you have access to the C source code:\r\n\r\n- **Set Breakpoints:** Use Visual Studio to set breakpoints in critical functions.\r\n- **Step Through Code:** Debug the DLL by stepping through the code to observe its behavior.\r\n\r\n#### 6. **Validate Monitor Selection**\r\n\r\nEnsure the correct monitor is targeted by printing monitor details.\r\n\r\n```python\r\nfrom screeninfo import get_monitors\r\n\r\nfor idx, monitor in enumerate(get_monitors()):\r\n print(f\"Monitor {idx}: {monitor}\")\r\n```\r\n\r\n---\r\n\r\n## Frequently Asked Questions (FAQ)\r\n\r\n### 1. **Is YOLO Overlay compatible with all versions of YOLO?**\r\n\r\n**Answer:** YOLO Overlay is specifically designed to work with YOLOv8 models. Compatibility with other YOLO versions has not been tested and may require modifications.\r\n\r\n### 2. **Can I use YOLO Overlay on operating systems other than Windows?**\r\n\r\n**Answer:** Currently, YOLO Overlay is exclusive to Windows due to its reliance on Windows-specific APIs for overlay rendering. Support for other operating systems is not available.\r\n\r\n### 3. **How can I improve detection accuracy?**\r\n\r\n**Answer:**\r\n- **Use a High-Quality Model:** Ensure your YOLOv8 model is well-trained and appropriate for your use case.\r\n- **Increase `conf_threshold`:** Setting a higher confidence threshold can reduce false positives.\r\n- **Enhance Image Quality:** Ensure that screen captures are clear and free from obstructions.\r\n\r\n### 4. **Why are some detections missing or not displayed?**\r\n\r\n**Answer:** Possible reasons include:\r\n- **Confidence Threshold Too High:** Lowering `conf_threshold` may include more detections.\r\n- **Maximum Detections Limit Reached:** Increase `max_detections` if necessary.\r\n- **Bounding Box Sanitization:** Ensure that detected bounding boxes fit within monitor bounds.\r\n\r\n### 5. **Can YOLO Overlay run in the background without a visible window?**\r\n\r\n**Answer:** YOLO Overlay's overlay window is necessary for rendering detections. However, you can minimize the window or adjust its properties to reduce its visibility while maintaining functionality.\r\n\r\n### 6. **How do I select a different monitor for the overlay?**\r\n\r\n**Answer:** Use the `monitor_index` parameter during initialization to specify the target monitor. Monitor indices start at `0` for the primary monitor.\r\n\r\n```python\r\noverlay = YOLOOverlay(\r\n model_path=\"path/to/yolo_model.pt\",\r\n monitor_index=1 # Selects the second monitor\r\n)\r\n```\r\n\r\n### 7. **Can I customize the appearance of detection boxes and labels?**\r\n\r\n**Answer:** Yes, you can customize colors and labels by modifying the `color` and `label` fields in the `DetectionBox` structure before sending them to the DLL. Refer to the [Customization](#customization) section for detailed instructions.\r\n\r\n### 8. **Is GPU acceleration supported for YOLOv8 in YOLO Overlay?**\r\n\r\n**Answer:** YOLOv8 supports GPU acceleration through CUDA. Ensure that your system has a compatible GPU and that CUDA is properly installed and configured to leverage GPU acceleration.\r\n\r\n---\r\n\r\n## Best Practices\r\n\r\nAdhering to best practices ensures optimal performance and reliability when using YOLO Overlay.\r\n\r\n### 1. **Use Optimized Models**\r\n\r\n- **Select Lightweight Models:** Opt for smaller YOLOv8 variants (e.g., YOLOv8n) to enhance detection speed.\r\n- **Fine-Tune Models:** Train your YOLOv8 model on relevant datasets to improve accuracy for your specific application.\r\n\r\n### 2. **Manage Resource Utilization**\r\n\r\n- **Monitor System Resources:** Regularly check CPU and GPU usage to prevent system overload.\r\n- **Adjust Parameters:** Fine-tune `max_detections` and `conf_threshold` based on performance metrics.\r\n\r\n### 3. **Handle Multi-Monitor Setups Gracefully**\r\n\r\n- **Enumerate Monitors:** Use `screeninfo.get_monitors()` to dynamically detect and select monitors.\r\n- **Dynamic Monitor Selection:** Allow users to specify monitor indices via configuration files or command-line arguments.\r\n\r\n### 4. **Implement Robust Error Handling**\r\n\r\n- **Graceful Degradation:** Ensure the overlay can handle unexpected scenarios without crashing.\r\n- **Informative Logs:** Provide clear and descriptive log messages to aid in troubleshooting.\r\n\r\n### 5. **Maintain Up-to-Date Dependencies**\r\n\r\n- **Regular Updates:** Keep Python packages and system dependencies updated to benefit from the latest features and security patches.\r\n- **Compatibility Checks:** Verify compatibility when updating major dependencies to prevent breaking changes.\r\n\r\n### 6. **Secure Your Overlay**\r\n\r\n- **Validate Inputs:** Ensure that data passed between Python and the DLL is properly sanitized to prevent security vulnerabilities.\r\n- **Limit Permissions:** Run scripts with the least required privileges to minimize potential security risks.\r\n\r\n---\r\n\r\n## Performance Optimization\r\n\r\nOptimizing YOLO Overlay's performance is crucial for achieving real-time detection and rendering without compromising system responsiveness.\r\n\r\n### 1. **Choose an Appropriate YOLOv8 Model**\r\n\r\n- **Lightweight Models:** Use smaller variants like YOLOv8n (nano) or YOLOv8s (small) for faster processing.\r\n- **Model Pruning:** Remove unnecessary layers or reduce model size to enhance speed.\r\n\r\n### 2. **Adjust Detection Frequency**\r\n\r\n- **Control Frame Rate:** Modify the sleep time in the detection loop to balance between detection accuracy and processing speed.\r\n \r\n ```python\r\n # Example: Set detection to 5 FPS\r\n sleep_time = max(0, (1/5) - elapsed_time)\r\n time.sleep(sleep_time)\r\n ```\r\n\r\n### 3. **Optimize Screen Capturing**\r\n\r\n- **Limit Capture Area:** If possible, restrict screen capturing to specific regions to reduce processing load.\r\n\r\n ```python\r\n # Example: Capture a specific region\r\n screenshot = sct.grab({\r\n \"left\": 100,\r\n \"top\": 100,\r\n \"width\": 800,\r\n \"height\": 600\r\n })\r\n ```\r\n\r\n- **Reduce Image Resolution:** Downscale captured images before processing to decrease detection time.\r\n\r\n### 4. **Enhance DLL Rendering Efficiency**\r\n\r\n- **Minimize GDI Calls:** Optimize drawing routines in the C DLL to reduce the number of GDI operations.\r\n- **Batch Rendering:** Group multiple rendering operations to minimize overhead.\r\n\r\n### 5. **Leverage Hardware Acceleration**\r\n\r\n- **GPU Utilization:** Ensure that YOLOv8 leverages GPU acceleration for faster detections.\r\n- **DLL Optimization:** Utilize GPU-accelerated rendering libraries if applicable.\r\n\r\n### 6. **Implement Caching Mechanisms**\r\n\r\n- **Detection Caching:** Cache recent detections to avoid redundant processing.\r\n- **Overlay Updates:** Only update portions of the overlay that have changed to reduce rendering load.\r\n\r\n### 7. **Profile and Benchmark**\r\n\r\n- **Use Profiling Tools:** Identify performance bottlenecks using tools like cProfile (Python) and Visual Studio Profiler (C).\r\n- **Benchmark Different Configurations:** Test various settings to determine optimal parameter values for your system.\r\n\r\n---\r\n\r\n## Security Considerations\r\n\r\nWhile YOLO Overlay is a powerful tool, it's essential to consider security implications, especially when integrating with system-level components.\r\n\r\n### 1. **Secure DLL Interactions**\r\n\r\n- **Validate Inputs:** Ensure that all data passed to the DLL is validated and sanitized to prevent buffer overflows or injection attacks.\r\n- **Restrict DLL Sources:** Use only trusted DLLs to avoid introducing malicious code into the system.\r\n\r\n### 2. **Manage Permissions Carefully**\r\n\r\n- **Run with Least Privileges:** Execute the overlay script with the minimum required permissions to mitigate potential security risks.\r\n- **Avoid Elevated Privileges:** Refrain from running scripts as an administrator unless absolutely necessary.\r\n\r\n### 3. **Protect Sensitive Data**\r\n\r\n- **Mask Detection Data:** If detections include sensitive information, ensure that it is handled securely.\r\n- **Limit Data Exposure:** Restrict access to detection data and avoid logging sensitive details.\r\n\r\n### 4. **Regularly Update Dependencies**\r\n\r\n- **Patch Vulnerabilities:** Keep Python packages and system libraries updated to protect against known vulnerabilities.\r\n- **Monitor Security Advisories:** Stay informed about security updates related to the dependencies used by YOLO Overlay.\r\n\r\n### 5. **Implement Secure Communication**\r\n\r\n- **Integrity Checks:** Ensure that data transmitted between Python and the DLL maintains integrity and is not tampered with.\r\n- **Use Secure Channels:** If extending the communication mechanisms, consider using secure channels to prevent interception.\r\n\r\n### 6. **Audit and Review Code**\r\n\r\n- **Regular Audits:** Conduct code reviews to identify and rectify potential security flaws.\r\n- **Automated Scanning:** Utilize static and dynamic analysis tools to detect vulnerabilities in the codebase.\r\n\r\n---\r\n\r\n## License\r\n\r\nYOLO Overlay is licensed under the [MIT License](LICENSE), which permits reuse within proprietary software provided all copies include the original license terms and the copyright notice.\r\n\r\n---\r\n\r\n## Acknowledgements\r\n\r\nYOLO Overlay builds upon several outstanding projects and technologies:\r\n\r\n- **[YOLOv8 by Ultralytics](https://github.com/ultralytics/yolov8):** Provides the cutting-edge object detection capabilities.\r\n- **[MSS](https://github.com/BoboTiG/python-mss):** Facilitates efficient screen capturing.\r\n- **[Pillow](https://python-pillow.org/):** Handles image processing tasks.\r\n- **[Screeninfo](https://github.com/rr-/screeninfo):** Detects and manages multiple monitors.\r\n- **Windows API:** Powers the overlay window creation and rendering functionalities.\r\n- **[Visual Studio](https://visualstudio.microsoft.com/):** Used for developing and building the C DLL.\r\n\r\n---\r\n\r\n## Contact\r\n\r\nFor any questions, issues, or suggestions, please create an issue on our GitHub repository:\r\n\r\n- **GitHub Issues:** [YOLO Overlay GitHub Issues](https://github.com/wuhplaptop/yolo_overlay/issues)\r\n\r\n---\r\n\r\n## Appendix\r\n\r\n### Source Code Overview\r\n\r\nA deeper understanding of YOLO Overlay's source code can aid in customization and troubleshooting.\r\n\r\n#### 1. **`overlay-yolo.dll` (C Code)**\r\n\r\n- **Purpose:** Manages the overlay window and renders detection boxes.\r\n- **Key Functionalities:**\r\n - **Window Creation:** Utilizes Windows APIs to create a transparent, topmost window.\r\n - **Rendering:** Draws bounding boxes and labels using GDI functions based on detection data.\r\n - **Thread Management:** Runs the overlay in a separate thread to handle window messages and rendering.\r\n - **Synchronization:** Uses critical sections to ensure thread-safe access to detection data.\r\n\r\n- **Exported Functions:**\r\n - `StartOverlay()`: Initializes and starts the overlay window.\r\n - `StopOverlay()`: Terminates the overlay window and cleans up resources.\r\n - `UpdateDetections(DetectionBox*, int)`: Receives detection data from Python to render.\r\n - `SetTargetMonitorRect(int, int, int, int)`: Sets the target monitor's dimensions.\r\n - `SetMaxDetections(int)`: Adjusts the maximum number of detections.\r\n\r\n#### 2. **`detection.py`**\r\n\r\n- **Purpose:** Handles screen capturing, performs YOLO detections, and communicates with the C DLL.\r\n- **Key Components:**\r\n - **`DetectionBox` Structure:** Mirrors the C `DetectionBox` for data consistency.\r\n - **`process_detections` Function:**\r\n - Captures the screen region.\r\n - Processes the image using YOLOv8 to detect objects.\r\n - Formats detections into `DetectionBox` instances.\r\n - Sends detection data to the DLL via `UpdateDetections`.\r\n\r\n#### 3. **`overlay.py`**\r\n\r\n- **Purpose:** Coordinates the overlay lifecycle and integrates detections with the overlay.\r\n- **Key Components:**\r\n - **`YOLOOverlay` Class:**\r\n - **Initialization:** Loads the DLL, initializes the YOLO model, and selects the target monitor.\r\n - **Overlay Management:** Starts and stops the overlay, manages detection threads.\r\n - **DLL Interaction:** Configures overlay settings by invoking DLL functions.\r\n\r\n#### 4. **`utils.py`**\r\n\r\n- **Purpose:** Provides utility functions for internal operations.\r\n- **Key Functions:**\r\n - **`rgb_to_colorref(r, g, b)`**\r\n - Converts RGB color values to `COLORREF` format required by the C DLL.\r\n - **Example:**\r\n ```python\r\n colorref = rgb_to_colorref(255, 0, 0) # Red\r\n ```\r\n \r\n - **`encode_label(label_text)`**\r\n - Encodes label text into a fixed byte format suitable for the C DLL.\r\n - Ensures labels are null-terminated and padded to 50 bytes.\r\n - **Example:**\r\n ```python\r\n encoded_label = encode_label(\"Person\")\r\n ```\r\n \r\n - **`sanitize_bounding_box(x1, y1, x2, y2, monitor_width, monitor_height)`**\r\n - Adjusts bounding box coordinates to fit within monitor bounds.\r\n - Ensures that bounding boxes have valid dimensions (minimum 1 pixel).\r\n - **Example:**\r\n ```python\r\n sanitized = sanitize_bounding_box(100, 100, 200, 200, 1920, 1080)\r\n ```\r\n\r\n### Glossary\r\n\r\n- **YOLO (You Only Look Once):** A state-of-the-art, real-time object detection system.\r\n- **DLL (Dynamic-Link Library):** A library that contains code and data used by multiple programs simultaneously.\r\n- **`ctypes`:** A foreign function library for Python that provides C compatible data types and allows calling functions in DLLs or shared libraries.\r\n- **`COLORREF`:** A 32-bit value used in Windows programming to specify an RGB color.\r\n- **GDI (Graphics Device Interface):** A Windows API for representing graphical objects and transmitting them to output devices.\r\n- **`mss`:** A Python library for fast cross-platform screenshots.\r\n- **`screeninfo`:** A Python module to obtain information about connected monitors.\r\n\r\n---\r\n\r\n# Conclusion\r\n\r\nThe comprehensive documentation provided above aims to equip users and developers with all the necessary information to effectively utilize, customize, and contribute to the **YOLO Overlay** project. By understanding its features, architecture, and operational mechanisms, users can seamlessly integrate real-time object detection overlays into their Windows applications. Developers, on the other hand, are empowered to extend the project's functionalities, optimize performance, and ensure its continued robustness and relevance.\r\n\r\nFeel free to revisit and expand upon these sections as the project evolves, ensuring that the documentation remains up-to-date and continues to serve the needs of its user base.\r\n\r\n---\r\n\r\n\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python package to overlay YOLO detections on displays using a custom DLL.",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/wuhplaptop/yolo_overlay"
},
"split_keywords": [
"yolo",
"overlay",
"detection",
"computer-vision"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0f6532b72caf32ada8349387339208026bd429574f03034726064f81a023171b",
"md5": "493956842f54c13dcaab0b0b3c421356",
"sha256": "a599a5f1268ad0610d0afa4cb9d3812313e22483960067d4f586d98792a686d7"
},
"downloads": -1,
"filename": "yolo_overlay-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "493956842f54c13dcaab0b0b3c421356",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5017838,
"upload_time": "2024-12-26T03:32:36",
"upload_time_iso_8601": "2024-12-26T03:32:36.581252Z",
"url": "https://files.pythonhosted.org/packages/0f/65/32b72caf32ada8349387339208026bd429574f03034726064f81a023171b/yolo_overlay-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a0f0e156ec6db0b93c544bde3b07ed807be5c08416d18f13f23485cb75f4ea84",
"md5": "273fc531b18bf659f4b042ba642086fe",
"sha256": "33d76475671aee4254f7ecb455ece360cb7c3c9817ab32c404cf8750fdaf5848"
},
"downloads": -1,
"filename": "yolo-overlay-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "273fc531b18bf659f4b042ba642086fe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 5047292,
"upload_time": "2024-12-26T03:32:39",
"upload_time_iso_8601": "2024-12-26T03:32:39.574325Z",
"url": "https://files.pythonhosted.org/packages/a0/f0/e156ec6db0b93c544bde3b07ed807be5c08416d18f13f23485cb75f4ea84/yolo-overlay-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-26 03:32:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wuhplaptop",
"github_project": "yolo_overlay",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "Pillow",
"specs": [
[
"==",
"9.4.0"
]
]
},
{
"name": "mss",
"specs": [
[
"==",
"6.1.0"
]
]
},
{
"name": "ultralytics",
"specs": [
[
"==",
"8.3.54"
]
]
},
{
"name": "screeninfo",
"specs": [
[
"==",
"0.8.1"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"1.24.3"
]
]
}
],
"lcname": "yolo-overlay"
}
JSON
