viso

Toolkit per la ricerca e la performance artistica di makeup adversarial contro sistemi di riconoscimento facciale.

Pensato come strumento di supporto per truccatori e performer: permette di visualizzare in tempo reale quali feature del volto vengono usate dagli algoritmi di detection, applicare pattern di trucco generati tramite Gaussian mesh rendering, e valutare l'efficacia dell'evasione live.

Quick start

Requisiti: Python >= 3.12, webcam, uv. GPU opzionale (CUDA) per l'ottimizzazione; detection e visualizzazione funzionano su CPU.

git clone <repo-url>
cd viso
uv sync

I modelli (YuNet, DNN SSD, MediaPipe, RetinaFace) vengono scaricati automaticamente al primo utilizzo.

Modalita live

uv run python -m viso
uv run python -m viso --camera 1   # webcam secondaria

Apre la webcam con detection, landmark e feedback di evasione. Comandi da tastiera:

Tasto	Azione
d	Cambia detector (YuNet -> DNN -> RetinaFace)
l	Cambia landmarker (YuNet -> MediaPipe)
k	Toggle overlay keypoint ArcFace + anchor box
s	Toggle saliency map detection (heatmap gradienti RetinaFace)
e	Toggle saliency map embedding (heatmap gradienti identita, richiede galleria)
m	Toggle mesh 3D del volto
g	Prossima Gaussian mesh (cicla tra quelle disponibili)
0	Spegni Gaussian mesh
+	Aumenta opacita Gaussian mesh
-	Diminuisci opacita Gaussian mesh
c	Cattura volti come riferimento (salvati in references/)
r	Ricarica galleria riferimenti da references/
q / ESC	Esci

Gaussian mesh

Il rendering avviene tramite ~300 Gaussiane 2D posizionate sui vertici della mesh facciale MediaPipe. Ogni Gaussiana ha colore, opacita e dimensione propri; la dimensione si adatta automaticamente alla densita locale della mesh (piu piccole sul naso, piu grandi sulle guance). Il rendering avviene direttamente nello spazio del frame, senza warping.

La directory di default e meshes/; se presente, le mesh vengono caricate automaticamente all'avvio. Per usare una directory diversa:

uv run python -m viso --mesh-dir altra_dir/

La directory meshes/ contiene 73 pattern pre-ottimizzati, organizzati per stile e densita:

Directory	Stile	Esempi colori
fluo/	Neon, alta visibilita	arancio-ciano, verde-magenta, giallo-viola
naturale/	Toni naturali	bordeaux-bronzo, terracotta-oro
teatrale/	Drammatico, teatrale	nero-bianco, rosso-nero

Ogni stile ha varianti di densita: denso (copertura piena), medio, rado (pattern sparso).

Usa g per ciclare tra le mesh disponibili, +/- per regolare l'opacita, 0 per spegnere.

Galleria riferimenti e riconoscimento

I riferimenti salvati in references/ vengono caricati automaticamente all'avvio. Bounding box verdi = volto riconosciuto, rosse = evasione riuscita, con score di similarita. Per aggiornare la galleria (aggiungere o rimuovere riferimenti), modificare i file in references/ e premere r per ricaricare.

Con una galleria attiva, e mostra una heatmap (colormap INFERNO: viola->giallo) delle zone del volto che piu influenzano l'embedding di identita: le aree gialle sono dove il trucco ha il massimo impatto per l'evasione.

La finestra "aligned" mostra i crop 112x112 allineati in tempo reale.

Per la pipeline sperimentale (cattura dataset, ottimizzazione, valutazione) vedi docs/pipeline-sperimentale.md. Per i renderer legacy (texture pixel, poligoni, shape palette) vedi docs/legacy-renderers.md.

Funzionalita

