# Architettura

Il progetto separa il motore di elaborazione facciale dai programmi che lo
utilizzano.

## Componenti principali

### face_engine.h

Definisce l'interfaccia pubblica C++:

- `Point`;
- `Face`;
- `FaceEngine`;
- inizializzazione dei modelli;
- elaborazione di una singola immagine.

### face_engine.cc

Implementa:

- caricamento delle immagini tramite stb_image;
- resize bilineare;
- conversione float32 e float16;
- inferenza SCRFD tramite RKNN;
- decodifica di score, bounding box e landmark;
- non-maximum suppression;
- trasformazione similarity;
- allineamento facciale;
- inferenza SFace tramite RKNN;
- conversione dell'output;
- normalizzazione L2 dell'embedding.

### face_recognition.cc

Programma dimostrativo con output leggibile.

Può:

- elaborare una singola immagine;
- elaborare due immagini;
- confrontare tutti i volti rilevati tramite cosine similarity.

### face_scan.cc

Programma destinato all'integrazione con altri software.

Caratteristiche:

- elabora una singola immagine;
- scrive esclusivamente JSON su standard output;
- scrive diagnostica ed errori su standard error;
- valida la dimensione degli embedding;
- rifiuta valori NaN o infiniti;
- restituisce exit code documentati.

## Pipeline runtime

```text
File immagine
    |
    v
Caricamento RGB
    |
    v
Resize proporzionale
    |
    v
Input SCRFD 640 x 640 FLOAT16 NHWC
    |
    v
SCRFD su NPU
    |
    v
Decodifica livelli stride 8, 16 e 32
    |
    v
Score threshold
    |
    v
Non-maximum suppression
    |
    v
Bounding box e cinque landmark
    |
    v
Similarity transform
    |
    v
Volto allineato 112 x 112
    |
    v
SFace su NPU
    |
    v
Embedding 128D
    |
    v
Normalizzazione L2
```

## Riutilizzo

Le applicazioni C++ possono utilizzare direttamente `FaceEngine`.

Applicazioni scritte in altri linguaggi possono eseguire
`face_scan` come processo figlio e analizzare il JSON prodotto.

Il motore non dipende:

- dal server della galleria;
- dal database;
- dall'interfaccia utente;
- da uno specifico framework applicativo.

## Estensione futura

Gli embedding prodotti da `FaceEngine` saranno utilizzati dalla
pipeline di clustering:

```text
FaceEngine
    |
    v
Embedding float32[N][128]
    |
    v
kNN OpenCL TOPK=32
    |
    v
Core distance
    |
    v
Mutual reachability
    |
    v
Minimum spanning tree
    |
    v
HDBSCAN
    |
    v
Cluster ID per embedding
```