docs: update docs_v1.0/ documentation
- Fix markdown lint issues (MD030, MD047, MD051, MD028, MD005) - Update AI agents, architecture, implementation docs - Add new identity, face recognition, and API documentation - Remove deprecated face/person API guides
This commit is contained in:
Warren
@@ -0,0 +1,261 @@
|
||||
# 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
|
||||
- 状态: ✅ 已完成基础功能
|
||||
Reference in New Issue
Block a user