# Formato JSON di face_scan

`face_scan` scrive un singolo oggetto JSON su standard output.

Gli errori e i messaggi diagnostici vengono scritti su standard error.

## Invocazione

```bash
./bin/face_scan /percorso/immagine.jpg
```

## Esempio

```json
{
  "image": {
    "path": "/percorso/immagine.jpg",
    "width": 1500,
    "height": 2000
  },
  "faces": [
    {
      "face_index": 0,
      "score": 0.8671875,
      "bbox": {
        "x": 1079.3457,
        "y": 489.648438,
        "width": 131.591797,
        "height": 182.275391
      },
      "landmarks": [
        [1107.8125, 558.325195],
        [1170.99609, 559.423828],
        [1134.17969, 594.500732],
        [1106.22559, 615.83252],
        [1168.34717, 616.967773]
      ],
      "embedding": [
        -0.0426222458,
        0.0678814054
      ]
    }
  ]
}
```

L'array `embedding` reale contiene sempre 128 valori.

## Oggetto image

Campi disponibili:

- `path`: percorso ricevuto dal programma;
- `width`: larghezza originale dell'immagine;
- `height`: altezza originale dell'immagine.

## Oggetto face

Campi disponibili:

- `face_index`: indice sequenziale del volto;
- `score`: confidence SCRFD;
- `bbox.x`: coordinata sinistra;
- `bbox.y`: coordinata superiore;
- `bbox.width`: larghezza;
- `bbox.height`: altezza;
- `landmarks`: cinque coppie di coordinate;
- `embedding`: vettore L2-normalizzato di 128 elementi.

## Immagini senza volti

Un'immagine elaborata correttamente ma senza volti produce:

```json
{
  "image": {
    "path": "image.jpg",
    "width": 1920,
    "height": 1080
  },
  "faces": []
}
```

L'exit code resta `0`.

## Exit code

```text
0   scansione completata
2   argomenti non validi
3   inizializzazione FaceEngine fallita
4   caricamento o elaborazione immagine fallita
5   risultato facciale o embedding non valido
```

## Requisiti dell'embedding

Per ogni volto:

```text
Dimensione   128
Tipo logico  float32
Norma L2     circa 1.0
Valori       tutti finiti
```

Quando viene salvato in formato binario float32:

```text
128 x 4 byte = 512 byte
```