# Pose-based Identity Matching 优化方案

> 规划日期: 2026-04-28
> 规划版本: V1.0
> 基于实验: Pose-filtered Matching Test

---

## 优化目标

### 核心目标

| 目标 | 当前状态 | 目标状态 |
|------|---------|---------|
| **Match Ratio** | 45.16% (阈值 0.85) | **60%+** |
| **Angle Coverage** | {three_quarter, profile_left, profile_right} | **{frontal, three_quarter, profile_left, profile_right}** |
| **Angle-specific Similarity** | profile_right: 0.08 ❌ | **> 0.85** |
| **自动化程度** | 手动选择参考向量 | **自动多角度注册** |

---

## 问题分析

### 当前实验结果

| Angle | Avg Similarity | Frames | Match Ratio | 问题 |
|-------|----------------|--------|-------------|------|
| **three_quarter** | 0.67 | 27 (87%) | 48% | 主要角度，覆盖良好 |
| **profile_left** | 0.97 ✅ | 3 (10%) | 100% | 参考向量匹配度高 |
| **profile_right** | 0.08 ❌ | 1 (3%) | 0% | **缺少参考向量** |
| **frontal** | - | 0 | - | **未检测到** |

### 问题根因

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| **profile_right 相似度低** | 缺少该角度参考向量 | 自动选择 profile_right 帧注册 |
| **frontal 未检测到** | 视频中没有正面人脸 | 需要补充 frontal 参考向量 |
| **角度分类粗糙** | 仅用 ratio threshold | 增加 landmarks geometry 分析 |
| **手动选择参考向量** | 需人工干预 | 实现自动多角度选择 |

---

## 优化方案设计

### Phase 1: 角度分类算法优化

**目标**: 提高角度分类准确性

**改进点**:
- 当前: 仅用 `nose_to_eye / eye_width` ratio
- 改进: 增加 landmarks geometry 特征

**具体改进**:

| 特征 | 当前 | 新增 |
|------|------|------|
| **Ratio** | ✅ | 保持 |
| **Eye Slope** | ❌ | 眼睛连线斜率（判断仰视/俯视） |
| **Nose Position** | ❌ | 鼻子相对眼睛中心的偏移 |
| **Mouth Symmetry** | ❌ | 嘴角对称性（判断侧脸） |
| **3D Landmarks** | ❌ | 使用 3D_68 landmarks（如有） |

**实施任务**:
1. 实现 `calculate_pose_angle_v2()` 函数
2. 添加多特征综合评分
3. 输出更精确的 angle 分类

---

### Phase 2: 自动多角度参考向量选择

**目标**: 自动选择覆盖所有角度的参考向量

**算法设计**:

```
输入: face.json (所有帧人脸)
输出: 4-10 个高质量参考向量（覆盖所有角度）

步骤:
1. 计算每帧人脸的 pose angle
2. 按 angle 分组
3. 每组按 quality_score 排序
4. 每组选择 Top 1-2 个
5. 总数限制 10 个
```

**角度覆盖策略**:

| Angle | 目标数量 | 选择策略 |
|-------|---------|---------|
| **frontal** | 1-2 | ratio < 0.4, quality > 0.85 |
| **three_quarter** | 2-3 | ratio 0.4-0.6, quality > 0.80 |
| **profile_left** | 1-2 | nose left of center, quality > 0.75 |
| **profile_right** | 1-2 | nose right of center, quality > 0.75 |

**实施任务**:
1. 改进 `select_face_reference_vectors.py`
2. 实现自动角度分组
3. 确保最少 4 个角度覆盖
4. 生成 angle_coverage_report

---

### Phase 3: Identity 注册优化

**目标**: 注册时自动存储 pose angle

**当前问题**: reference_data 中 angle 多为 "unknown"

**改进**:
- 计算 pose angle 并存储到 reference_data
- 存储 pose_ratio 供后续过滤使用

**reference_data 结构优化**:

