Passa all'italiano

CLI and web tool for automatic person anonymization in surveillance videos. Designed for fixed cameras with wide-angle lenses where people may appear small (30–100 px).

In addition to the default YOLO pipeline, Person Anonymizer supports SAM3 (Segment Anything Model 3 by Meta) as an optional detection/segmentation backend, providing pixel-precise person masks instead of bounding boxes.

Three detection modes:

Requirements for SAM3:

• Python 3.12+
• CUDA-capable GPU (≥8 GB VRAM recommended for sam3 mode)

Install SAM3 dependencies:

# Option A — dedicated requirements file
pip install -r requirements-sam3.txt

# Option B — package extra
pip install 'person-anonymizer[sam3]'

CLI usage:

# Hybrid mode: YOLO detection + SAM3 mask refinement
python -m person_anonymizer.cli video.mp4 --backend yolo+sam3

# Full SAM3 mode: detection and segmentation entirely by SAM3
python -m person_anonymizer.cli video.mp4 --backend sam3

Web interface: a "Detection backend" dropdown is available in the configuration panel to select the mode without using the CLI.

• Multi-scale YOLO v8 detection — inference at 4 scales (1.0x–2.5x) + 3x3 sliding window + Test-Time Augmentation
• ByteTrack tracking — persistent person IDs across consecutive frames
• Temporal smoothing EMA — stabilizes bounding boxes with moving average; ghost boxes handle temporary occlusions
• Auto-refinement — re-analyzes the rendered video and adds missed detections (up to 3 passes)
• Manual review — interactive OpenCV (CLI) or browser (web) interface to add/edit/delete polygons
• Two anonymization methods — pixelation (default) or Gaussian blur
• Adaptive intensity — obscuring strength proportional to person size
• Post-render verification — second YOLO pass on the anonymized video to flag residual detections
• Optional fish-eye correction — optical undistortion via camera calibration
• Complete output set — anonymized H.264 video, debug video, CSV report, reusable JSON annotations

• Python 3.11+ (3.12+ required for SAM3 backend)
• ffmpeg (for H.264 encoding and audio preservation)
• ~150 MB disk space for YOLO models (downloaded automatically on first run)
• CUDA GPU recommended; CPU also supported (CUDA required for SAM3 modes)

Install ffmpeg:

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows (Chocolatey)
choco install ffmpeg

git clone https://github.com/AndreaBonn/PRIVATE__video-anonimyzer.git
cd PRIVATE__video-anonimyzer
python -m venv person_anonymizer/.venv
source person_anonymizer/.venv/bin/activate
# Windows: person_anonymizer\.venv\Scripts\activate
pip install -r requirements.txt

# Standard — automatic detection + manual review (recommended)
python -m person_anonymizer.cli video.mp4

# Fully automatic (no manual review)
python -m person_anonymizer.cli video.mp4 -M auto

# Specify output and method
python -m person_anonymizer.cli video.mp4 -o output.mp4 -m blur

# Disable debug video and CSV report
python -m person_anonymizer.cli video.mp4 --no-debug --no-report

# Reload JSON annotations and reopen review
python -m person_anonymizer.cli video.mp4 --review annotations.json

# Normalize annotations (merge overlapping polygons)
python -m person_anonymizer.cli video.mp4 --review annotations.json --normalize

CLI options:

python -m person_anonymizer.web.app
# Open http://127.0.0.1:5000

The web GUI allows you to:

• Upload videos via drag & drop
• Configure all pipeline parameters
• Monitor progress in real time (SSE)
• Review annotations frame by frame in the browser
• Download all outputs (video, debug, report, JSON)

Environment variables:

1. Detection — YOLO v8 multi-scale + sliding window + TTA, with optional motion detection
2. Auto-refinement — Re-render + second YOLO pass, up to 3 iterations
3. Manual review — Interactive interface (OpenCV or web) for corrections
4. Rendering — Apply anonymization to the original video (FFV1 lossless intermediate)
5. Post-processing — H.264 encoding with ffmpeg, audio preservation, report saving

.mp4, .m4v, .mov, .avi, .mkv, .webm

All 40+ parameters are configurable via PipelineConfig or the web GUI. Key parameters:

