Python binding for the FaceX face detection + recognition library.

cd python/
pip install -e .

# With Pillow for image loading:
pip install -e ".[image]"

import numpy as np
from facex import FaceX

# Initialize (auto-finds library and weights)
fx = FaceX()

# Load an image as RGB uint8 numpy array (H, W, 3)
from PIL import Image
image = np.array(Image.open("photo.jpg").convert("RGB"))

# Detect faces — returns list of dicts
faces = fx.detect(image)
for face in faces:
    print(f"bbox: {face['bbox']}, score: {face['score']:.3f}")
    print(f"keypoints: {face['keypoints']}")
    # face['embedding'] is a 512-dim numpy float32 vector

# Compare two faces
if len(faces) >= 2:
    sim = FaceX.similarity(faces[0]["embedding"], faces[1]["embedding"])
    print(f"Similarity: {sim:.3f}  ({'same' if sim > 0.3 else 'different'} person)")

FaceX looks for the native library and weights relative to the package location (expects ../../weights/ and ../../libfacex.so or ../../facex.dll).

fx = FaceX(
    lib_path="/path/to/libfacex.so",
    embed_weights="/path/to/embed.bin",
    detect_weights="/path/to/detect.bin",
    score_threshold=0.5,
    nms_threshold=0.4,
    max_faces=20,
)

Main class. Uses ctypes (shared library) if available, falls back to subprocess (CLI).

• detect(image, max_faces=None) -- Detect faces in an RGB uint8 image. Returns list of dicts with bbox, score, keypoints, embedding.
• embed(face_112x112) -- Compute embedding for a pre-aligned 112x112 face (ctypes only). Input: float32 HWC in [-1, 1]. Returns 512-dim float32 array.
• similarity(emb1, emb2) -- Static method. Cosine similarity between two 512-dim embeddings. Returns float in [-1, 1].
• close() -- Free native resources. Also works as context manager (with FaceX() as fx: ...).
• backend -- Property: "ctypes", "cli", or "none".

Module-level function, same as FaceX.similarity(). Works without initializing FaceX.

from facex import similarity
sim = similarity(emb1, emb2)

Similarity always works (pure numpy).