```json
{
  "face_embeddings": [
    {
      "embedding": [512-dim],
      "angle": "three_quarter",
      "pose_ratio": 0.542,
      "eye_slope": 0.12,
      "nose_offset": -5.3,
      "quality_score": 0.92,
      "source": "video_detection",
      "frame": "210",
      "created_at": "2026-04-28T..."
    }
  ],
  "angle_coverage": {
    "frontal": 2,
    "three_quarter": 3,
    "profile_left": 1,
    "profile_right": 1
  },
  "best_angle": "three_quarter",
  "total_references": 7
}
```

**实施任务**:
1. 更新 reference_data JSON schema
2. 注册时计算 pose features
3. 生成 angle_coverage 统计

---

### Phase 4: Pose-filtered Matching 优化

**目标**: 改进匹配策略

**当前问题**:
- 找不到同角度向量时，fallback 不够智能
- 阈值固定，未考虑角度差异

**改进策略**:

| 场景 | 当前策略 | 改进策略 |
|------|---------|---------|
| **有同角度向量** | 使用同角度 | 保持 ✅ |
| **无同角度向量** | 使用 three_quarter | **使用 closest angle** |
| **阈值固定** | 0.85 | **角度自适应阈值** |

**角度自适应阈值**:

| Angle | Threshold | 说明 |
|-------|-----------|------|
| **frontal** | 0.90 | 最高质量 |
| **three_quarter** | 0.85 | 标准 |
| **profile_left/right** | 0.80 | 更宽容（角度差异大） |

**Closest Angle Fallback**:

```python
angle_similarity = {
    'frontal': {'frontal': 1.0, 'three_quarter': 0.8, 'profile': 0.5},
    'three_quarter': {'frontal': 0.8, 'three_quarter': 1.0, 'profile': 0.7},
    'profile': {'frontal': 0.5, 'three_quarter': 0.7, 'profile': 1.0},
}

# Fallback order
if detected_angle == 'profile_right':
    fallback_order = ['profile_right', 'profile_left', 'three_quarter', 'frontal']
```

**实施任务**:
1. 实现 `strategy_pose_filtered_v2()`
2. 添加角度自适应阈值
3. 实现 closest angle fallback
4. 添加 angle_similarity 矩阵

---

### Phase 5: 生产流程整合

**目标**: 整合到 Momentry Core 生产流程

**整合点**:

| 流程 | 整合内容 |
|------|---------|
| **Face Processor** | 输出 pose angle 到 face.json |
| **Identity Registration API** | 自动多角度参考向量选择 |
| **Identity Matching API** | Pose-filtered matching |
| **Portal UI** | 显示 angle_coverage |

**API 设计**:

```
POST /api/v1/identities/:id/register-reference-vectors
Body: {
  "file_uuid": "xxx",
  "face_json_path": "output/xxx.face.json",
  "auto_select": true,
  "min_angles": 4,
  "max_vectors": 10
}

Response: {
  "uuid": "xxx",
  "reference_count": 7,
  "angle_coverage": {...},
  "quality_avg": 0.89
}
```

---

## 实施计划

### 阶段划分

| Phase | 任务 | 优先级 | 预计时间 |
|-------|------|--------|---------|
| **Phase 1** | 角度分类算法优化 | 高 | 1天 |
| **Phase 2** | 自动多角度参考向量选择 | 高 | 1天 |
| **Phase 3** | Identity 注册优化 | 中 | 0.5天 |
| **Phase 4** | Pose-filtered Matching 优化 | 中 | 1天 |
| **Phase 5** | 生产流程整合 | 低 | 2天 |

**总计**: 5.5天

---

### Phase 1 详细任务

| 任务 | 说明 | 文件 |
|------|------|------|
| Task 1.1 | 实现 `calculate_pose_angle_v2()` | `scripts/utils/pose_analyzer.py` |
| Task 1.2 | 添加多特征计算 | 同上 |
| Task 1.3 | 单元测试 | `tests/test_pose_analyzer.py` |
| Task 1.4 | 验证角度分类准确性 | 测试脚本 |

**验证指标**:
- Angle 分类准确率 > 90%
- 特征计算速度 < 0.01s/face

---

### Phase 2 详细任务

