momentry_core/docs_v1.0/FACE_TRACKER_GUIDE.md

Face Tracker 功能文档

创建日期: 2026-04-28 脚本路径: scripts/utils/face_tracker.py

---

功能概述

Face Tracker 追踪视频中同一人脸在不同帧之间的连续性，为每个人脸分配唯一的 trace_id。

---

核心功能

1. 人脸追踪

功能	说明
trace_id 分配	每个追踪的人脸获得唯一 ID
跨帧匹配	使用 bbox IoU + embedding similarity
路径记录	记录人脸位置、置信度、pose 变化

2. 匹配算法

匹配条件（优先级）:
1. bbox IoU > 0.3 AND embedding similarity > 0.7  → 最佳匹配
2. bbox IoU > 0.5                                   → 位置匹配
3. embedding similarity > 0.85                      → 高置信度匹配
4. distance < 100 AND similarity > 0.6             → fallback 匹配

---

使用方式

基础用法

# 追踪人脸
python3 scripts/utils/face_tracker.py \
  --face-json output/video.face.json \
  --output output/video.face_traced.json

# 仅分析（不输出）
python3 scripts/utils/face_tracker.py \
  --face-json output/video.face.json \
  --analyze-only

参数调整

# 调整匹配阈值
python3 scripts/utils/face_tracker.py \
  --face-json output/video.face.json \
  --iou-threshold 0.4 \
  --similarity-threshold 0.75 \
  --distance-threshold 80

# 禁用 embedding 匹配（仅使用位置）
python3 scripts/utils/face_tracker.py \
  --face-json output/video.face.json \
  --no-embedding

---

输出结构

1. face.json 结构变化

Before:

{
  "frames": {
    "210": {
      "faces": [
        {"x": 208, "y": 71, "embedding": [...], "pose_angle": {...}}
      ]
    }
  }
}

After:

{
  "frames": {
    "210": {
      "faces": [
        {
          "x": 208,
          "y": 71,
          "embedding": [...],
          "pose_angle": {...},
          "trace_id": 2  // 新增
        }
      ]
    }
  },
  "traces": {  // 新增
    "2": {
      "trace_id": 2,
      "start_frame": 155,
      "end_frame": 297,
      "duration_frames": 143,
      "duration_seconds": 6.5,
      "total_appearances": 143,
      "avg_confidence": 0.862,
      "pose_angles": ["profile_right", ...],
      "path": [
        {"frame": 155, "bbox": {...}, "confidence": 0.87, "pose_angle": "profile_right"},
        ...
      ]
    }
  },
  "metadata": {  // 新增统计
    "trace_stats": {
      "total_traces": 4,
      "active_traces": 4,
      "long_traces": 3
    }
  }
}

2. traces 结构详解

字段	说明
trace_id	唯一追踪 ID
start_frame	首次出现帧号
end_frame	最后出现帧号
duration_frames	持续帧数
duration_seconds	持续时间（秒）
total_appearances	总出现次数
avg_confidence	平均检测置信度
pose_angles	Pose 变化序列
path	详细路径（bbox, confidence, pose）

---

可视化工具

face_trace_visualizer.py

# 生成可视化图表 + CSV
python3 scripts/utils/face_trace_visualizer.py \
  --face-json output/video.face_traced.json \
  --output-plot output/face_trace_visualization.png \
  --output-csv output/face_trace_stats.csv

输出图表

图表	说明
X Position	人脸 X 坐标随时间变化
Y Position	人脸 Y 坐标随时间变化
Confidence	检测置信度随时间变化
Pose Distribution	各 trace 的 pose 分布

---

实测案例

preview.mp4 (15秒, 329帧)

Trace	Frames	Duration	Appearances	Avg Confidence	Pose Distribution
0	1-146	6.64s	146	0.76	three_quarter (144), profile_left (2)
1	147	0.05s	1	-	single appearance
2	155-297	6.50s	143	0.86	profile_right (125), three_quarter (18)
3	298-329	1.45s	32	0.69	profile_left (32)

分析结论:

• Trace 0: 主要人物 A（前半段）
• Trace 2: 主要人物 B（后半段，高置信度）
• Trace 3: 主要人物 C（结尾，侧脸）
• Gap: frames 148-154 (7帧无人脸检测)

---

应用场景

场景	用途
Identity Registration	从 longest trace 选择参考向量
Person Tracking	追踪视频中的人物轨迹
Scene Analysis	分析人物在不同场景的出现
Quality Control	识别低置信度 trace（需重新处理）

---

与 Identity Registration 整合

建议流程

# Step 1: Face detection + pose
python3 scripts/face_processor.py video.mp4 video.face.json --sample-interval 1

# Step 2: Face tracking
python3 scripts/utils/face_tracker.py --face-json video.face.json --output video.face_traced.json

# Step 3: Select reference vectors from longest trace
python3 scripts/select_face_reference_vectors_v2.py \
  --face-json video.face_traced.json \
  --trace-id-filter 2 \
  --identity-name "Person Name" \
  --register

trace-id-filter 逻辑

仅从指定 trace_id 的人脸中选择参考向量：

• 确保同一人物的多角度参考
• 避免不同人物的 embedding 混合
• 选择 longest trace 作为主要 identity

---

参数优化建议

场景	参数调整
快速移动人脸	--distance-threshold 150 (更宽容)
低质量视频	--similarity-threshold 0.65 (降低阈值)
多人场景	--iou-threshold 0.5 (更严格位置匹配)
稳定人脸	默认参数即可

---

未来改进

Phase	功能	优先级
Phase 1	基础追踪（已完成）	✅
Phase 2	3D pose estimation	中
Phase 3	Multi-face interaction tracking	低
Phase 4	Real-time tracking API	低

---

参考文档

• scripts/utils/face_tracker.py: 人脸追踪脚本
• scripts/utils/face_trace_visualizer.py: 可视化脚本
• scripts/face_processor.py: 人脸检测脚本
• scripts/select_face_reference_vectors_v2.py: 参考向量选择

---

版本信息

• 版本: 1.0
• 创建日期: 2026-04-28
• 状态: ✅ 已完成基础功能