# Face Tracker 记录内容详解

> 文件: face_traced.json
> 创建日期: 2026-04-28
> 更新: 2026-04-28 (添加 Pose Trace)

---

## 文件结构

```
face_traced.json
├── metadata              # 元数据（新增 trace_stats）
│   ├── video_path
│   ├── fps
│   ├── width/height
│   ├── total_frames
│   ├── trace_stats       # 新增：追踪统计
│   │   ├── total_traces
│   │   ├── active_traces
│   │   └── long_traces
│   └── ...
├── frames                # 所有帧的人脸数据
│   ├── "30": {           # 帧 30
│   │   ├── frame_number
│   │   ├── time_seconds
│   │   ├── faces         # 该帧的人脸列表
│   │   │   ├── face[0]
│   │   │   │   ├── x, y, width, height
│   │   │   │   ├── confidence
│   │   │   │   ├── embedding
│   │   │   │   ├── landmarks
│   │   │   │   ├── pose_angle
│   │   │   │   ├── attributes
│   │   │   │   └── trace_id    # 新增：追踪 ID
│   │   │   └── ...
│   │   └── ...
│   └── ...
└── traces                # 新增：所有 trace 的汇总
    ├── "0": {            # Trace 0
    │   ├── trace_id
    │   ├── start_frame
    │   ├── end_frame
    │   ├── duration_frames
    │   ├── duration_seconds
    │   ├── total_appearances
    │   ├── avg_confidence
    │   ├── pose_angles     # Pose 变化序列（简化）
    │   ├── pose_trace      # 新增：完整 Pose 信息
    │   ├── pose_statistics # 新增：Pose 统计
    │   ├── pose_transitions # 新增：Pose 变化事件
    │   └── path            # 详细路径
    ├── "2": { ... }
    └── "3": { ... }
```

---

## 一、frames 中的新增字段

### 1.1 trace_id

**位置**: `frames[frame_num].faces[i].trace_id`

**说明**: 每个人脸新增 `trace_id` 字段，标识该人脸属于哪个追踪轨迹。

**示例**:
```json
{
  "faces": [
    {
      "x": 209,
      "y": 71,
      "width": 70,
      "height": 89,
      "confidence": 0.8778,
      "embedding": [512-dim vector],
      "landmarks": [[x1, y1], ...],
      "pose_angle": {"angle": "profile_right", ...},
      "attributes": {"age": 31, "gender": "male"},
      "trace_id": 2        // 新增字段
    }
  ]
}
```

**用途**:
- 区分视频中不同人物的人脸
- 从特定 trace_id 选择参考向量
- 分析人物在不同帧的连续性

---

## 二、metadata.trace_stats

**位置**: `metadata.trace_stats`

**说明**: 追踪统计摘要。

**结构**:
```json
{
  "total_traces": 4,      // 总共分配的 trace_id 数量
  "active_traces": 4,     // 活跃 trace 数量
  "long_traces": 3        // 长追踪数量（>= 2 帧）
}
```

**示例（preview.mp4）**:
```
Total traces: 4
  - Trace 0: frames 1-146
  - Trace 1: frame 147 (单帧)
  - Trace 2: frames 155-297
  - Trace 3: frames 298-329

Long traces: 3 (Trace 0, 2, 3)
Short trace: 1 (Trace 1, 仅 1 帧)
```

---

## 三、traces 结构

### 3.1 Trace 基础字段

| 字段 | 类型 | 说明 |
|------|------|------|
| **trace_id** | int | 唯一追踪 ID |
| **start_frame** | int | 首次出现帧号 |
| **end_frame** | int | 最后出现帧号 |
| **duration_frames** | int | 持续帧数 |
| **duration_seconds** | float | 持续时间（秒） |
| **total_appearances** | int | 总出现次数 |
| **avg_confidence** | float | 平均检测置信度 |

**示例**:
```json
{
  "trace_id": 2,
  "start_frame": 155,
  "end_frame": 297,
  "duration_frames": 143,
  "duration_seconds": 6.5,
  "total_appearances": 143,
  "avg_confidence": 0.8624
}
```

---

### 3.2 pose_angles（Pose 变化序列 - 简化）

**类型**: `list[string]`