| 任务 | 说明 | 文件 |
|------|------|------|
| Task 2.1 | 实现角度分组算法 | `scripts/select_face_reference_vectors_v2.py` |
| Task 2.2 | 实现每角度 Top-K 选择 | 同上 |
| Task 2.3 | 确保最少角度覆盖 | 同上 |
| Task 2.4 | 生成 angle_coverage_report | 同上 |
| Task 2.5 | 批量测试（多个视频） | 测试脚本 |

**验证指标**:
- Angle 覆盖 ≥ 4
- 参考向量数量 4-10
- 质量 avg > 0.85

---

### Phase 3 详细任务

| 任务 | 说明 | 文件 |
|------|------|------|
| Task 3.1 | 更新 reference_data schema | 设计文档 |
| Task 3.2 | 注册脚本集成 pose features | `scripts/register_identity_with_pose.py` |
| Task 3.3 | 数据库测试 | 测试脚本 |

**验证指标**:
- reference_data 包含 pose features ✅
- angle_coverage 统计准确 ✅

---

### Phase 4 详细任务

| 任务 | 说明 | 文件 |
|------|------|------|
| Task 4.1 | 实现 `strategy_pose_filtered_v2()` | `scripts/match_face_with_pose_v2.py` |
| Task 4.2 | 实现角度自适应阈值 | 同上 |
| Task 4.3 | 实现 closest angle fallback | 同上 |
| Task 4.4 | 批量测试对比 | 测试脚本 |

**验证指标**:
- Match Ratio > 60% (阈值 0.85)
- profile_right 相似度 > 0.85
- Fallback 有效

---

### Phase 5 详细任务

| 任务 | 说明 | 文件 |
|------|------|------|
| Task 5.1 | Face Processor 输出 pose angle | `scripts/face_processor.py` |
| Task 5.2 | Identity Registration API | `src/api/identity.rs` |
| Task 5.3 | Identity Matching API | 同上 |
| Task 5.4 | Portal UI 组件 | Vue components |
| Task 5.5 | 整合测试 | E2E 测试 |

**验证指标**:
- API 响应正常 ✅
- UI 显示 angle_coverage ✅
- E2E 流程成功 ✅

---

## 预期成果

### 定量指标

| 指标 | 当前 | Phase 4后 | Phase 5后 |
|------|------|----------|----------|
| **Match Ratio (阈值 0.85)** | 45.16% | **60%+** | 65%+ |
| **Angle Coverage** | 2-3 | **4+** | 4+ |
| **profile_right Similarity** | 0.08 | **0.85+** | 0.85+ |
| **自动化程度** | 手动 | 半自动 | **全自动** |

### 定性改进

| 改进 | 说明 |
|------|------|
| **鲁棒性** | 多角度覆盖，减少角度差异影响 |
| **准确性** | 角度分类更精确，匹配更可靠 |
| **自动化** | 从手动选择到自动注册 |
| **可追溯** | pose features 存储可追溯 |

---

## 验证方案

### 单元测试

| 测试 | 说明 |
|------|------|
| `test_pose_analyzer` | 角度分类准确性 |
| `test_reference_selector_v2` | 多角度选择逻辑 |
| `test_pose_filtered_matching_v2` | 匹配策略有效性 |

### 集成测试

| 测试 | 说明 |
|------|------|
| `test_identity_registration_with_pose` | 注册流程 |
| `test_batch_matching` | 批量匹配效果 |
| `test_angle_coverage` | 角度覆盖验证 |

### E2E 测试

| 测试 | 说明 |
|------|------|
| `test_full_pipeline` | 从 Face Processor 到 Matching |
| `test_api_integration` | API 端到端 |

---

## 风险与缓解

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| **缺少 frontal 帧** | frontal 角度无参考向量 | 使用 closest angle fallback |
| **角度分类错误** | 匹配失败 | 多特征综合评分 |
| **计算成本增加** | 性能下降 | 预计算 pose features |
| **阈值设置不当** | 匹配率波动 | 角度自适应阈值 |

---

## 版本信息

- 规划版本: V1.0
- 规划日期: 2026-04-28
- 规划状态: ✅ 完成
- 下一步: **Phase 1 实施**
