# LibreFaceRec
LibreFaceRec is LibreYOLO's face-embedding task: a face detector locates and aligns faces, and a recognition head produces an L2-normalized identity embedding for verification or search.
Tasks: Embeddings. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.0.

## Install

LibreFaceRec's recognition head runs through `onnxruntime`, which is not part
of the base install.

```bash
pip install "libreyolo[onnx]"
```

## Predict

**Python**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

# librefacerec-* names route to this family regardless of file
# suffix and download from the LibreYOLO Hugging Face org on first
# use, along with the default face detector.
model = LibreYOLO("librefacerec-l.onnx")
result = model(SAMPLE_IMAGE)

print(result.embeddings.data.shape)   # (N, D), L2-normalized
```

**CLI**

```bash
libreyolo predict model=librefacerec-l.onnx source=face.jpg
```

**Verify**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("librefacerec-l.onnx")

# Compares the most prominent face in each image via cosine
# similarity of their L2-normalized embeddings.
result = model.verify("person_a.jpg", "person_b.jpg", threshold=0.4)
print(result["similarity"], result["same_person"])
```

**Gallery search**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("librefacerec-l.onnx")

query = model("query.jpg").embeddings          # this image's faces
gallery = model.embed(["a.jpg", "b.jpg", "c.jpg"])   # (N_total, D)

# (query_faces, N_total) cosine similarities.
scores = query.similarity(gallery)
```

Detection and recognition are two separate ONNX graphs behind one call: a
face detector locates and aligns each face to a canonical crop, and the
recognition head returns an L2-normalized embedding per face. Left alone,
`predict()` downloads and pairs the bundled default detector automatically.
`face_detector` accepts a callable, a LibreYOLO detection model, or a
`FaceDetector` instance; `face_boxes` bypasses detection entirely with boxes
you already have. `result.embeddings` holds one row per detected face,
aligned with `result.boxes`; its `.similarity()` method computes cosine
similarity against another embedding or a whole gallery in one call. For
comparing two images directly rather than two already-computed embeddings,
`model.verify(image_a, image_b)` runs detection and embedding on both and
compares their most confident face. Any other ArcFace-convention ONNX
recognition model (aligned crop in, `(N, D)` embeddings out) can be
substituted by passing its file path instead of a `librefacerec-*` name. See
[prediction](/docs/predict) for sources, streaming and result handling.

## Export

| Task | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | ncnn | TFLite | CoreML | Core AI |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Embeddings |  |  |  |  |  |  |  |  |  |  |  |  |

A "yes" means the export is supported. An empty cell means the exporter refuses that combination.

LibreFaceRec already wraps a pre-exported ONNX graph; re-exporting it to
another format is not implemented.

## Licensing

Check the license on the Hugging Face repository of the specific weights you download. That repository is authoritative and licenses are not always uniform across a family. This is a description of the licenses involved, not legal advice.

- Original work: AuraFace-v1, fal.ai
- Upstream license: Apache-2.0
- Upstream source: https://huggingface.co/fal/AuraFace-v1
- LibreYOLO code: MIT
- Weights: Apache-2.0, distributed by their authors. LibreYOLO does not host or mirror them.
- Interpretation: Apache-2.0 covers the embedding weights (AuraFace-v1's glintr100 recognition head), so they may be used, modified and redistributed, including commercially, provided the license text and attribution notices travel with any copy. LibreYOLO's default face detector is a separate artifact under a separate license, MIT (OpenCV Zoo's YuNet, copyright Shiqi Yu). No code is ported from either project: both graphs are consumed opaquely through onnxruntime, so LibreYOLO's own wrapper code, which carries no third-party architecture, is MIT throughout. Any other ArcFace-convention ONNX recognition model can be substituted by passing its file path, and that file's own license then applies instead of AuraFace-v1's.

The bundled default face detector is a second artifact under a second
license: OpenCV Zoo's YuNet, MIT, copyright Shiqi Yu. No architecture code is
ported from either project; both graphs are consumed opaquely through
`onnxruntime`, so LibreYOLO's own wrapper carries no third-party code and is
MIT throughout.

## Citation

```bibtex
@inproceedings{deng2019arcface,
  title={Arcface: Additive angular margin loss for deep face recognition},
  author={Deng, Jiankang and Guo, Jia and Xue, Niannan and Zafeiriou, Stefanos},
  booktitle={CVPR},
  year={2019}
}
```

Copied from https://github.com/deepinsight/insightface/tree/master/recognition/arcface_torch#citations


## Face recognition architecture

- Face recognition l: ONNX iResNet100: [SVG](/diagrams/models/librefacerec/l-core-embed.svg), [interactive diagram](/diagrams/models/librefacerec/l-core-embed.html)
- Face recognition default detector: ONNX graph: [SVG](/diagrams/models/librefacerec/detector-640.svg), [interactive diagram](/diagrams/models/librefacerec/detector-640.html)
- Face recognition l: [SVG](/diagrams/models/librefacerec/l-embed.svg), [interactive diagram](/diagrams/models/librefacerec/l-embed.html)