LibreFaceRec

Install

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

pip install "libreyolo[onnx]"

Predict

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

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

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"])

from libreyolo import LibreYOLO model = LibreYOLO("librefacerec-l.onnx") query = model("query.jpg").embeddings          # this image's facesgallery = 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 for sources, streaming and result handling.

Export

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

Licensing

Citation

@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}
}