• Detection multi-backend — YuNet, OpenCV DNN (SSD), RetinaFace (MobileNet 0.25)
• 478 landmark facciali — MediaPipe Face Mesh con regioni colorate (occhi, sopracciglia, naso, labbra, iride, ovale)
• Allineamento ArcFace — crop 112x112 con 5 keypoint di riferimento, preview live
• Saliency map detection — heatmap dei gradienti: mostra quali pixel influenzano di piu la detection
• Saliency map embedding — heatmap dei gradienti di similarita coseno: mostra dove truccare per massimizzare l'evasione dell'identita
• Keypoint e anchor box overlay — visualizza i 5 punti ArcFace e le anchor box RetinaFace con i relativi score
• Gaussian mesh rendering — ~300 Gaussiane 2D sui vertici della mesh facciale, sigma adattivo, rendering diretto in frame space
• 73 pattern pre-ottimizzati — tre collezioni estetiche (fluo, naturale, teatrale) con varianti di densita
• Ottimizzazione adversarial — genera pattern Gaussian mesh tramite rasterizzazione differenziabile con loss detection + embedding + regolarizzazione
• Palette vincolata — ottimizzazione con colori vincolati a una palette scelta, per pattern cromaticamente coerenti
• Mesh 3D — warping tramite mesh facciale 3D
• Feedback evasione — barra in tempo reale: tasso di detection, confidenza, jitter dell'allineamento
• Cattura dataset — raccolta automatica di frame diversificati per posa e illuminazione
• Generazione maschera — maschera della zona truccabile (ovale - occhi - labbra) con feathering
• Attacco all'embedding — loss coseno su ArcFace (IResNet-50, w600k_r50): il trucco puo rendere il volto non solo invisibile al detector, ma anche non riconoscibile

Architettura

src/viso/
├── __main__.py          # CLI e routing subcomandi
├── main.py              # Loop principale (webcam/immagine)
├── align.py             # Allineamento ArcFace (5 keypoint -> crop 112x112)
├── feedback.py          # Tracker detection/allineamento + barre feedback
├── overlay.py           # Applicazione texture/Gaussian mesh via warp
├── keypoint_overlay.py  # Visualizzazione keypoint ArcFace e anchor box
├── recognition.py       # Galleria riferimenti + riconoscimento live
├── saliency.py          # Saliency map (detection + embedding -> heatmap)
├── colors.toml          # Configurazione colori landmark per regione
│
├── landmarkers/
│   ├── __init__.py      # Region enum, Landmark, protocollo Landmarker
│   └── mediapipe_lm.py  # MediaPipe Face Mesh (478 punti)
│
├── detectors/
│   ├── __init__.py      # Detection NamedTuple, protocollo Detector
│   ├── dnn.py           # OpenCV DNN SSD (Caffe)
│   ├── yunet.py         # YuNet (ONNX, detection + 5 landmark)
│   └── retinaface.py    # RetinaFace (MobileNet 0.25)
│
└── adversarial/
    ├── models.py         # RetinaFaceTarget + ArcFaceTarget (wrapper differenziabili)
    ├── iresnet.py        # IResNet-50 backbone per ArcFace
    ├── loss.py           # Loss: detection + embedding + landmark + regolarizzazione
    ├── gaussian_renderer.py # GaussianMeshRenderer (Gaussiane 2D su mesh)
    ├── renderer.py       # MakeupRenderer (legacy, texture pixel)
    ├── polygon_renderer.py # PolygonRenderer (legacy, triangoli)
    ├── mask.py           # Generazione maschera zona truccabile
    ├── capture.py        # Cattura dataset con selezione per diversita
    ├── optimize.py       # Loop di ottimizzazione
    └── retinaface/
        ├── net.py        # Architettura RetinaFace (MobileNet + FPN + SSH)
        └── prior_box.py  # Generazione anchor box e decodifica bbox

Sviluppo

make fmt          # Formatta codice (ruff)
make lint         # Lint (ruff)
make typecheck    # Type check (pyright)
make test         # Test (pytest)
make complexity   # Complessita ciclomatica (radon)
make check        # Tutti i check