video_helper.faces.detect module

video_helper.faces.detect

Per-frame face detection with 5-point landmarks via OpenCV’s YuNet (cv2.FaceDetectorYN). Tiny, fast, Apache-2.0, HuggingFace-free.

The 5 landmarks (right eye, left eye, nose tip, right mouth corner, left mouth corner) are what the recognition aligner and the ASD mouth-ROI both need, so the raw detector row is carried through on each Face for downstream reuse (cv2.FaceRecognizerSF.alignCrop consumes it directly — no re-derivation).

class video_helper.faces.detect.Face(box, landmarks, score, raw)[source]

Bases: object

One detected face in one frame.

Parameters:

box (tuple[float, float, float, float])
landmarks (ndarray)
score (float)
raw (ndarray)

box

(x, y, w, h) in pixels.

Type:: tuple[float, float, float, float]

landmarks

(5, 2) float array — see _LANDMARK_NAMES.

Type:: np.ndarray

score

Detector confidence in [0, 1].

Type:: float

raw

The full 15-float YuNet row (box + 10 landmark coords + score), kept so cv2.FaceRecognizerSF.alignCrop can be fed the exact detector output.

Type:: np.ndarray

box: tuple[float, float, float, float]

landmarks: ndarray

raw: ndarray

score: float

class video_helper.faces.detect.FaceDetector(*, score_threshold=0.6, min_size=40)[source]

Bases: object

Lazy, reusable YuNet detector.

The underlying cv2.FaceDetectorYN is created on first use and its input size is reset per frame (YuNet requires the exact frame dimensions). Construction never downloads; the first detect() does.

Parameters:

score_threshold (float)
min_size (int)

detect(frame_bgr)[source]

Detect faces in a single BGR uint8 frame (OpenCV convention).

Parameters:: frame_bgr (ndarray)
Return type:: list[Face]