video_helper.faces.recognize module

video_helper.faces.recognize

Face-recognition embeddings via OpenCV’s SFace (cv2.FaceRecognizerSF), Apache-2.0, HuggingFace-free. SFace emits a 128-d embedding (not 512-d); downstream stores must size themselves from FaceRecognizer.emb_dim, not a hard-coded constant.

Alignment is delegated to cv2.FaceRecognizerSF.alignCrop, which consumes the raw YuNet detector row (5 landmarks) to similarity-transform each face to the canonical 112×112 template — so detection and recognition share one landmark source and there is no second alignment implementation to keep in sync.

class video_helper.faces.recognize.FaceRecognizer

Bases: object

Lazy, reusable SFace embedder.

emb_dim

Embedding dimensionality (128 for SFace). Read this rather than assuming.

Type:

int

embed(frame_bgr, face)

Return the L2-normalised 128-d embedding for one face, or None.

The face is aligned+cropped from frame_bgr using its raw YuNet row, then run through SFace. Returns None on any failure so callers can skip a bad crop rather than poison an average.

Parameters:

• frame_bgr (ndarray)

• face (Face)

Return type:

ndarray | None

embed_track(frames, faces, *, top_k=12)

Aggregate one persistent embedding for a face track.

Quality-gates the crops (highest detector score first — the face analogue of picking the longest, most-confident turns for a voiceprint), embeds up to top_k of them, and returns the L2-normalised mean. None if no crop yields a usable embedding.

Parameters:

• frames (list[ndarray])

• faces (list[Face])

• top_k (int)

Return type:

ndarray | None

video_helper.faces.recognize.l2(v)

L2-normalise a single vector (matches identity.py’s convention).

Parameters:

v (ndarray)

Return type:

ndarray