# 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 匹配
```

---

## 使用方式

### 基础用法

```bash
# 追踪人脸
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
```

### 参数调整

```bash
# 调整匹配阈值
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**:
```json
{
  "frames": {
    "210": {
      "faces": [
        {"x": 208, "y": 71, "embedding": [...], "pose_angle": {...}}
      ]
    }
  }
}
```

**After**:
```json
{
  "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

```bash
# 生成可视化图表 + 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 整合

### 建议流程

```bash
# 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
- 状态: ✅ 已完成基础功能