warren/momentry_core
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

cleanup: remove dead code and duplicate docs

Browse Source 
- Remove session-ses_2f27.md (161KB raw session log)
- Remove 49 ROOT_* duplicate files across REFERENCE/
- Remove 14 duplicate files between REFERENCE/ root and history/
- Remove asr_legacy.rs (dead code, replaced by asr.rs)
- Remove src/core/worker/ (duplicate JobWorker)
- Remove src/core/layers/ (empty directory)
- Remove 4 .bak files in src/
- Remove 7 dead private methods in worker/processor.rs
- Remove backup directory from git tracking
This commit is contained in:
Warren
2026-05-04 01:31:21 +08:00
parent ee81e343ce
commit e75c4d6f07
3270 changed files with 35190 additions and 53367 deletions
Download Patch File Download Diff File Expand all files Collapse all files

196
docs_v1.0/EXPERIMENT_REPORTS/FACE_PROCESSOR_PERFORMANCE_2026-04-28.md
View File

@@ -1,196 +0,0 @@
# Face Processor 性能评估报告
> 测试日期: 2026-04-28
> 测试视频: preview.mp4 (15秒, 329帧)
> 测试版本: face_processor.py (InsightFace REQUIRED)
---
## 测试环境
| 配置 | 值 |
|------|-----|
| **视频文件** | preview.mp4 |
| **视频时长** | 15秒 |
| **总帧数** | 329 |
| **FPS** | 22 |
| **分辨率** | 640x360 |
| **采样间隔** | 10 (每10帧检测一次) |
---
## 对比测试: OLD vs NEW
### OLD (Haar Cascade fallback)
| 指标 | 结果 |
|------|------|
| **Frames 处理** | 8 |
| **Faces 检测** | 8 |
| **Embeddings** | 0 ❌ |
| **Embedding dim** | NULL |
| **Attributes** | NULL |
| **Detection method** | haar_cascade |
**问题**: Haar Cascade 无法生成 embedding，导致全链路失败。
### NEW (InsightFace REQUIRED)
| 指标 | 结果 |
|------|------|
| **Frames 处理** | 31 |
| **Faces 检测** | 31 |
| **Embeddings** | 31 ✅ |
| **Embedding dim** | 512 ✅ |
| **Attributes** | {age, gender} ✅ |
| **Detection method** | insightface |
**改进**: 所有检测的人脸都成功生成 512-dim embedding。
---
## Embedding 质量分析
### Embedding 统计
| 指标 | 结果 | 说明 |
|------|------|------|
| **Embeddings 提取** | 31 | ✅ 全部成功 |
| **Embedding 维度** | 512 | ✅ ArcFace |
| **Embedding norms** | 23.18 (avg) | 未归一化 |
| **Norms std** | 1.01 | 标准差小，质量稳定 |
### Intra-person Similarity (同人脸相似度)
| 指标 | 结果 | 说明 |
|------|------|------|
| **平均相似度** | 0.7764 | ✅ 正常（阈值: 0.85） |
| **最小相似度** | 0.0902 | ⚠️ 过低（可能角度变化） |
| **最大相似度** | 0.9960 | ✅ 很高 |
| **相似度范围** | 0.09 - 0.99 | ⚠️ 波动大 |
### 问题分析
⚠️ **相似度波动大 (0.09 - 0.99)**
**原因**:
1. 人脸角度变化（正面 vs 侧面）
2. 人脸表情变化
3. 光线变化
4. 人脸大小变化
**解决方案**: **1对多参考向量架构**
- 同一 Identity 存储多个 embedding（不同角度）
- 使用投票机制 + 加权平均匹配
- 提高识别鲁棒性
---
## Attributes 检测质量
### 年龄检测
| Frame | Age | Confidence |
|-------|-----|------------|
| 10 | 37 | 0.81 |
| 20 | 36 | 0.81 |
| 30 | 39 | 0.82 |
| 40 | 36 | 0.84 |
| 50 | 43 | 0.85 |
**分析**: 年龄波动 36-43，平均约 38岁。
### 性别检测
| Frame | Gender | Confidence |
|-------|--------|------------|
| All | male | 0.81-0.85 |
**分析**: 性别一致，检测稳定。
---
## 性能指标
### 处理速度
| 指标 | 结果 |
|------|------|
| **视频时长** | 15秒 |
| **处理帧数** | 31 |
| **采样间隔** | 10 |
| **InsightFace 模型** | buffalo_l (5个模型) |
**模型加载**:
- `det_10g.onnx` - 人脸检测
- `w600k_r50.onnx` - Recognition (512-dim)
- `genderage.onnx` - 年龄/性别
- `landmark_3d_68.onnx` - 3D关键点
- `landmark_2d_106.onnx` - 2D关键点
---
## 关键改进总结
| 改进项 | OLD (Haar) | NEW (InsightFace) |
|--------|-----------|------------------|
| **Embeddings** | 0 | 31 ✅ |
| **Embedding dim** | NULL | 512 ✅ |
| **Attributes** | NULL | {age, gender} ✅ |
| **Landmarks** | NULL | 3D + 2D ✅ |
| **Recognition** | ❌ | ✅ |
| **Identity Matching** | ❌ | ✅ |
---
## 下一步建议
### 1. 归一化 Embedding
```python
# 当前 norms = 23.18，建议归一化到 1.0
embedding_normalized = embedding / np.linalg.norm(embedding)
```
### 2. 1对多参考向量
```json
{
"face_embeddings": [
{"embedding": [...], "angle": "frontal", "quality": 0.95},
{"embedding": [...], "angle": "profile_left", "quality": 0.88},
{"embedding": [...], "angle": "three_quarter", "quality": 0.92}
]
}
```
### 3. 匹配算法优化
- **投票机制**: 统计超过阈值的参考向量数量
- **加权平均**: 根据质量评分加权计算相似度
- **综合评分**: 50% 最佳匹配 + 30% 投票 + 20% 加权
---
## 结论
✅ **Face Processor 修复成功**
- 所有检测的人脸都成功生成 512-dim embedding
- 年龄/性别检测正常
- 嵌入质量稳定
⚠️ **需要改进**
- Embedding 需要归一化
- 相似度波动大，需要 1对多参考向量架构
- 建议实现投票机制匹配算法
---
## 版本信息
- 测试版本: V1.0
- 测试日期: 2026-04-28
- 测试状态: ✅ 成功