**说明**: 该 trace 所有帧的 pose_angle 字符串序列（简化版本）。

**示例（Trace 2 前 10 帧）**:
```json
{
  "pose_angles": [
    "profile_right",   // frame 155
    "profile_right",   // frame 156
    "profile_right",   // frame 157
    "profile_right",   // frame 158
    "profile_right",   // frame 159
    "profile_right",   // frame 160
    "profile_right",   // frame 161
    "profile_right",   // frame 162
    "profile_right",   // frame 163
    "profile_right",   // frame 164
    ...                // 共 143 个
  ]
}
```

**用途**:
- 快速查看 pose 变化趋势
- 统计 pose distribution

---

### 3.3 pose_trace（完整 Pose 信息）⭐ 新增

**类型**: `list[dict]`

**说明**: 该 trace 每一帧的完整 pose 信息（包含 confidence, pitch, features）。

**结构**:
```json
{
  "pose_trace": [
    {
      "frame": 155,                    // 帧号
      "angle": "profile_right",        // Pose 类型
      "confidence": 0.75,              // Pose 置信度
      "pitch": "neutral",              // Pitch 类型（tilted_up/tilted_down/neutral）
      "features": {                    // Pose 特征（10 个）
        "nose_to_eye_ratio": 0.5924,
        "eye_width": 29.52,
        "nose_to_eye_dist": 17.13,
        "eye_slope": 0.0292,
        "eye_angle_deg": 1.67,
        "nose_offset_x": 5.75,
        "nose_offset_norm": 0.1956,
        "mouth_symmetry": 0.7839,
        "mouth_width": 22.67,
        "jaw_visibility_hint": 1.0
      }
    },
    {
      "frame": 156,
      "angle": "profile_right",
      "confidence": 0.75,
      "pitch": "neutral",
      "features": {...}
    },
    ...                                // 共 143 个
  ]
}
```

**用途**:
- 详细分析 pose confidence 变化
- 分析 pitch 变化（仰视/俯视）
- 提取 pose features 进行深度分析

---

### 3.4 pose_statistics（Pose 统计）⭐ 新增

**类型**: `dict`

**说明**: 该 trace 的 pose 统计信息。

**结构**:
```json
{
  "pose_statistics": {
    "distribution": {                  // Pose 分布
      "profile_right": 125,
      "three_quarter": 18
    },
    "avg_confidence_by_angle": {       // 各 pose 平均置信度
      "profile_right": 0.895,
      "three_quarter": 0.85
    },
    "dominant_angle": "profile_right", // 主导 pose
    "pose_count": 2                    // pose 类型数量
  }
}
```

**示例分析（Trace 2）**:
```
Dominant Angle: profile_right (87%)
Avg Confidence:
  profile_right: 0.895 ✅ (高质量)
  three_quarter: 0.85  ✅ (高质量)
Pose Count: 2 (仅 2 种 pose)
```

**用途**:
- 快速了解 pose 分布
- 评估 pose 稳定性（pose_count 少 = 更稳定）
- 选择高质量 pose 的参考向量

---

### 3.5 pose_transitions（Pose 变化事件）⭐ 新增

**类型**: `list[dict]`

**说明**: 该 trace 中 pose 类型变化的事件列表。

**结构**:
```json
{
  "pose_transitions": [
    {
      "frame": 173,                    // 变化发生的帧号
      "from_angle": "profile_right",   // 原 pose
      "to_angle": "three_quarter",     // 新 pose
      "transition_index": 1            // 变化序号
    },
    {
      "frame": 174,
      "from_angle": "three_quarter",
      "to_angle": "profile_right",
      "transition_index": 2
    },
    ...                                // 共 8 个
  ]
}
```

**示例（Trace 2）**:
```
Frame 173: profile_right → three_quarter
Frame 174: three_quarter → profile_right  (立即恢复)
Frame 177: profile_right → three_quarter
Frame 188: three_quarter → profile_right
...
共 8 个 transitions
```

**用途**:
- 分析 pose 变化时机
- 计算 transition frequency
- 评估 pose stability

---

### 3.6 path（详细路径）

**类型**: `list[dict]`

**说明**: 该 trace 每一帧的详细信息（bbox, confidence, pose_full）。

