🎭 Real-Time Face Blur

Detects faces in a live webcam feed using OpenCV's ResNet-SSD DNN model and blurs them in real time.

---

Project Structure

├── config.yaml          # All configuration (edit this, not the code)
├── config.py            # Pydantic config loader & validator
├── face_detector.py     # FaceDetector class — detection only
├── blur.py              # FaceBlurrer class — blurring only
├── camera.py            # FrameGrabber — threaded capture
├── main.py              # Entry point + CLI
├── requirements.txt
└── weights/             # Put your model files here
    ├── deploy.prototxt.txt
    └── res10_300x300_ssd_iter_140000.caffemodel

---

Setup

# 1. Clone / download the project
git clone https://github.com/YOUR_USERNAME/face-blur-realtime.git
cd face-blur-realtime

# 2. Create a virtual environment
python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Place model weights
mkdir weights
# Copy your deploy.prototxt.txt and .caffemodel into weights/

---

Running

# Default (uses config.yaml)
python main.py

# Override camera index
python main.py --camera 1

# Override blur style
python main.py --blur pixelate

# Override confidence threshold
python main.py --confidence 0.6

# Use a custom config file
python main.py --config my_config.yaml

Press q or Esc to quit.

---

Configuration (config.yaml)

Section	Key	Default	Description
model	prototxt_path	weights/deploy.prototxt.txt	Path to Caffe prototxt
model	model_path	weights/res10_300x300_ssd_iter_140000.caffemodel	Path to model weights
model	confidence_threshold	0.5	Min confidence to show a detection
model	backend	default	default / cuda / opencl
model	target	cpu	cpu / cuda / opencl
camera	index	0	Webcam index or RTSP URL
blur	method	gaussian	gaussian / pixelate / median
blur	kernel_size	51	Blur strength (must be odd)
performance	skip_frames	0	Detect every N+1 frames (0 = every frame)
performance	detection_resize_width	0	Shrink frame before inference (0 = off)

---

Performance Tips

• GPU acceleration — set backend: cuda and target: cuda in config.yaml (requires OpenCV built with CUDA)
• Faster CPU inference — set detection_resize_width: 480 to shrink the frame before detection
• Reduce CPU load — set skip_frames: 1 to detect every other frame (blur still applies every frame using the last known boxes)
• The threaded FrameGrabber (camera.py) decouples camera I/O from inference, eliminating the main bottleneck on most machines

---

Architecture & SOLID Principles

Principle	How it's applied
Single Responsibility	Each file has one job: capture / detect / blur / configure
Open/Closed	New blur methods or DNN backends can be added without changing existing classes
Liskov Substitution	Detection is a frozen dataclass — no subclass can violate its contract
Interface Segregation	Callers only depend on detect() or apply() — internals are private
Dependency Inversion	All classes receive config objects (abstractions), not file paths or magic constants

---

License

MIT