PrivacyGuard

---

PrivacyGuard is a computer-vision pipeline that detects selected regions and applies configurable masking to images, recorded video, and live streams. It can run locally without sending frames to a cloud inference API.

Masking quality depends on detection quality. Missed or heavily occluded regions cannot be masked, blur is not encryption, and this software does not by itself establish legal compliance. Validate the selected model, labels, thresholds, input conditions, and deployment controls for your own use case.

Why PrivacyGuard?

Challenge	Solution
Deployment control	Process frames locally and choose what leaves the device
Performance	Benchmark your exact model, input, hardware, runtime, and masking settings; see Benchmarks
Privacy-oriented processing	Avoid a cloud inference dependency when the pipeline is configured to run locally
Robustness	Multi-model ensemble, adaptive blurring, regression-tested
Integration	3-line API, CLI tool, easy to embed in existing pipelines

Architecture

┌──────────────────────────────────────────────────────┐
│                    PrivacyGuard                       │
│                                                      │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────┐ │
│  │ VideoStream  │→│ ONNXDetector  │→│  Anonymizer  │ │
│  │  (threaded)  │  │ (YOLOv8/ONNX)│  │ (blur/pixel)│ │
│  └─────────────┘  └──────────────┘  └─────────────┘ │
│                                                      │
│  Sources:           Models:           Methods:       │
│  • Webcam           • YOLOv8-nano     • Gaussian     │
│  • Video file       • YOLOv8-small    • Pixelate     │
│  • RTSP stream      • Any ONNX        • Solid fill   │
└──────────────────────────────────────────────────────┘

Installation

PrivacyGuard is not currently published as a verified package on PyPI. Install the public repository from source:

git clone https://github.com/laythayache/privacyguard.git
cd privacyguard
pip install -e ".[dev]"

GPU acceleration (optional):

pip install -e ".[gpu]"

Requirements

• Python 3.9+
• OpenCV 4.8+
• ONNX Runtime 1.16+
• A compatible ONNX detection model (see Model Setup)

Quick Start

3-Line Live Webcam Masking

from privacyguard import PrivacyGuard

guard = PrivacyGuard("yolov8n-face.onnx")
guard.run(source=0)  # webcam — press 'q' to quit

Process a Single Image

from privacyguard import PrivacyGuard

guard = PrivacyGuard("yolov8n-face.onnx", method="pixelate")
detections = guard.process_image("photo.jpg", "photo_safe.jpg")
print(f"Anonymized {len(detections)} regions")

Process a Video File

guard = PrivacyGuard("yolov8n-face.onnx")
guard.process_video("input.mp4", "output_safe.mp4")

Fine-Grained Control

import cv2
from privacyguard import PrivacyGuard

guard = PrivacyGuard(
    model_path="yolov8n-face.onnx",
    method="gaussian",           # "gaussian" | "pixelate" | "solid"
    conf_threshold=0.5,          # detection confidence
    target_classes=[0],          # only anonymize faces (skip plates)
    padding=10,                  # expand blur region by 10px
)

cap = cv2.VideoCapture(0)
while True:
    ret, frame = cap.read()
    if not ret:
        break

    # Option A: one-shot
    result = guard.process_frame(frame)

    # Option B: inspect detections first
    detections = guard.detect(frame)
    for det in detections:
        print(f"{det.label}: {det.confidence:.0%} at ({det.x1},{det.y1})-({det.x2},{det.y2})")
    result = guard.anonymize(frame, detections)

    cv2.imshow("PrivacyGuard", result)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break
cap.release()

CLI Usage

# Live webcam
privacyguard model.onnx

# Video file with pixelation
privacyguard model.onnx -s input.mp4 -m pixelate -o output.mp4

# RTSP stream, no preview
privacyguard model.onnx -s "rtsp://192.168.1.10:554/stream" --no-display -o recording.mp4

Experimental Regional Processing

PrivacyGuard includes experimental modules for Arabic plate, text, document, and mixed-script workflows. They require deployment-specific models and validation; their presence in the repository is not evidence of accuracy on a particular country's plates, documents, scripts, or camera conditions.

Arabic License Plate Processing

Use a compatible custom model and optional format heuristics for plate regions.

from privacyguard.detectors.arabic_plate import ArabicPlateDetector, PlateConfig

config = PlateConfig(model_path="yolov8-arabic-plates.onnx")
detector = ArabicPlateDetector(config)
detections = detector.detect(frame)

The supplied module does not include a validated plate model or a published regional benchmark. Verify the model labels, format assumptions, and false negatives against representative footage.

Arabic Text Detection and Masking

Detect and blur Arabic text regions while preserving visual context (for bilingual documents).

from privacyguard.detectors.text import ArabicTextDetector, TextDetectorConfig

config = TextDetectorConfig(use_paddle_ocr=True)
detector = ArabicTextDetector(config)
result = detector.anonymize_text(frame)

Features:

• Arabic + Latin + Mixed script detection
• PaddleOCR integration (optional, falls back to contour-based detection)
• Per-script selective blurring
• Document-aware processing

Identity Document Masking

Selectively blur ID cards, passports, and driving licenses while preserving face visibility for recognition.

from privacyguard.detectors.document import DocumentDetector, DocumentConfig

config = DocumentConfig(blur_strategy="selective", preserve_face=True)
detector = DocumentDetector(config)
result = detector.anonymize_frame(frame)

Strategies:

• "selective": Blur text/numbers, keep face visible
• "full": Blur entire document

This is the beginning of the README. Read the rest at the original. Read the full README ↗