**结构**:
```json
{
  "path": [
    {
      "frame": 155,                        // 帧号
      "face_index": 0,                     // 人脸索引
      "bbox": {                            // 边界框
        "x": 196,
        "y": 79,
        "width": 64,
        "height": 82
      },
      "confidence": 0.8067,                // 检测置信度
      "pose_angle": "profile_right",       // Pose 类型（简化）
      "pose_full": {...}                   // 完整 pose 信息（新增）
    },
    {
      "frame": 156,
      "face_index": 0,
      "bbox": {"x": 206, "y": 77, "width": 65, "height": 83},
      "confidence": 0.8280,
      "pose_angle": "profile_right",
      "pose_full": {...}
    },
    ...                                    // 共 143 个
  ]
}
```

**用途**:
- 追踪人脸移动轨迹（bbox 变化）
- 分析置信度变化
- 绘制 trace path 可视化

---

## 四、完整示例

### 4.1 Trace 2 完整数据

```json
{
  "2": {
    "trace_id": 2,
    "start_frame": 155,
    "end_frame": 297,
    "duration_frames": 143,
    "duration_seconds": 6.5,
    "total_appearances": 143,
    "avg_confidence": 0.8624,
    "pose_angles": [
      "profile_right", "profile_right", ..., // 125 个 profile_right
      "three_quarter", "three_quarter", ...  // 18 个 three_quarter
    ],
    "path": [
      {"frame": 155, "bbox": {...}, "confidence": 0.8067, "pose_angle": "profile_right"},
      {"frame": 156, "bbox": {...}, "confidence": 0.8280, "pose_angle": "profile_right"},
      ...                                     // 143 个路径点
    ]
  }
}
```

---

### 4.2 Face 数据对比

| 字段 | face.json (无 trace) | face_traced.json (有 trace) |
|------|----------------------|----------------------------|
| **trace_id** | ❌ 无 | ✅ 添加 `trace_id: 2` |
| **pose_angle** | ✅ 有 | ✅ 有（不变） |
| **embedding** | ✅ 有 | ✅ 有（不变） |
| **confidence** | ✅ 有 | ✅ 有（不变） |

**新增字段**: 仅添加 `trace_id`，其他字段不变。

---

## 五、数据用途

### 5.1 Trace 统计分析

| 分析维度 | 数据来源 |
|----------|----------|
| **人物持续时间** | `duration_seconds` |
| **人物置信度** | `avg_confidence` |
| **Pose 分布** | `pose_angles` → 统计 |
| **轨迹移动** | `path` → bbox 变化 |

**示例分析**:
```
Trace 2:
  Duration: 6.5 seconds
  Confidence: 0.862 ✅ (高质量)
  Pose: profile_right (87%), three_quarter (13%)
  Movement: x 196→209, y 79→72 (稳定)
```

---

### 5.2 参考向量选择

**使用 trace_id 过滤**:
```python
# 仅选择 Trace 2 的人脸
for face in faces:
    if face["trace_id"] == 2:
        selected_vectors.append(face["embedding"])
```

**优势**:
- 确保参考向量来自同一人物
- 避免 embedding 混合（不同人物）
- 选择高质量 trace（avg_confidence > 0.85）

---

### 5.3 可视化

**路径可视化** (`face_trace_visualizer.py`):
- X Position vs Frame
- Y Position vs Frame
- Confidence vs Frame
- Pose Distribution

**输出**:
- PNG: `face_trace_visualization.png`
- CSV: `face_trace_stats.csv`

---

## 六、数据大小估算

### 6.1 文件大小

| 内容 | 大小估算 |
|------|----------|
| **embedding (512-dim)** | 512 × 4 bytes = 2 KB per face |
| **landmarks (5 × 2)** | 10 × 8 bytes = 80 bytes per face |
| **path (简化)** | ~100 bytes per path entry |
| **trace (汇总)** | ~200 bytes per trace |

**示例（preview.mp4）**:
```
Frames: 322
Faces per frame: 1
Total faces: 322

face.json size: ~650 KB
face_traced.json size: ~750 KB (+ trace data)
```

---

### 6.2 内存占用

