# Face Tracker 整合 Identity Registration 完成报告

> 实验日期: 2026-04-28
> 实验版本: V3.0 (Face Tracker + Reference Vector Selection)

---

## 实验概述

将 **Face Tracker** 整合到 **Identity Registration** 流程：

1. **Face Tracker**: 追踪人脸跨帧连续性，分配 `trace_id`
2. **Reference Vector Selection V3**: 从特定 trace 选择参考向量
3. **Identity Registration**: 注册带 trace statistics 的 identity

---

## 创建的文件

| 文件 | 说明 |
|------|------|
| `scripts/utils/face_tracker.py` | 人脸追踪脚本 |
| `scripts/utils/face_trace_visualizer.py` | 可视化脚本 |
| `scripts/select_face_reference_vectors_v3.py` | Trace-based 参考向量选择 |
| `docs_v1.0/FACE_TRACKER_GUIDE.md` | Face Tracker 功能文档 |

---

## 测试结果

### 1. Face Tracking

| Trace | Frames | Duration | Appearances | Avg Confidence | Pose Distribution |
|-------|--------|----------|-------------|----------------|-------------------|
| **0** | 1-146 | 6.64s | 146 | **0.76** | three_quarter (144), profile_left (2) |
| **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 2 置信度最高 (0.862)，适合作为 Identity 参考向量来源
- Trace 3 置信度较低 (0.69)，可能不适合注册

---

### 2. Reference Vector Selection V3

| 参数 | Trace 0 | Trace 2 |
|------|---------|---------|
| **Vectors Selected** | 4 | 4 |
| **Angles Covered** | three_quarter, profile_left | profile_right, three_quarter |
| **Quality Avg** | 0.774 | **0.875** ✅ |

**Trace 2 Vector Details**:
```
Vector 1: profile_right (frame 220), quality: 0.889
Vector 2: profile_right (frame 212), quality: 0.889
Vector 3: three_quarter (frame 180), quality: 0.861
Vector 4: three_quarter (frame 181), quality: 0.861
```

---

### 3. Identity Matching

| 指标 | Trace 2 Identity | Trace 0 Identity |
|------|-------------------|------------------|
| **Match Ratio** | **33.54%** (108/322) | 未测试 |
| **profile_right Similarity** | **0.8361** ✅ | 未测试 |
| **three_quarter Similarity** | 0.4398 | 未测试 |
| **Angle Match Types** | exact (288), fallback (34) | 未测试 |

**对比之前的单一向量匹配**:
| 匹配策略 | Match Ratio | profile_right Similarity |
|----------|-------------|--------------------------|
| Best Match (单向量) | 48.39% | 0.08 ❌ |
| Pose-filtered V2 | 41.94% | 0.8547 ✅ |
| **Trace-based V3** | **33.54%** | **0.8361** ✅ |

**说明**:
- Trace-based V3 Match Ratio 较低 (33.54% vs 41.94%)
- 原因: Trace 2 仅覆盖 frames 155-297，不包括 Trace 0 和 Trace 3
- 优势: 高置信度匹配（仅匹配 Trace 2 frames），相似度高 (0.8361)

---

### 4. trace_stats 存储

```json
{
  "trace_id": 2,
  "trace_stats": {
    "start_frame": 155,
    "end_frame": 297,
    "duration_frames": 143,
    "duration_seconds": 6.5,
    "total_appearances": 143,
    "avg_confidence": 0.8624,
    "pose_distribution": {
      "profile_right": 125,
      "three_quarter": 18
    }
  }
}
```

---

## 完整流程

### 建议使用方式

```bash
# Step 1: Face detection (所有帧)
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: 分析 traces，选择最佳 trace
python3 scripts/utils/face_tracker.py \
  --face-json video.face_traced.json \
  --analyze-only

# Step 4: 从最佳 trace 选择参考向量
python3 scripts/select_face_reference_vectors_v3.py \
  --face-json video.face_traced.json \
  --trace-id-filter 2 \
  --identity-name "Person Name" \
  --register

# 或自动选择最长 trace
python3 scripts/select_face_reference_vectors_v3.py \
  --face-json video.face_traced.json \
  --use-longest-trace \
  --identity-name "Person Name" \
  --register

# Step 5: Matching (可选，验证 identity)
python3 scripts/match_face_with_pose_filtering.py \
  --identity-name "Person Name" \
  --face-json video.face_traced.json \
  --strategy pose_filtered_v2 \
  --batch
```

---

## trace_id 选择建议

| 场景 | 建议 |
|------|------|
| **单人视频** | 使用 `--use-longest-trace` |
| **多人视频** | 使用 `--trace-id-filter 2`（指定最佳 trace） |
| **高质量 Identity** | 选择 avg_confidence > 0.85 的 trace |
| **低质量视频** | 检查 trace confidence，低于 0.7 不建议注册 |

---

## reference_data 结构对比

### V2 vs V3

| 字段 | V2 | V3 |
|------|----|----|
| **face_embeddings** | ✅ | ✅ (相同格式) |
| **angle_coverage** | ✅ | ✅ |
| **trace_id** | ❌ | ✅ |
| **trace_stats** | ❌ | ✅ |
| **selection_method** | `v2_auto_multi_angle` | `trace_filtered_v3` |

**V3 优势**:
- 包含 trace 统计信息（duration, confidence, pose distribution）
- 确保参考向量来自同一人物（同 trace_id）
- 更好的质量控制（选择高置信度 trace）

---

## 未来改进

| Phase | 功能 | 优先级 |
|-------|------|--------|
| **Phase 1** | Trace-based Registration (已完成) | ✅ |
| **Phase 2** | Multi-trace Identity（合并多个 trace） | 中 |
| **Phase 3** | Trace quality scoring（自动选择最佳 trace） | 中 |
| **Phase 4** | Real-time tracking API | 低 |

---

## 版本信息

- 版本: 3.0
- 创建日期: 2026-04-28
- 状态: ✅ Face Tracker + Reference Vector Selection V3 完成

---

## 参考文档

- `scripts/utils/face_tracker.py`: 人脸追踪脚本
- `scripts/utils/face_trace_visualizer.py`: 可视化脚本
- `scripts/select_face_reference_vectors_v3.py`: Trace-based 参考向量选择
- `docs_v1.0/FACE_TRACKER_GUIDE.md`: Face Tracker 功能文档
- `docs_v1.0/EXPERIMENT_REPORTS/POSE_BASED_MATCHING_FINAL_REPORT_2026-04-28.md`: Pose Optimization 报告