206
docs_v1.0/EXPERIMENT_REPORTS/FACE_TRACKER_INTEGRATION_REPORT_2026-04-28.md
View File

@@ -1,206 +0,0 @@
# 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 报告

204
docs_v1.0/EXPERIMENT_REPORTS/IDENTITY_SYSTEM_EXPERIMENT_2026-04-28.md
View File

@@ -1,204 +0,0 @@
# Identity 系统实验报告
> 实验日期: 2026-04-28
> 实验版本: V1.0
> 实验对象: Accusys Storage Logo
---
## 实验概述
本实验验证 Momentry Core Identity 系统的完整流程，包括：
1. **数据库架构重构**: identities 表扩展（identity_embedding, reference_data JSONB）
2. **人脸处理系统重构**: face_processor.py 强制 InsightFace + Rust Face Struct 添加 embedding
3. **TMDB 整合**: 多角度人脸下载 + ArcFace embedding + Identity 注册
4. **CLIP Logo Identity**: CLIP ViT-L/14 embedding 提取 + Logo Identity 注册
---
## 实验结果
### Phase 0: 文档存档更新
| 文档 | 操作 | 状态 |
|------|------|------|
| `MOMENTRY_CORE_ARCHITECTURE_V2.md` | 更新 identities 表结构 | ✅ 完成 |
| `FILE_IDENTITY_API_DESIGN.md` | 更新 reference_data JSONB 结构 | ✅ 完成 |
| `IDENTITY_REFERENCE_VECTOR_DESIGN.md` | 新建：1对多参考向量设计 | ✅ 完成 |
| `CLIP_EMBEDDING_BENCHMARK_PLAN.md` | 新建：CLIP 测试计划 | ✅ 完成 |
| `SOUND_RECOGNITION_EXTENSION.md` | 新建：声音识别扩展设计 | ✅ 完成 |
---
### Phase 1: 数据库架构重构
| Migration | 操作 | 状态 |
|-----------|------|------|
| Migration 023 | identities 表扩展 | ✅ 完成 |
| Migration 024 | face_embedding 维度修复 (768→512) | ✅ 完成 |
**identities 表最终结构**:
| 字段 | 类型 | 说明 |
|------|------|------|
| uuid | UUID | 唯一标识 |
| name | VARCHAR(255) | 名称 |
| identity_type | VARCHAR(30) | 类型 (CHECK constraint: people, logo, symbol, sound, animal, environmental) |
| source | VARCHAR(20) | 来源 (manual, tmdb, ai_detection) |
| status | VARCHAR(20) | 状态 (pending, confirmed, skipped) |
| **face_embedding** | VECTOR(512) | InsightFace ArcFace (512-dim) |
| **voice_embedding** | VECTOR(192) | ECAPA-TDNN (192-dim) |
| **identity_embedding** | VECTOR(768) | CLIP ViT-L/14 (768-dim) |
| **reference_data** | JSONB | 1对多参考向量存储 |
| tmdb_id | INTEGER | TMDB ID |
| tmdb_profile | TEXT | TMDB profile URL |
---
### Phase 2: 人脸处理系统重构
#### Phase 2.1: face_processor.py 修改
| 修改 | 说明 |
|------|------|
| 移除 Haar Cascade fallback | Haar 无法生成 embedding，导致全链路失败 |
| 强制 InsightFace | 确保 **所有检测的 Face 都有 embedding** |
#### Phase 2.2: Rust Face Struct 修改
| 新增字段 | 类型 | 说明 |
|----------|------|------|
| embedding | Option<Vec<f32>> | 512-dim ArcFace embedding |
| landmarks | Option<Vec<Vec<f32>>> | 关键点坐标 |
| attributes | Option<FaceAttributes> | 年龄、性别 |
**测试结果**: 8 个 Rust 测试全部通过 ✅
#### Phase 2.3: TMDB Identity Integration 脚本
| 功能 | 说明 |
|------|------|
| TMDB /person/:id/images API | 下载多张人脸照片（不同角度） |
| ArcFace embedding 提取 | 提取 512-dim embedding |
| reference_data JSONB 存储 | 存储多个 embedding（1对多） |
| Centroid 计算 | 计算中心向量 |
**Database Integration Test**: 5 个测试全部通过 ✅
---
### Phase 3: CLIP Logo Identity 测试
#### 测试对象
| 属性 | 值 |
|------|-----|
| Logo 名称 | Accusys Storage Logo |
| Logo URL | https://www.accusys.com.tw/wp-content/uploads/2023/03/Accusys-Orange-2017.png |
| Logo 尺寸 | 3269x747px |
| 品牌色 | Orange (#EE7632) |
#### 性能基准测试
| 指标 | MPS | CPU | Speedup |
|------|-----|-----|---------|
| **提取速度** | 0.0338s/img | 0.2211s/img | **6.54x** |
| **10 iterations** | 0.338s | 2.211s | |
#### Embedding 提取
| 指标 | 结果 |
|------|------|
| **Embedding 维度** | 768-dim ✅ |
| **模型** | CLIP ViT-L/14 |
| **设备** | MPS (Apple Silicon) |
#### Identity 注册
| 指标 | 值 |
|------|-----|
| **UUID** | 23050c3e-6bea-4b8e-a916-2aaff0024bc2 |
| **identity_type** | logo |
| **status** | confirmed |
| **identity_embedding** | ✅ 存储 768-dim VECTOR |
| **reference_data** | ✅ 存储 JSONB |
#### Similarity Search 测试
| Test | Similarity | Match |
|------|-----------|-------|
| **Test 1** (自己) | 1.0000 | ✅ True |
| **Test 2** (随机) | -0.0298 | ❌ False |
---
## 创建的脚本
| 脚本 | 路径 | 说明 |
|------|------|------|
| TMDB Integration | `scripts/tmdb_identity_integration.py` | TMDB 多角度人脸 + ArcFace + Identity 注册 |
| CLIP Logo Integration | `scripts/clip_logo_integration.py` | CLIP embedding + Logo Identity 注册 |
| DB Test | `scripts/test_identity_db.py` | identities 表结构验证 |
---
## 创建的 Migration
| Migration | 文件路径 |
|-----------|----------|
| Migration 023 | `migrations/023_extend_identities_embeddings.sql` |
| Migration 024 | `migrations/024_fix_face_embedding_dim.sql` |
---
## 关键发现
### 1. Haar Cascade 是"破坏者"
**问题**: Haar Cascade 只能检测人脸，无法生成 embedding。
**后果**: 当 InsightFace 失败时，系统 fallback 到 Haar，导致 embedding=null → 全链路失败。
**解决方案**: 移除 Haar fallback，强制使用 InsightFace。
### 2. Rust Face Struct 缺失 embedding 字段
**问题**: Python 输出的 embedding 在 Rust 解析时被丢弃。
**解决方案**: Face Struct 添加 `embedding: Option<Vec<f32>>` 字段。
### 3. MPS 性能提升 6.54x
**测试结果**: CLIP ViT-L/14 在 MPS 模式下比 CPU 快 6.54 倍。
**建议**: Logo/Symbol/Object Identity 系统优先使用 MPS。
### 4. 1对多参考向量架构验证成功
**设计**: 同一 Identity 可存储多个 embedding（不同角度/场景/版本）。
**验证**: reference_data JSONB 存储成功。
---
## 下一步计划
### Phase 5+: 声音识别扩展
| 类型 | 说明 |
|------|------|
| animal | 动物叫声（狗叫声、猫叫声、鸟叫声） |
| environmental | 环境音（雷声、雨声、风声） |
| weapon | 武器声（枪声、爆炸声、警报声） |
| musical | 乐器声（吉他、钢琴、鼓） |
**设计文档**: `docs_v1.0/ARCHITECTURE/SOUND_RECOGNITION_EXTENSION.md`
---
## 版本信息
- 实验版本: V1.0
- 实验日期: 2026-04-28
- 实验状态: ✅ 全部成功

309
docs_v1.0/EXPERIMENT_REPORTS/LANDMARKS_SOURCE_ANALYSIS_2026-04-28.md
View File

@@ -1,309 +0,0 @@
# Landmarks 来源分析报告
> 分析日期: 2026-04-28
> 分析目标: face.json 中的 landmarks 字段
---
## 概述
`face.json` 中的 `landmarks` 字段用于 **Pose-based Identity Matching**。本报告分析：
1. **Landmarks 来源**: InsightFace buffalo_l 模型
2. **数据结构**: 5-point keypoints (kps)
3. **可靠性评估**: 模型精度 vs 实际测试
---
## 1. 数据流程
### 1.1 InsightFace buffalo_l 模型链
```
det_10g.onnx (RetinaFace) → Face detection + kps (5-point)
↓
1k3d68.onnx (Landmark3D) → landmark_3d_68 (68-point 3D)
↓
2d106det.onnx (Landmark2D) → landmark_2d_106 (106-point 2D)
↓
w600k_r50.onnx (ArcFace) → embedding (512-dim)
↓
genderage.onnx (Attribute) → age, gender
```
### 1.2 kps (5-point) 来源
**关键发现**: `kps` 来自 **RetinaFace 检测器**，而非 landmark_3d_68。
**代码路径**:
```
FaceAnalysis.get() → det_model.detect() → bboxes, kpss
→ Face(bbox, kps=kpss[i], det_score)
```
**文件**: `/opt/homebrew/lib/python3.11/site-packages/insightface/app/face_analysis.py:83-96`
```python
def get(self, img, max_num=0):
bboxes, kpss = self.det_model.detect(img, max_num=max_num, metric='default')
if bboxes.shape[0] == 0:
return []
ret = []
for i in range(bboxes.shape[0]):
bbox = bboxes[i, 0:4]
det_score = bboxes[i, 4]
kps = None
if kpss is not None:
kps = kpss[i]
face = Face(bbox=bbox, kps=kps, det_score=det_score)
for taskname, model in self.models.items():
if taskname=='detection':
continue
model.get(img, face)
ret.append(face)
return ret
```
---
## 2. kps 结构分析
### 2.1 数据格式
```json
{
"landmarks": [
[236.50, 106.82], // 0: left eye
[266.01, 107.21], // 1: right eye
[256.68, 123.23], // 2: nose
[241.10, 139.31], // 3: left mouth corner
[263.37, 139.54] // 4: right mouth corner
]
}
```
**维度**: `(5, 2)` - 5 个点，每个点 2D 坐标 (x, y)
### 2.2 点定义
| Index | Point | 说明 |
|-------|-------|------|
| 0 | left_eye | 左眼中心 |
| 1 | right_eye | 右眼中心 |
| 2 | nose | 鼻尖 |
| 3 | left_mouth | 左嘴角 |
| 4 | right_mouth | 右嘴角 |
---
## 3. kps vs landmark_3d_68 对比
### 3.1 理论来源
| Feature | kps | landmark_3d_68 |
|---------|-----|----------------|
| **来源模型** | RetinaFace (det_10g.onnx) | Landmark3D (1k3d68.onnx) |
| **点数** | 5 | 68 |
| **维度** | 2D (x, y) | 3D (x, y, z) |
| **用途** | Face alignment | Detailed geometry |
| **计算顺序** | Detection phase | Post-detection |
### 3.2 实际对比测试
**测试帧**: Frame 210 (preview.mp4)
```
=== kps from RetinaFace ===
left_eye: [236.45, 106.68]
right_eye: [265.98, 107.18]
nose: [256.51, 123.42]
left_mouth: [240.99, 139.40]
right_mouth: [263.23, 139.72]
=== landmark_3d_68 from Landmark3D ===
Eye centroids (36-41, 42-48):
left_eye centroid: [236.52, 107.16] diff: 0.49 pixel
right_eye centroid: [264.90, 107.68] diff: 1.19 pixel
Single points:
nose (30): [255.90, 119.21] diff: 4.25 pixel ⚠️
left_mouth (48): [241.40, 139.31] diff: 0.42 pixel
right_mouth (54): [263.42, 140.20] diff: 0.51 pixel
```
**关键发现**:
- **眼睛**: kps 与 landmark_3d_68 centroid 差异 < 1 pixel ✅
- **鼻子**: kps 与 landmark_3d_68 差异 4.25 pixel ⚠️
- **嘴角**: kps 与 landmark_3d_68 差异 < 1 pixel ✅
### 3.3 差异原因分析
**RetinaFace kps**:
- 在 detection phase 计算
- 使用 `distance2kps()` 函数从 anchor centers 解码
- 基于检测网络的回归输出
**Landmark3D landmark_3d_68**:
- 在 post-detection phase 计算
- 使用专门的 landmark 模型
- 更精细的面部几何
**差异原因**:
1. **不同模型**: RetinaFace vs Landmark3D
2. **不同精度**: kps 用于快速 alignment，landmark_3d_68 用于精细 alignment
3. **鼻子的特殊性**: RetinaFace kps 可能预测鼻尖位置不准确（4.25 pixel）
---
## 4. 可靠性评估
### 4.1 RetinaFace kps 可靠性
| 场景 | 可靠性 | 说明 |
|------|--------|------|
| **正面人脸** | ✅ 高 | det_score > 0.8，kps 精确 |
| **侧面人脸** | ✅ 高 | det_score > 0.8，kps 仍可靠 |
| **小脸检测** | ⚠️ 中 | det_size=320，小脸可能降低精度 |
| **低质量图像** | ⚠️ 中 | blur, low resolution 降低精度 |
### 4.2 Pose Analyzer 使用 kps 的可靠性
**计算特征**:
- `nose_to_eye_ratio`: nose 到 eye center 的距离比例
- `eye_slope`: 眼睛连线斜率（pitch detection）
- `nose_offset`: nose 相对 eye center 的偏移
- `mouth_symmetry`: 嘴角对称性
**可靠性分析**:
| Feature | 依赖点 | 可靠性 | 说明 |
|---------|--------|--------|------|
| nose_to_eye_ratio | nose (2), eyes (0,1) | ⚠️ 中 | nose 位置差异 4.25 pixel |
| eye_slope | eyes (0,1) | ✅ 高 | eyes 精确 (< 1 pixel) |
| nose_offset | nose (2), eye center | ⚠️ 中 | nose 位置差异 |
| mouth_symmetry | mouth corners (3,4) | ✅ 高 | mouth 精确 (< 1 pixel) |
**整体评估**: ✅ **可靠合理**
原因:
1. **多特征综合**: 使用 5 个特征，单一特征误差不影响整体
2. **眼睛主导**: eye_slope 和 eye center 最精确
3. **confidence score**: Pose Analyzer 输出 confidence，低 confidence 可过滤
4. **实际测试**: 31帧人脸，confidence avg = 0.87 ✅
---
## 5. 改进建议
### 5.1 短期改进
| 改进 | 说明 | 优先级 |
|------|------|--------|
| **使用 landmark_3d_68** | 替代 kps，更精确 | 高 |
| **鼻子点校准** | 使用 landmark_3d_68[30] 替代 kps[2] | 中 |
| **confidence threshold** | 添加 confidence 过滤（< 0.75 reject） | 低 |
### 5.2 实施方案
**方案 A: 使用 landmark_3d_68**
修改 `face_processor.py`:
```python
# Before
if hasattr(face, 'kps'):
landmarks = face.kps.tolist()
elif hasattr(face, 'landmark_3d_68'):
landmarks = face.landmark_3d_68.tolist()
# After (推荐)
if hasattr(face, 'landmark_3d_68'):
# Extract 5-point from landmark_3d_68
lm3d = face.landmark_3d_68
landmarks = [
np.mean(lm3d[36:42][:, :2], axis=0).tolist(), # left eye centroid
np.mean(lm3d[42:48][:, :2], axis=0).tolist(), # right eye centroid
lm3d[30][:2].tolist(), # nose tip
lm3d[48][:2].tolist(), # left mouth
lm3d[54][:2].tolist(), # right mouth
]
elif hasattr(face, 'kps'):
landmarks = face.kps.tolist() # Fallback
```
**预期效果**:
- nose 位置精度提升 (4.25 → 0 pixel)
- confidence 提升 (0.87 → 0.90+)
---
## 6. 结论
### 6.1 Landmarks 来源总结
| 问题 | 回答 |
|------|------|
| **来源模型** | RetinaFace (det_10g.onnx) - detection phase |
| **数据结构** | 5-point 2D keypoints (left_eye, right_eye, nose, left_mouth, right_mouth) |
| **精度** | eyes/mouth: < 1 pixel ✅, nose: ~4 pixel ⚠️ |
| **是否可靠** | ✅ **可靠合理** - 多特征综合降低单一误差影响 |
### 6.2 推荐行动
| 优先级 | 行动 |
|--------|------|
| **高** | 使用 landmark_3d_68 替代 kps |
| **中** | 测试改进后的 pose confidence |
| **低** | 添加 confidence threshold 过滤 |
---
## 7. 参考文档
- [InsightFace GitHub](https://github.com/deepinsight/insightface)
- [RetinaFace Paper](https://arxiv.org/abs/1905.00641)
- [buffalo_l Models](https://github.com/deepinsight/insightface/tree/master/model_zoo)
- `pose_analyzer.py`: 多特征 Pose 分类
- `face_processor.py`: Face detection + Pose 输出
---
## 附录: 实测数据
### Frame 210 (preview.mp4)
```json
{
"landmarks": [
[236.50, 106.82],
[266.01, 107.21],
[256.68, 123.23],
[241.10, 139.31],
[263.37, 139.54]
],
"pose_angle": {
"angle": "profile_right",
"confidence": 0.9,
"pitch": "neutral",
"features": {
"nose_to_eye_ratio": 0.5793,
"eye_width": 29.52,
"eye_slope": 0.0134,
"nose_offset_x": 5.42,
"mouth_symmetry": 0.7874
}
}
}
```
### 31帧统计
```
Total faces: 31
Pose distribution: {
three_quarter: 17 (55%),
profile_right: 11 (35%),
profile_left: 3 (10%)
}
Confidence avg: 0.87 ✅
```

184
docs_v1.0/EXPERIMENT_REPORTS/ONE_TO_MANY_MATCHING_OPTIMIZATION_2026-04-28.md
View File

@@ -1,184 +0,0 @@
# 1对多参考向量架构优化报告
> 测试日期: 2026-04-28
> 测试版本: V1.0
> 测试对象: Preview Test Person Identity
---
## 实验概述
本实验验证 **1对多参考向量架构** 的匹配效果，对比不同策略和阈值：
1. **Combined 策略权重优化**: 从 {0.5, 0.3, 0.2} → {0.7, 0.2, 0.1}
2. **阈值对比测试**: 0.85, 0.80, 0.75
3. **策略对比**: Best Match vs Combined
---
## 测试环境
| 配置 | 值 |
|------|-----|
| **Identity UUID** | 5ae2a1a2-0cd6-4007-971d-12b8e04be9be |
| **Identity Name** | Preview Test Person |
| **Reference Vectors** | 6 个 (质量 0.85-0.94) |
| **Angles Covered** | {unknown, profile_right} |
| **Faces to Match** | 31 (from preview.mp4) |
---
## 权重优化对比
### 原始权重 (V1)
```
final_score = best_match * 0.5 + vote_ratio * 0.3 + weighted_sim * 0.2
```
| 阈值 | Match Ratio |
|------|-------------|
| 0.85 | 0% ❌ |
| 0.80 | - |
| 0.75 | - |
**问题**: vote_ratio 和 weighted_sim 拉低了 final_score。
---
### 优化权重 (V2)
```
final_score = best_match * 0.7 + vote_ratio * 0.2 + weighted_sim * 0.1
```
| 阈值 | Match Ratio | 说明 |
|------|-------------|------|
| **0.85** | 9.68% (3/31) | 高精度 |
| **0.80** | 35.48% (11/31) | 平衡 |
| **0.75** | **45.16% (14/31)** ✅ | 接近 Best Match |
**改进**: 优化权重后，阈值 0.75 时 Match Ratio 达到 45.16%，接近 Best Match (48.39%)。
---
## 策略对比
| 策略 | 阈值 | Match Ratio | Final Score Range |
|------|------|-------------|------------------|
| **Best Match** | 0.85 | 48.39% (15/31) ✅ | 0.30 - 1.00 |
| **Combined (V2)** | 0.75 | 45.16% (14/31) ✅ | 0.24 - 0.94 |
| **Combined (V1)** | 0.85 | 0% ❌ | - |
---
## 详细分析
### Best Match 策略特点
| 特点 | 说明 |
|------|------|
| **优势** | 简单快速，Match Ratio 最高 |
| **劣势** | 单一参考向量匹配，鲁棒性低 |
| **适用场景** | 高质量参考向量 + 正面人脸 |
### Combined 策略特点
| 特点 | 说明 |
|------|------|
| **优势** | 多参考向量投票，鲁棒性高 |
| **劣势** | 计算成本稍高，阈值敏感 |
| **适用场景** | 多角度参考向量 + 变化人脸 |
---
## Top 5 Match Details (阈值 0.75)
| Match | Frame | Final Score | Best Match | Vote Ratio | Weighted Sim |
|-------|-------|-------------|-----------|-----------|--------------|
| 1 | 210 | 0.9427 | 1.0000 | 83.33% | 0.7602 |
| 2 | 190 | 0.9422 | 1.0000 | 83.33% | 0.7548 |
| 3 | 220 | 0.9419 | 1.0000 | 83.33% | 0.7525 |
| 4 | 260 | 0.9415 | 1.0000 | 83.33% | 0.7483 |
| 5 | 180 | 0.9392 | 1.0000 | 83.33% | 0.7256 |
---
## 推荐配置
### 高精度匹配
| 参数 | 值 |
|------|-----|
| **策略** | Best Match |
| **阈值** | 0.85 |
| **Match Ratio** | 48.39% |
### 平衡匹配
| 参数 | 值 |
|------|-----|
| **策略** | Combined |
| **权重** | {best_match: 0.7, vote_ratio: 0.2, weighted_sim: 0.1} |
| **阈值** | 0.80 |
| **Match Ratio** | 35.48% |
### 高鲁棒性匹配
| 参数 | 值 |
|------|-----|
| **策略** | Combined |
| **权重** | {best_match: 0.7, vote_ratio: 0.2, weighted_sim: 0.1} |
| **阈值** | 0.75 |
| **Match Ratio** | 45.16% ✅ |
---
## 使用方式
### 高精度匹配 (Best Match)
```bash
python3 scripts/match_face_identity.py \
--identity-name "Person Name" \
--face-json output/video.face.json \
--strategy best_match \
--threshold 0.85 \
--batch
```
### 高鲁棒性匹配 (Combined)
```bash
python3 scripts/match_face_identity.py \
--identity-name "Person Name" \
--face-json output/video.face.json \
--strategy combined \
--threshold 0.75 \
--weights "0.7,0.2,0.1" \
--batch
```
---
## 结论
✅ **1对多参考向量架构验证成功**
| 改进项 | 结果 |
|--------|------|
| **权重优化** | 从 0% → 45.16% (阈值 0.75) |
| **阈值调整** | 0.85 → 0.75 (Match Ratio 提升 36%) |
| **策略对比** | Combined 接近 Best Match |
**推荐配置**:
- **高精度**: Best Match + 阈值 0.85
- **高鲁棒性**: Combined + 权重 {0.7, 0.2, 0.1} + 阈值 0.75
---
## 版本信息
- 报告版本: V1.0
- 测试日期: 2026-04-28
- 测试状态: ✅ 成功

231
docs_v1.0/EXPERIMENT_REPORTS/POSE_BASED_MATCHING_FINAL_REPORT_2026-04-28.md
View File

@@ -1,231 +0,0 @@
# Pose-based Identity Matching 完整实验报告
> 实验日期: 2026-04-28
> 实验版本: V2.0 (Phase 1-4)
> 测试视频: preview.mp4 (15秒, 31帧人脸)
---
## 实验概述
本实验完整验证 **Pose-based Identity Matching 系统**，包括：
1. **Phase 1**: 角度分类算法优化 (多特征综合)
2. **Phase 2**: 自动多角度参考向量选择
3. **Phase 3**: Identity 注册优化
4. **Phase 4**: Pose-filtered Matching v2 (自适应阈值 + fallback)
---
## 实验结果对比
### 总体对比
| Strategy | Match Ratio | Confidence Avg | profile_right Similarity |
|----------|-------------|----------------|--------------------------|
| **Best Match** | 48.39% (15/31) | - | 0.08 ❌ |
| **Combined (优化权重)** | 9.68% (3/31) | - | - |
| **Pose-filtered V1** | 35.48% (11/31) | 0.87 | 0.08 ❌ |
| **Pose-filtered V2** | **41.94% (13/31)** ✅ | **0.87** | **0.8547** ✅ |
---
### Phase 1: Pose 分析器对比
| 指标 | V1 (单特征) | V2 (多特征) | 改进 |
|------|------------|------------|------|
| **Confidence Avg** | 0.70 | **0.87** | +0.17 ✅ |
| **profile_right 检测** | 1 帧 (3%) | **11 帧 (35%)** | +10 帧 ✅ |
| **three_quarter 分布** | 27 帧 (87%) | **17 帧 (55%)** | 更准确 ✅ |
**V2 多特征**:
- `nose_to_eye_ratio`
- `eye_slope` (仰视/俯视)
- `nose_offset_norm` (左/右侧脸)
- `mouth_symmetry`
- `jaw_visibility_hint`
---
### Phase 2: 参考向量选择对比
| Identity | Vectors | Angles Covered | Quality Avg | profile_right References |
|----------|---------|----------------|-------------|-------------------------|
| **V1** | 6 | {three_quarter, profile_left, profile_right} | - | **0** ❌ |
| **V2** | 6 | {three_quarter: 2, profile_left: 2, profile_right: 2} | **0.88** | **2** ✅ |
**关键改进**: V2 自动选择 2 个 profile_right 参考向量（质量 0.91）。
---
### Phase 4: 匹配策略对比
| Angle | V1 Similarity | V1 Threshold | V2 Similarity | V2 Threshold | V2 Match |
|-------|--------------|--------------|--------------|--------------|----------|
| **three_quarter** | 0.5154 | 0.85 | 0.5154 | **0.85** | 4/17 ✅ |
| **profile_right** | 0.0854 ❌ | 0.85 | **0.8547** ✅ | **0.80** | 7/11 ✅ |
| **profile_left** | 0.9987 | 0.85 | 0.9987 | **0.80** | 2/3 ✅ |
**自适应阈值**:
- `frontal`: 0.90 (最高精度)
- `three_quarter`: 0.85 (标准)
- `profile_left/right`: **0.80** (更宽容)
---
## 详细分析
### profile_right 改进 (关键成果)
| 指标 | Before | After | 改进 |
|------|--------|-------|------|
| **Reference Vectors** | 0 | **2** | +2 |
| **Avg Similarity** | 0.08 ❌ | **0.8547** | **+0.77** 🎉 |
| **Match Count** | 0 | **7/11** | +7 |
**原因**:
1. V2 Pose 分析器正确检测 11 个 profile_right 帧
2. 自动选择 2 个高质量 profile_right 参考向量
3. 自适应阈值 0.80 (更宽容)
---
### Angle Match Types
| Type | Count | 说明 |
|------|-------|------|
| **exact** | 31 (100%) | 所有匹配使用 exact angle |
| **fallback** | 0 | 无需 fallback ✅ |
**说明**: V2 参考向量覆盖了所有检测到的角度，无需 fallback。
---
## Top 5 Matches
| Match | Frame | Pose Angle | Similarity | Threshold | Match |
|-------|-------|-----------|-----------|-----------|-------|
| 1 | 220 | profile_right | **1.0000** | 0.80 | ✅ |
| 2 | 210 | profile_right | **1.0000** | 0.80 | ✅ |
| 3 | 260 | three_quarter | **1.0000** | 0.85 | ✅ |
| 4 | 270 | three_quarter | **1.0000** | 0.85 | ✅ |
| 5 | 310 | profile_left | **1.0000** | 0.80 | ✅ |
---
## 实施成果
### 创建的文件
| 文件 | 说明 | 功能 |
|------|------|------|
| `scripts/utils/pose_analyzer.py` | Pose 分析器 V2 | 多特征综合分类 |
| `scripts/select_face_reference_vectors_v2.py` | 自动参考向量选择 | 确保角度覆盖 |
| `scripts/match_face_with_pose_filtering.py` | Pose-filtered Matching V2 | 自适应阈值 + fallback |
| `docs/POSE_BASED_MATCHING_OPTIMIZATION_PLAN.md` | 优化方案规划 | 完整实施计划 |
---
### 数据库注册
| Identity | UUID | Angles | Quality Avg |
|----------|------|--------|-------------|
| **Preview Test Person V1** | `5ae2a1a2-...` | 3 angles | - |
| **Preview Test Person V2** | `4ce396fc-...` | **3 angles (balanced)** | **0.88** |
---
## 关键发现
### 1. Pose 分析关键
**V1 问题**: 仅用 nose-to-eye ratio，profile_right 检测 1 帧 (3%)
**V2 解决**: 多特征综合，profile_right 检测 11 帧 (35%)
### 2. 参考向量覆盖关键
**V1 问题**: profile_right 无参考向量 → similarity = 0.08
**V2 解决**: 自动选择 2 个 profile_right 参考向量 → similarity = 0.8547
### 3. 自适应阈值关键
**V1 问题**: 所有角度使用 0.85 → profile_right 匹配失败
**V2 解决**: profile 使用 0.80 → 7/11 匹配成功
---
## 推荐配置
### 高精度匹配 (推荐)
| 参数 | 值 |
|------|-----|
| **Pose Analyzer** | V2 (多特征) |
| **Reference Selection** | V2 (自动多角度) |
| **Matching Strategy** | pose_filtered_v2 |
| **Adaptive Threshold** | frontal=0.90, three_quarter=0.85, profile=0.80 |
### 使用方式
```bash
# Step 1: Pose 分析
python3 scripts/utils/pose_analyzer.py --face-json output/video.face.json
# Step 2: 自动选择参考向量
python3 scripts/select_face_reference_vectors_v2.py \
--face-json output/video.face.json \
--identity-name "Person Name" \
--register
# Step 3: Pose-filtered 匹配
python3 scripts/match_face_with_pose_filtering.py \
--identity-name "Person Name" \
--face-json output/video.face.json \
--strategy pose_filtered_v2 \
--batch
```
---
## 未来优化
| Phase | 任务 | 优先级 |
|-------|------|--------|
| **Phase 5** | 整合到生产流程 | 高 |
| **Phase 5.1** | Face Processor 输出 pose angle | 高 |
| **Phase 5.2** | Identity Registration API | 中 |
| **Phase 5.3** | Portal UI 显示 angle_coverage | 低 |
| **Phase 6** | Frontal 角度补充 | 中 |
---
## 结论
✅ **Pose-based Identity Matching 完整实施成功**
### 定量改进
| 指标 | Before | After | 改进 |
|------|--------|-------|------|
| **Match Ratio** | 35.48% | **41.94%** | +6.46% ✅ |
| **profile_right Similarity** | 0.08 | **0.8547** | **+0.77** 🎉 |
| **Pose Confidence** | 0.70 | **0.87** | +0.17 ✅ |
### 定性改进
- ✅ **多特征 Pose 分类**: 更准确的角度检测
- ✅ **自动多角度覆盖**: 确保 3-4 个角度覆盖
- ✅ **自适应阈值**: 不同角度使用不同阈值
- ✅ **Fallback 机制**: 支持无同角度向量时的 fallback
---
## 版本信息
- 实验版本: V2.0
- 实验日期: 2026-04-28
- 实验状态: ✅ Phase 1-4 完成
- 下一步: Phase 5 (生产流程整合)