video_helper.faces.track module

video_helper.faces.track

Lightweight multi-face tracking: greedy IoU association (SORT/ByteTrack-family, pure NumPy, no model weights). Meeting / talking-head video moves slowly, so IoU linking with a short “coast” through missed frames is enough to build coherent face tracks — the unit ASD and recognition actually operate on.

Face-embedding-based stitching of tracks that a person split by leaving and re-entering frame is handled one level up (in the resolver, where embeddings are already computed) — the face analogue of voiceprint re-identification.

class video_helper.faces.track.FaceTrack(track_id, frame_idx=<factory>, faces=<factory>)

Bases: object

A temporally coherent sequence of one face’s detections.

Parameters:

• track_id (int)

• frame_idx (list[int])

• faces (list[Face])

track_id

Stable id across the video (subject to stitching upstream).

Type:

int

frame_idx

Absolute frame indices where the face was seen.

Type:

list[int]

faces

The per-frame detection at each frame_idx.

Type:

list[Face]

add(frame_idx, face)

Parameters:

• frame_idx (int)

• face (Face)

Return type:

None

faces: list[Face]

frame_idx: list[int]

property last_box: tuple[float, float, float, float]

span(fps)

Track time span (t0, t1) in seconds given the sampling fps.

Parameters:

fps (float)

Return type:

tuple[float, float]

track_id: int

video_helper.faces.track.track_faces(frame_dets, *, iou_threshold=0.3, max_gap=15)

Link per-frame detections into tracks by greedy IoU association.

Parameters:

• frame_dets (list[tuple[int, list[Face]]]) – (frame_idx, faces) in increasing frame order.

• iou_threshold (float, optional) – Minimum IoU to attach a detection to an existing track.

• max_gap (int, optional) – How many frames a track may coast unmatched before it is retired (lets a track survive a brief miss / occlusion).

Returns:

All tracks discovered, in creation order.

Return type:

list[FaceTrack]