| Trace ID | Path Entries | Pose Angles | 占用 |
|----------|--------------|-------------|------|
| **0** | 146 | 146 | ~30 KB |
| **2** | 143 | 143 | ~30 KB |
| **3** | 32 | 32 | ~7 KB |
| **Total** | 321 | 321 | ~67 KB |

---

## 七、数据完整性检查

### 7.1 Trace Gap 检测

```python
# 检查 trace 之间的 gap
for i in range(len(traces) - 1):
    gap = next_trace.start - curr_trace.end - 1
    if gap > 0:
        print(f"Gap: {gap} frames (无人脸检测)")
```

**示例**:
```
Gap between Trace 1 and 2: 7 frames (frames 148-154)
```

**说明**: frames 148-154 无人脸检测（可能人物离开画面）。

---

### 7.2 Trace Quality 评估

| Trace | Avg Confidence | Quality |
|-------|----------------|---------|
| **0** | 0.76 | ⚠️ 中等 |
| **2** | 0.86 | ✅ 高质量 |
| **3** | 0.69 | ⚠️ 较低 |

**建议**:
- 选择 avg_confidence > 0.85 的 trace
- 过滤 avg_confidence < 0.7 的 trace

---

## 九、Pose Transition Analysis ⭐ 新增

### 9.1 功能说明

**脚本**: `scripts/utils/pose_transition_analyzer.py`

**功能**:
1. 分析 pose 变化频率（transition_frequency）
2. 计算 pose 稳定性分数（stability_score）
3. 识别 pose segments（连续 pose 区段）
4. 可视化 pose timeline

---

### 9.2 Stability Score

**定义**: `stability_score = 1.0 - min(transition_frequency / 2.0, 1.0)`

| Stability Score | 说明 |
|-----------------|------|
| **0.8-1.0** | ✅ 高稳定性（< 0.4 transitions/second） |
| **0.5-0.8** | ⚠️ 中稳定性（0.4-1.0 transitions/second） |
| **0-0.5** | ❌ 低稳定性（> 1.0 transitions/second） |

---

### 9.3 Trace Stability 对比

| Trace | Transitions | Frequency | Stability Score | 评价 |
|-------|-------------|-----------|-----------------|------|
| **0** | 2 | 0.301/s | **0.849** | ✅ 高稳定 |
| **2** | 8 | 1.231/s | **0.385** | ⚠️ 低稳定 |
| **3** | 0 | 0.0/s | **1.0** | ✅ 完全稳定 |

**分析**:
- **Trace 0**: 仅 2 次变化（frame 122, 124），高稳定
- **Trace 2**: 8 次变化，频繁切换 pose，低稳定
- **Trace 3**: 无变化，完全稳定（单一 pose）

---

### 9.4 Pose Segments

**说明**: 将连续相同 pose 的帧合并为一个 segment。

**示例（Trace 2）**:
```
Segment 1: profile_right (frames 155-172, 18 frames, avg_confidence: 0.883)
Segment 2: three_quarter (frames 173-173, 1 frame, avg_confidence: 0.85)   ← 短暂变化
Segment 3: profile_right (frames 174-176, 3 frames, avg_confidence: 0.90)
Segment 4: three_quarter (frames 177-187, 11 frames, avg_confidence: 0.85)
Segment 5: profile_right (frames 188-258, 71 frames, avg_confidence: 0.90) ← 最长稳定
...
共 9 个 segments
```

**用途**:
- 识别最长稳定 pose 区段
- 选择高质量 segment 的参考向量
- 分析 pose 持续时间

---

### 9.5 使用方式

```bash
# 分析 pose transitions
python3 scripts/utils/pose_transition_analyzer.py \
  --face-json video.face_traced.json \
  --output-plot pose_transition_visualization.png \
  --output-json pose_transition_analysis.json
```

---

### 9.6 输出文件

| 文件 | 内容 |
|------|------|
| **PNG** | Pose timeline 可视化（每个 trace 一行） |
| **JSON** | Transition analysis 结果（stability_score, segments, etc.） |

---

## 十、参考文档

| 文件 | 说明 |
|------|------|
| `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` | 使用指南 |

---

## 版本信息

- 版本: 1.0
- 创建日期: 2026-04-28
- 状态: ✅ Face Tracker 记录说明完成