person_anonymizer/
├── config.py            # PipelineConfig with validation
├── models.py            # Dataclasses (PipelineContext, OutputPaths, etc.)
├── pipeline.py          # Pipeline orchestrator
├── pipeline_stages.py   # Stages: detection, refinement, review
├── output.py            # Output saving and JSON loading
├── cli.py               # CLI entry point
├── detection.py         # YOLO multi-scale + NMS
├── tracking.py          # ByteTrack + TemporalSmoother
├── anonymization.py     # Obscuring + polygon geometry
├── preprocessing.py     # CLAHE, fisheye, motion detection
├── postprocessing.py    # H.264 encoding, post-render check
├── rendering.py         # Video rendering + review stats
├── manual_reviewer.py   # OpenCV manual review GUI
├── camera_calibration.py# Camera calibration utility
├── sam3_backend.py      # SAM3 segmentation backend
├── backend_factory.py   # Backend selection and instantiation
└── web/                 # Flask web interface
    ├── app.py           # Flask routes + SSE + security
    ├── pipeline_runner.py
    ├── sse_manager.py
    └── review_state.py
tests/                   # 293 tests (pytest)
reports/                 # Audit reports
requirements-sam3.txt    # SAM3 optional dependencies

source person_anonymizer/.venv/bin/activate
pytest tests/ -v
ruff check person_anonymizer/

See SECURITY.md for full details on implemented protections.

• Ultralytics YOLOv8 — Object detection
• Meta SAM3 — Pixel-precise segmentation (optional)
• ByteTrack — Multi-object tracking
• OpenCV — Video processing
• Flask — Web interface
• ffmpeg — Video encoding

This project is licensed under the Apache License 2.0.

Note: This project depends on Ultralytics YOLOv8 which is licensed under AGPL-3.0. If you use this software as a network service, the AGPL requires that the complete source code be made available. Since this project is already open source, there is no practical conflict. For commercial/proprietary use of YOLO, see Ultralytics Licensing.

Switch to English

Tool CLI e web per l'anonimizzazione automatica di persone in video di sorveglianza. Progettato per telecamere fisse con lenti grandangolari, dove le persone possono apparire di piccole dimensioni (30–100 px).

Oltre alla pipeline YOLO predefinita, Person Anonymizer supporta SAM3 (Segment Anything Model 3 di Meta) come backend opzionale di detection e segmentazione, che produce maschere pixel-precise delle persone al posto dei bounding box.

Tre modalità di rilevamento:

Requisiti per SAM3:

• Python 3.12+
• GPU con supporto CUDA (≥8 GB VRAM consigliati per la modalità sam3)

Installazione dipendenze SAM3:

# Opzione A — file requirements dedicato
pip install -r requirements-sam3.txt

# Opzione B — extra del package
pip install 'person-anonymizer[sam3]'

Utilizzo CLI:

# Modalità ibrida: YOLO rileva, SAM3 raffina le maschere
python -m person_anonymizer.cli video.mp4 --backend yolo+sam3

# Modalità SAM3 completo: detection e segmentazione interamente tramite SAM3
python -m person_anonymizer.cli video.mp4 --backend sam3

Interfaccia web: nel pannello di configurazione è disponibile un menu a tendina "Backend rilevamento" per selezionare la modalità senza usare la CLI.

• Rilevamento YOLO v8 multi-scala — inferenza a 4 scale (1.0x–2.5x) + sliding window 3x3 + Test-Time Augmentation
• Tracking ByteTrack — ID persona persistenti tra frame consecutivi
• Temporal smoothing EMA — stabilizza i bounding box con media mobile; ghost box per gestire occlusioni temporanee
• Auto-refinement — ri-analizza il video renderizzato e aggiunge detection mancanti (fino a 3 iterazioni)
• Revisione manuale — interfaccia interattiva OpenCV (CLI) o browser (web) per aggiungere/modificare/eliminare poligoni
• Due metodi di oscuramento — pixelation (default) o blur gaussiano
• Intensità adattiva — forza dell'oscuramento proporzionale alla dimensione della persona
• Verifica post-rendering — secondo passaggio YOLO sul video anonimizzato per segnalare detection residue
• Correzione fish-eye opzionale — undistortion ottica tramite calibrazione camera
• Output completo — video H.264 anonimizzato, video debug, report CSV, annotazioni JSON riutilizzabili

• Python 3.11+ (3.12+ obbligatorio per il backend SAM3)
• ffmpeg (per encoding H.264 e preservazione audio)
• ~150 MB di spazio disco per i modelli YOLO (scaricati automaticamente al primo avvio)
• GPU CUDA raccomandata; funziona anche su CPU (CUDA obbligatoria per le modalità SAM3)

