A high-performance, multi-threaded C++ application that performs real-time face detection using your webcam and OpenCV's Haar cascade classifier. Features a modern Qt6 GUI interface with parallel processing architecture for optimal performance.

• Parallel Processing: Multi-threaded architecture utilizing 4 CPU cores simultaneously
• Real-Time Performance: 10 FPS processing with configurable frame rates
• Thread Pool Design: Efficient worker thread pool for optimal resource utilization
• Memory Management: Bounded frame queue with overflow protection

• Input Validation: Comprehensive validation of all input parameters
• Exception Handling: Robust error handling with graceful degradation
• Thread Safety: Full mutex protection and atomic operations
• Resource Management: Automatic cleanup and memory leak prevention

• Modern Qt6 GUI: Professional interface with real-time camera feed
• Live Status Updates: Real-time face count and processing status
• Frame Counter: Visual frame numbering for processing verification
• Responsive Controls: Start/Stop camera with immediate feedback

• OpenCV Haar Cascade: Industry-standard face detection algorithm
• Real-Time Detection: Live detection with green bounding boxes
• Multi-Face Support: Detects and tracks multiple faces simultaneously
• Performance Optimized: Efficient processing for real-time applications

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MainWindow    │    │ FrameProcessor   │    │   FaceDetector  │
│   (Qt6 GUI)     │◄──►│  (Thread Pool)   │◄──►│  (OpenCV AI)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │ CameraManager    │
                       │  (Camera I/O)    │
                       └──────────────────┘

• 1 Capture Thread: Continuously captures frames from camera
• 4 Worker Threads: Process frames in parallel for face detection
• 1 UI Thread: Handles GUI updates and user interactions
• Total: 6 threads working simultaneously

Camera → Capture Thread → Frame Queue → Worker Threads → Results → UI Display
   ↓           ↓            ↓            ↓           ↓         ↓
 10 FPS    Non-blocking  Thread-safe  Parallel   Thread-safe  Real-time

• Operating System: Linux (Ubuntu 20.04+ recommended)
• Processor: Multi-core CPU (4+ cores for optimal performance)
• Memory: 4GB RAM minimum, 8GB recommended
• Storage: 100MB free space
• Camera: USB webcam or built-in camera

• C++ Compiler: GCC 7+ or Clang 5+ (C++17 support required)
• Qt6: Core and Widgets modules
• OpenCV: Version 4.x with development libraries
• CMake: Version 3.16 or higher
• pthread: POSIX threading library

# Clone the repository
git clone https://github.com/Baraa-Rj/Face-Detector.git
cd Face-Detector

# Make build script executable
chmod +x build.sh

# Build the application
./build.sh

# Update package list
sudo apt-get update

# Install Qt6 and OpenCV development libraries
sudo apt-get install -y \
    qt6-base-dev \
    qt6-tools-dev \
    libopencv-dev \
    pkg-config \
    build-essential \
    cmake

# Verify installations
pkg-config --modversion opencv4
qmake6 --version
cmake --version

# Create build directory
mkdir build && cd build

# Configure with CMake
cmake ..

# Build the application
make -j$(nproc)

# Verify build
ls -la face_detection

# Navigate to project directory
cd Face-Detector

# Run the application
./build/face_detection

1. Launch: Run the executable to open the main window
2. Start Camera: Click "Start Camera" to begin face detection
3. Monitor Status: Watch real-time face count and processing status
4. Stop Camera: Click "Stop Camera" to halt processing
5. Exit: Close the window to quit the application

The application provides real-time feedback:

• Frame Counter: Shows current processing frame number
• Face Count: Displays number of faces detected
• Status Bar: Shows camera and processing status
• Visual Feedback: Green rectangles around detected faces

// In Headers/FrameProcessor.h
static constexpr int NUM_PROCESSING_THREADS = 4;  // Adjust based on CPU cores
static constexpr int FRAME_INTERVAL_MS = 100;     // Adjust for desired FPS

// In Headers/FrameProcessor.h
static constexpr size_t MAX_QUEUE_SIZE = 10;  // Adjust queue size limit

// In src/CameraManager.cpp
videoCapture.set(cv::CAP_PROP_FRAME_WIDTH, 640);   // Frame width
videoCapture.set(cv::CAP_PROP_FRAME_HEIGHT, 480);  // Frame height
videoCapture.set(cv::CAP_PROP_FPS, 30);            // Camera FPS

