face-clustering-rk3588./docs/architecture.md

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

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:

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