README.md

---
license: apache-2.0
library_name: libreyolo
pipeline_tag: image-feature-extraction
tags:
  - face-recognition
  - face-embedding
  - arcface
  - onnx
  - libreyolo
---

# librefacerec-l

512-d face-embedding model for LibreYOLO's facial-recognition (`embed`) task:
aligned 112x112 RGB face crop in, L2-normalized 512-d identity embedding out
(iResNet100, ArcFace input convention). Verification and identification are
cosine similarity on these embeddings.

## Usage

```python
from libreyolo import LibreYOLO, FaceGallery

model = LibreYOLO("librefacerec-l")          # auto-downloads this file

# 1:1 verification
model.verify("a.jpg", "b.jpg", threshold=0.4)

# 1:N identification
gallery = FaceGallery(embedder=model)
gallery.enroll("alice", ["alice1.jpg", "alice2.jpg"])
results = model("group.jpg", gallery=gallery)
print(results.identities.name)
```

```bash
libreyolo compare model=facerec-l source=a.jpg source2=b.jpg
libreyolo enroll  model=facerec-l source=people/ gallery=team.gallery.npz
libreyolo predict model=facerec-l source=group.jpg gallery=team.gallery.npz
```

The default face detector (`librefacerec-det`) is auto-downloaded separately.

## Provenance and license

- Mirrored unmodified from
  [fal/AuraFace-v1](https://huggingface.co/fal/AuraFace-v1) `glintr100.onnx`
  (Apache-2.0), renamed to `librefacerec-l.onnx`.
- SHA-256: `a7933ea5330113b01c9b60351d8f4c33003f145d8470ac5f0e52ee2effe25c60`
  (verified identical to upstream at mirror time, 2026-07-28).
- Training data: not disclosed by the upstream authors (described only as a
  commercially licensed face dataset). Evaluate fitness for your use case
  accordingly.
- Only this single file is mirrored; other files in the upstream repository
  are third-party artifacts under different terms and are NOT mirrored here.

## Accuracy

Measured 2026-07-28 through the full LibreYOLO pipeline (detect, 5-point
align, embed) on the standard LFW dev pairs, using the funneled originals.
The decision threshold was selected on `pairsDevTrain` (1100 pairs) and
accuracy is reported on the held-out `pairsDevTest` (1000 pairs, 500 same
and 500 different), so the headline number is not tuned on itself.

| Metric | Value |
|---|---|
| ROC-AUC | 0.980 |
| Accuracy @ threshold 0.227 (selected on train) | 96.9% |
| Accuracy @ threshold 0.400 (library default) | 95.6% |
| Mean cosine, same person | 0.572 (std 0.159) |
| Mean cosine, different people | 0.063 (std 0.063) |

Operating points on the held-out split:

| Threshold | False accept | False reject | Accuracy |
|---|---|---|---|
| 0.30 | 0.0% | 5.4% | 97.3% |
| 0.40 | 0.0% | 8.8% | 95.6% |
| 0.50 | 0.0% | 25.0% | 87.5% |

The distribution is heavily separated in the false-accept direction: no
different-person pair in this split scored above 0.30. The library's 0.4
default is therefore conservative, trading recall for near-zero false
accepts, which suits access-control style uses; lower it toward 0.3 when
missed matches cost more than false ones.

For calibration, note that LFW is a saturated benchmark where leading
ArcFace-family models report roughly 99.5% and above. This pipeline's 96.9%
is usable but not state of the art, and it is a single benchmark on a
frontal, celebrity-photo distribution. Evaluate on data representative of
your deployment.

## Responsible use

This model produces biometric identifiers. It is intended for consent-based
applications (device unlock, photo-library organization, opt-in event
galleries). Remote biometric identification of individuals in public spaces
is prohibited or heavily restricted in several jurisdictions (EU AI Act,
BIPA and similar laws), and compliance is the deployer's responsibility.
Accuracy varies across demographics; calibrate thresholds for your
population and application.