Face-Detector/
├── Headers/                           # Header files (.h)
│   ├── MainWindow.h                   # Main GUI window interface
│   ├── FaceDetector.h                 # Face detection interface
│   ├── CameraManager.h                # Camera operations interface
│   └── FrameProcessor.h               # Multi-threaded processing
├── src/                               # Source files (.cpp)
│   ├── main.cpp                       # Application entry point
│   ├── MainWindow.cpp                 # GUI implementation
│   ├── FaceDetector.cpp               # Face detection logic
│   ├── CameraManager.cpp              # Camera management
│   └── FrameProcessor.cpp             # Thread pool implementation
├── CMakeLists.txt                     # Build configuration
├── build.sh                           # Automated build script
├── haarcascade_frontalface_alt.xml    # Face detection classifier
└── README.md                          # This documentation

• Purpose: Central coordinator for multi-threaded processing
• Threads: Manages 1 capture + 4 worker threads
• Synchronization: Uses mutexes and condition variables
• Queue Management: Thread-safe frame queue with overflow protection

• Algorithm: OpenCV Haar Cascade classifier
• Input: Grayscale frames (BGR to grayscale conversion)
• Output: Vector of face rectangles (x, y, width, height)
• Performance: Optimized for real-time processing

• Interface: OpenCV VideoCapture wrapper
• Properties: Configurable resolution and frame rate
• Error Handling: Comprehensive error checking and recovery
• Resource Management: Automatic camera cleanup

• Framework: Qt6 with modern styling
• Threading: Safe cross-thread communication
• Display: Real-time video feed with overlay information
• Controls: User interface for camera operations

Capture Thread (Producer) → Frame Queue → Worker Threads (Consumers)

• Mutexes: Protect shared resources (queue, results)
• Condition Variables: Coordinate between threads
• Atomic Operations: Simple flags and counters
• RAII Locks: Automatic resource management

1. Creation: Threads start immediately upon creation
2. Execution: Continuous processing loops with stop checks
3. Shutdown: Graceful termination with proper cleanup
4. Cleanup: Automatic resource deallocation

• Capture: 10 FPS (configurable via FRAME_INTERVAL_MS)
• Processing: Up to 4 frames simultaneously
• Latency: Minimal due to parallel processing
• Throughput: Scales with CPU core count

• Frame Queue: Bounded to prevent memory overflow
• Image Storage: Efficient OpenCV Mat operations
• Thread Overhead: Minimal per-thread memory usage
• Cleanup: Automatic memory deallocation

# Check camera permissions
ls -la /dev/video*

# Verify camera is not in use by other applications
lsof /dev/video0

# Test camera with simple command
ffmpeg -f v4l2 -i /dev/video0 -frames:v 1 test.jpg

# Verify dependencies
pkg-config --modversion opencv4
qmake6 --version

# Clean build directory
rm -rf build/
./build.sh

# Check OpenCV installation
ldd ./build/face_detection | grep opencv

# Verify classifier file exists
ls -la haarcascade_frontalface_alt.xml

• Reduce thread count if CPU is overloaded
• Increase frame interval for lower FPS
• Check camera capabilities for higher resolution

• Monitor thread activity with system tools
• Adjust queue size to balance memory vs. performance
• Profile with tools like htop or perf

# Debug build with symbols
mkdir build-debug && cd build-debug
cmake -DCMAKE_BUILD_TYPE=Debug ..
make -j$(nproc)

# Release build with optimizations
mkdir build-release && cd build-release
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

• C++17 Standard: Modern C++ features throughout
• RAII Principles: Automatic resource management
• Exception Safety: Comprehensive error handling
• Thread Safety: All shared resources protected

# Run basic functionality test
./build/face_detection

# Monitor system resources
htop
iotop

• CPU Affinity: Pin threads to specific cores for better performance
• Memory Alignment: Ensure frame data is properly aligned
• Cache Optimization: Minimize memory access patterns
• Thread Pooling: Adjust worker count based on workload

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

• Follow existing code style
• Add comprehensive error handling
• Include performance considerations
• Document new features

This project is licensed under the MIT License - see the LICENSE file for details.

• OpenCV Community for the excellent computer vision library
• Qt Development Team for the modern GUI framework
• Haar Cascade Contributors for the face detection algorithm
• C++ Standards Committee for modern C++ features

• Issues: Report bugs via GitHub Issues
• Discussions: Use GitHub Discussions for questions
• Documentation: Check this README and code comments
• Community: Engage with other developers

When reporting issues, please include:

• System Information: OS, compiler version, dependencies
• Error Messages: Complete error output and logs
• Reproduction Steps: Clear steps to reproduce the issue
• Expected vs. Actual Behavior: What you expected vs. what happened

Built with ❤️ using C++, Qt6, and OpenCV

For real-time face detection that scales with your hardware