Installare ffmpeg:

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows (Chocolatey)
choco install ffmpeg

git clone https://github.com/AndreaBonn/PRIVATE__video-anonimyzer.git
cd PRIVATE__video-anonimyzer
python -m venv person_anonymizer/.venv
source person_anonymizer/.venv/bin/activate
# Windows: person_anonymizer\.venv\Scripts\activate
pip install -r requirements.txt

# Standard — detection automatica + revisione manuale (consigliato)
python -m person_anonymizer.cli video.mp4

# Completamente automatico (senza revisione)
python -m person_anonymizer.cli video.mp4 -M auto

# Specificare output e metodo
python -m person_anonymizer.cli video.mp4 -o output.mp4 -m blur

# Disabilitare video debug e report CSV
python -m person_anonymizer.cli video.mp4 --no-debug --no-report

# Ricaricare annotazioni JSON e riaprire la revisione
python -m person_anonymizer.cli video.mp4 --review annotazioni.json

# Normalizzare annotazioni (merge poligoni sovrapposti)
python -m person_anonymizer.cli video.mp4 --review annotazioni.json --normalize

Opzioni CLI:

python -m person_anonymizer.web.app
# Apri http://127.0.0.1:5000 nel browser

La web GUI permette di:

• Caricare video tramite drag & drop
• Configurare tutti i parametri della pipeline
• Monitorare il progresso in tempo reale (SSE)
• Revisionare le annotazioni frame per frame nel browser
• Scaricare tutti gli output (video, debug, report, JSON)

Variabili d'ambiente:

1. Detection — YOLO v8 multi-scala + sliding window + TTA, con motion detection opzionale
2. Auto-refinement — Re-rendering + secondo passaggio YOLO, fino a 3 iterazioni
3. Revisione manuale — Interfaccia interattiva (OpenCV o web) per correzioni
4. Rendering — Applicazione oscuramento al video originale (intermedio FFV1 lossless)
5. Post-processing — Encoding H.264 con ffmpeg, preservazione audio, salvataggio report

.mp4, .m4v, .mov, .avi, .mkv, .webm

Tutti i 40+ parametri sono configurabili tramite PipelineConfig o la web GUI. I principali:

person_anonymizer/
├── config.py            # PipelineConfig con validazione
├── models.py            # Dataclass (PipelineContext, OutputPaths, ecc.)
├── pipeline.py          # Orchestratore pipeline
├── pipeline_stages.py   # Fasi: detection, refinement, review
├── output.py            # Salvataggio output e caricamento JSON
├── cli.py               # CLI entry point
├── detection.py         # YOLO multi-scala + NMS
├── tracking.py          # ByteTrack + TemporalSmoother
├── anonymization.py     # Oscuramento + geometria poligoni
├── preprocessing.py     # CLAHE, fisheye, motion detection
├── postprocessing.py    # Encoding H.264, verifica post-render
├── rendering.py         # Rendering video + statistiche review
├── manual_reviewer.py   # GUI OpenCV per revisione manuale
├── camera_calibration.py# Utility calibrazione camera
├── sam3_backend.py      # Backend segmentazione SAM3
├── backend_factory.py   # Selezione e istanziazione backend
└── web/                 # Interfaccia web Flask
    ├── app.py           # Flask routes + SSE + security
    ├── pipeline_runner.py
    ├── sse_manager.py
    └── review_state.py
tests/                   # 293 test (pytest)
reports/                 # Report di audit
requirements-sam3.txt    # Dipendenze opzionali SAM3

source person_anonymizer/.venv/bin/activate
pytest tests/ -v
ruff check person_anonymizer/

Vedi SECURITY.md per i dettagli completi sulle protezioni implementate.

• Ultralytics YOLOv8 — Object detection
• Meta SAM3 — Segmentazione pixel-precisa (opzionale)
• ByteTrack — Multi-object tracking
• OpenCV — Video processing
• Flask — Interfaccia web
• ffmpeg — Video encoding

Questo progetto è rilasciato sotto Apache License 2.0.

Nota: Questo progetto dipende da Ultralytics YOLOv8, rilasciato sotto AGPL-3.0. Se si utilizza questo software come servizio di rete, l'AGPL richiede che il codice sorgente completo sia reso disponibile. Essendo questo progetto già open source, non c'è conflitto pratico. Per uso commerciale/proprietario di YOLO, vedere Ultralytics Licensing.