Person Detection App

A real-time person detection application using YOLO (You Only Look Once) with OpenCV and Supervision for video processing and annotation.

Features

• Real-time person detection using YOLO models (YOLOv8)
• Multiple input sources: Webcam, video files, or streaming URLs
• Interactive GUI with live video feed and statistics
• Command-line interface for batch processing
• Configurable confidence thresholds
• Frame saving and video output capabilities
• Detection statistics and performance metrics

Installation

⚠️ IMPORTANT: Always use virtual environments - this is a fundamental best practice in Python development.

1. Create and activate a virtual environment:

# Using conda (recommended)
conda create -n person-detection python=3.9
conda activate person-detection

# OR using venv
python -m venv person-detection-env
source person-detection-env/bin/activate  # Linux/Mac
# person-detection-env\Scripts\activate  # Windows

2. Install the required dependencies:

pip install -r requirements.txt

Why virtual environments are essential:

• Prevents conflicts with system Python packages
• Ensures reproducible installations across different machines
• Isolates project dependencies from other projects
• Standard practice in professional Python development

Usage

GUI Application

Run the graphical interface:

python gui_app.py

GUI Features:

• Load different YOLO models (n, s, m, l, x variants)
• Adjust confidence threshold with slider
• Start webcam for live detection
• Load and process video files
• Save current frames
• View real-time statistics

Command Line Interface

Run person detection from command line:

# Use webcam (default)
python person_detector.py

# Process a video file
python person_detector.py --source path/to/video.mp4

# Save output video
python person_detector.py --source input.mp4 --output output.mp4

# Use different model and confidence
python person_detector.py --model yolov8s.pt --confidence 0.7

# Process without display (headless)
python person_detector.py --source video.mp4 --no-display

Command Line Options:

• --source, -s: Video source (file path, webcam index, or URL)
• --output, -o: Output video path (optional)
• --model, -m: YOLO model path (default: yolov8n.pt)
• --confidence, -c: Confidence threshold (default: 0.5)
• --no-display: Don't display video in real-time

Models

The app supports different YOLOv8 models:

• yolov8n.pt: Nano - Fastest, least accurate
• yolov8s.pt: Small - Good balance
• yolov8m.pt: Medium - Better accuracy
• yolov8l.pt: Large - High accuracy
• yolov8x.pt: Extra Large - Best accuracy, slowest

Models will be automatically downloaded on first use.

Controls

GUI Controls

• Load Model: Initialize YOLO with selected model
• Start Webcam: Begin live detection from webcam
• Load Video: Select and process a video file
• Save Frame: Export current frame as image

Keyboard Controls (CLI)

• 'q': Quit application
• 's': Save current frame

Technical Details

Dependencies

• ultralytics: YOLOv8 implementation
• opencv-python: Video processing and display
• supervision: Detection annotation and utilities
• numpy: Numerical operations
• Pillow: Image processing (GUI only)

Detection Process

1. Load YOLOv8 model (COCO pre-trained)
2. Process video frame by frame
3. Filter detections for person class (class_id = 0)
4. Apply confidence threshold
5. Annotate frames with bounding boxes and labels
6. Display results and update statistics

Performance Tips

• Use smaller models (yolov8n) for real-time applications
• Increase confidence threshold to reduce false positives
• Process at lower resolution for better performance
• Use GPU acceleration if available (CUDA)

File Structure

person-detection-app/
├── person_detector.py    # Core detection class and CLI
├── gui_app.py           # GUI application
├── requirements.txt     # Python dependencies
└── README.md           # This file

Example Output

The application will display:

• Bounding boxes around detected persons
• Confidence scores for each detection
• Frame count and detection statistics
• Real-time processing information

Troubleshooting

Common Issues:

1. Webcam not working: Check camera permissions and try different indices (0, 1, 2)
2. Model download fails: Ensure internet connection for first-time model download
3. Poor performance: Try smaller model (yolov8n) or lower resolution
4. No detections: Lower confidence threshold or check lighting conditions

System Requirements:

• Python 3.8+
• Webcam (for live detection)
• 4GB+ RAM recommended
• GPU optional but recommended for better performance

License

This project uses open-source libraries and pre-trained models. Please check individual library licenses for commercial use.