AA Video Processing System 1.2.0
A modern C++23 video processing system with gRPC-based client-server architecture for real-time object detection using YOLO neural networks (YOLOv7, YOLOv10, YOLOv11, YOLOX) with advanced polygon-based detection zones, comprehensive memory safety, and segmentation fault protection
Loading...
Searching...
No Matches
YoloX OpenCV Processing System

YoloX OpenCV Processing System

A C++23 video processing system featuring gRPC-based client-server architecture for real-time object detection using YOLO neural networks (YOLOv11, YOLOX). The system provides advanced polygon-based detection zones with priority-based filtering, comprehensive memory safety, and enterprise-grade deployment capabilities.

Complete Documentation: https://stolyarchuk.github.io/aa-video/

Key Features

Core Technology Stack

  • Modern C++23 with Google C++ Style Guide and rigorous memory safety
  • gRPC & Protocol Buffers for high-performance client-server communication
  • OpenCV 4.12.0 with DNN module for computer vision and neural network inference
  • YOLO Object Detection with support for YOLOv11, and YOLOX models
  • GitHub Actions for complete CI/CD and automated testing

Advanced Detection Capabilities

  • Polygon-based Detection Zones with inclusion/exclusion areas and priority-based adjudication
  • Non-Maximum Suppression (NMS) for duplicate detection filtering with configurable IoU thresholds
  • Letterboxing Preprocessing maintains aspect ratios without distortion artifacts
  • Multi-YOLO Model Support YOLOv10/v11 (.onnx), and YOLOX (.onnx) formats
  • Real-time Performance with ~100-200ms inference times on CPU

Production-Grade Architecture

  • Memory Safety Guarantees with comprehensive bounds checking and RAII patterns
  • Signal-based Graceful Shutdown with proper resource cleanup and state management
  • Thread-safe Logging System using AA_LOG_* macros with configurable levels
  • Comprehensive Test Suite with 100% pass rate across 50+ unit tests
  • Complete API Documentation with Doxygen docstrings for all classes and methods

Recent Major Updates

YOLO Integration & Performance Optimizations

  • Complete YOLO Pipeline with COCO dataset support and optimized preprocessing
  • Multi-Model Support for YOLOv7, YOLOv10, YOLOv11, and YOLOX architectures
  • Dynamic Tensor Shape Support for flexible model input/output dimensions
  • Verified Polygon Filtering System with 100% accuracy compared to OpenCV's pointPolygonTest
  • Performance-Optimized Geometry Algorithms matching OpenCV performance benchmarks

Security & Stability Improvements

  • Fixed Critical Segmentation Faults in Frame::ToMat() and ParseNetworkOutput() methods
  • Enhanced Memory Safety with comprehensive bounds checking and null pointer validation
  • Exception Safety Guarantees with proper error recovery and resource cleanup
  • Buffer Overflow Protection in all network operations and data processing
  • Comprehensive Test Coverage with 100% pass rate across all polygon filtering scenarios
  • Complete Doxygen Documentation with docstrings for all classes, methods, and public interfaces

Project Structure

For detailed information about the project architecture, file organization, and component relationships, see the Complete Documentation.

aa_video_processing/
├── CMakeLists.txt # Main CMake configuration with C++23 support
├── client/ # Client application with gRPC communication
├── server/ # Server application with neural network inference
├── shared/ # Shared components and Protocol Buffers
├── tests/ # Comprehensive unit test suite (100% pass rate)
├── models/ # Neural network models (YOLOv11, YOLOX)
├── input/ # Sample input images for testing
└── build/ # Build directory (generated by CMake)

Quick Start

Prerequisites

  • CMake 3.20 or higher
  • C++23 compatible compiler (GCC 11+, Clang 12+, MSVC 2022+)
  • Protocol Buffers compiler and libraries
  • gRPC C++ libraries and plugins
  • OpenCV 4.8.1+ with DNN support
  • Google Test (for running tests)

For detailed installation instructions, see the Installation Guide.

Building the Project

# Configure Debug build
cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
# Build all components
cmake --build build

For complete build instructions and advanced configuration options, see the Build Guide.

Usage

Starting the Server

Run the detector server with a YOLO model:

# Using YOLOX ONNX model for object detection
./build/server/detector_server \
--model=./models/yolox_s.onnx \
--verbose=true

Running the Client

Connect to the server and process frames:

# Connect to server and process input image
./build/client/detector_client \
--input=input/000000039769.jpg \
--verbose=true

For complete usage instructions and command-line options, see the Usage Guide.

Testing

The project includes comprehensive unit tests with 100% pass rate:

# Run all tests
cmake --build build --target test
# Run tests with detailed output
ctest --test-dir build --output-on-failure

For detailed testing documentation and coverage reports, see the Testing Guide.

Polygon-Based Detection System

The server supports sophisticated polygon-based detection zones with comprehensive safety measures:

Polygon Features

  • Inclusion Zones: Detect only specified object classes within these areas
  • Exclusion Zones: Block all detections within these areas regardless of class
  • Priority System: Higher priority polygons override lower priority ones in overlapping regions
  • Class Filtering: Per-polygon target class lists for fine-grained control
  • Coordinate Scaling: Automatic scaling between input and model coordinate systems

For complete documentation on polygon configuration and advanced features, see the Polygon Detection Guide.

Security & Safety Features

The system implements comprehensive safety measures:

  • Memory Safety Guarantees with bounds checking and RAII patterns
  • Input Validation for all data processing
  • Exception Safety with proper error recovery
  • Graceful Degradation for robust operation

For detailed security documentation and safety protocols, see the Security Guide.

Testing & Quality Assurance

Performance & Deployment

System Requirements

Minimum requirements:

  • 4GB RAM (8GB recommended)
  • 2 CPU cores (4+ cores recommended)
  • OpenCV 4.8.1+ with DNN support

Performance characteristics:

  • Inference Speed: ~100-200ms per frame (CPU)
  • Memory Usage: ~150-300MB depending on model size
  • Throughput: Up to 10-15 FPS on modern multi-core systems

For complete deployment guides, performance optimization, and troubleshooting, see the Deployment Documentation.

Documentation & API Reference

For complete technical documentation, including:

  • API Reference: Comprehensive Doxygen documentation
  • Architecture Details: System design and component relationships
  • Protocol Buffer Schema: gRPC service definitions and message types
  • Advanced Configuration: Polygon zones, detection parameters, and deployment options

Visit the official documentation at: https://stolyarchuk.github.io/aa-video/

Development

Code Style Guidelines

The project follows Google C++ Style Guide with modern C++23 features. For detailed development guidelines, see the Development Guide.

VS Code Integration

This project includes VS Code configuration with recommended extensions and tasks for seamless development.

Contributing

We welcome contributions! Please see our Contributing Guide for:

  • Development workflow and standards
  • Code style guidelines
  • Testing requirements
  • Pull request process

Quick Development Setup

Use the provided devcontainer with VS Code for consistent development:

# Clone and open in VS Code
git clone https://github.com/stolyarchuk/aa-video.git
code aa-video

License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Links