# Heading Error Analysis Toolkit

Heading 误差分析工具链，用于提取、可视化和分析 3D 目标检测中的方向预测错误。

## 工具概览

本工具链包含 4 个核心工具：

### ✅ Tool 1: 数据提取工具
**文件**: `extract_bad_heading_cases.py`

从评估结果中提取 heading 误差大的案例，支持多维度筛选。

```bash
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 1.5 \
    --top-k 100 \
    --output bad_heading_cases.json \
    --stats
```

**功能**：
- 多条件筛选（阈值、类别、距离、置信度）
- 反转错误检测（≈180°）
- 详细统计分析
- 结构化 JSON 输出

📖 [详细文档](EXTRACT_BAD_HEADING_USAGE.md)

---

### ✅ Tool 2: 可视化生成工具
**文件**: `visualize_heading_errors.py`

生成 BEV、图像投影、角度分析和综合视图。

```bash
python eval_tools/visualize_heading_errors.py \
    --input bad_heading_cases.json \
    --image-root /path/to/images \
    --output runs/heading_viz \
    --viz-types bev image angle combined
```

**功能**：
- BEV 鸟瞰图（GT/Pred 3D框 + 方向箭头）
- 图像视图（2D框 + 误差标注）
- 角度分析（极坐标 + 柱状图）
- 综合视图（四宫格 + 详细统计）

📖 [详细文档](VISUALIZE_HEADING_USAGE.md)

---

### 🚧 Tool 3: 交互式查看器 (待实现)
**文件**: `heading_error_viewer.py`

Web 界面交互式浏览和分析案例。

```bash
python eval_tools/heading_error_viewer.py \
    --input bad_heading_cases.json \
    --viz-dir runs/heading_viz \
    --port 8080
```

**计划功能**：
- Web UI 浏览所有案例
- 过滤和排序功能
- 并排对比多个案例
- 统计图表展示

---

### 🚧 Tool 4: 报告生成器 (待实现)
**文件**: `generate_heading_report.py`

自动生成 HTML/Markdown 分析报告。

```bash
python eval_tools/generate_heading_report.py \
    --input bad_heading_cases.json \
    --viz-dir runs/heading_viz \
    --output heading_analysis_report.html
```

**计划功能**：
- 自动生成分析报告
- 统计图表和趋势分析
- 典型案例展示
- 问题总结和建议

---

## 完整工作流

### 1. 数据提取阶段

```bash
# 提取所有 bad cases
python eval_tools/extract_bad_heading_cases.py \
    --input eval_results_common_match_comparison/yolov5s-300w/20260203_210259/detailed_3d_matches.json \
    --threshold 1.5 \
    --output all_bad_cases.json \
    --stats

# 或者只提取反转错误（针对 yolov5s-300w 的主要问题）
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --reversal-only \
    --top-k 100 \
    --output reversal_errors.json \
    --stats
```

### 2. 可视化生成阶段

```bash
# 生成所有类型的可视化
python eval_tools/visualize_heading_errors.py \
    --input reversal_errors.json \
    --image-root /path/to/eval/cases \
    --output runs/reversal_analysis \
    --viz-types bev image angle combined

# 或者只生成关键视图（节省时间）
python eval_tools/visualize_heading_errors.py \
    --input reversal_errors.json \
    --image-root /path/to/eval/cases \
    --output runs/reversal_analysis \
    --viz-types combined \
    --max-cases 50
```

### 3. 交互式查看阶段 (待实现)

```bash
# 启动 Web 查看器
python eval_tools/heading_error_viewer.py \
    --input reversal_errors.json \
    --viz-dir runs/reversal_analysis \
    --port 8080

# 浏览器访问 http://localhost:8080
```

### 4. 报告生成阶段 (待实现)

```bash
# 生成分析报告
python eval_tools/generate_heading_report.py \
    --input reversal_errors.json \
    --viz-dir runs/reversal_analysis \
    --output reports/heading_analysis_report.html

# 查看报告
open reports/heading_analysis_report.html
```

---

## 典型使用场景

### 场景 1: 快速定位严重问题

```bash
# 1. 提取 top 20 worst cases
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 2.0 \
    --top-k 20 \
    --output top20_worst.json

# 2. 生成综合视图
python eval_tools/visualize_heading_errors.py \
    --input top20_worst.json \
    --image-root /data/cases \
    --output runs/top20_analysis \
    --viz-types combined

# 3. 查看 runs/top20_analysis/combined/ 目录
```

### 场景 2: 分析反转错误模式

```bash
# 1. 提取所有反转错误
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --reversal-only \
    --top-k 100 \
    --output reversal_100.json \
    --stats

# 2. 生成 BEV 视图（最直观）
python eval_tools/visualize_heading_errors.py \
    --input reversal_100.json \
    --image-root /data/cases \
    --output runs/reversal_bev \
    --viz-types bev

# 3. 浏览 BEV 图像，寻找共同特征
```

### 场景 3: 类别对比分析

```bash
# 分别提取和可视化不同类别
for class in vehicle pedestrian bicycle rider; do
    python eval_tools/extract_bad_heading_cases.py \
        --input detailed_3d_matches.json \
        --threshold 1.5 \
        --classes $class \
        --top-k 30 \
        --output ${class}_bad.json
    
    python eval_tools/visualize_heading_errors.py \
        --input ${class}_bad.json \
        --image-root /data/cases \
        --output runs/by_class/${class} \
        --viz-types combined
done

# 对比各类别的问题模式
```

### 场景 4: 距离敏感性分析

```bash
# 近距离 (< 30m)
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --max-distance 30 \
    --top-k 30 \
    --output near_bad.json

python eval_tools/visualize_heading_errors.py \
    --input near_bad.json \
    --image-root /data/cases \
    --output runs/distance/near \
    --viz-types combined

# 中距离 (30-60m)
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --min-distance 30 \
    --max-distance 60 \
    --top-k 30 \
    --output mid_bad.json

python eval_tools/visualize_heading_errors.py \
    --input mid_bad.json \
    --image-root /data/cases \
    --output runs/distance/mid \
    --viz-types combined

# 远距离 (> 60m)
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --min-distance 60 \
    --top-k 30 \
    --output far_bad.json

python eval_tools/visualize_heading_errors.py \
    --input far_bad.json \
    --image-root /data/cases \
    --output runs/distance/far \
    --viz-types combined
```

---

## 当前问题分析

基于 yolov5s-300w 模型的评估结果：

### 主要发现

1. **Heading 误差严重**：
   - 比 mono3d 高 28.61%
   - 68.7% 的 bad cases 是反转错误（≈180°）

2. **类别差异**：
   - **Vehicle**: 87.3% 反转率（最严重）
   - Bicycle: 46.8% 反转率
   - Rider: 35.3% 反转率
   - Pedestrian: 16.1% 反转率（最轻）

3. **其他指标良好**：
   - 2D mAP +21.85%
   - 横向误差 -9.39%
   - 纵向误差 -4.48%

### 分析假设

可能的根本原因：

1. **模型输出范围问题**：
   - Heading 预测范围不正确
   - 输出范围 [0, π] vs 需要 [-π, π]
   - 导致 180° 的系统性偏差

2. **损失函数问题**：
   - Heading loss 可能没有正确处理角度周期性
   - 没有惩罚反转错误

3. **后处理问题**：
   - 角度转换或归一化错误
   - NMS 或其他后处理导致的问题

4. **数据或标注问题**：
   - 训练数据中的角度分布不均
   - 标注定义不一致

---

## 文件结构

```
eval_tools/
├── extract_bad_heading_cases.py          # Tool 1: 数据提取
├── visualize_heading_errors.py           # Tool 2: 可视化生成
├── heading_error_viewer.py               # Tool 3: 交互查看器 (待实现)
├── generate_heading_report.py            # Tool 4: 报告生成 (待实现)
│
├── test_extract_bad_cases.sh             # Tool 1 测试脚本
├── test_visualize_heading.sh             # Tool 2 测试脚本
│
├── HEADING_ERROR_TOOLKIT_README.md       # 本文档
├── EXTRACT_BAD_HEADING_USAGE.md          # Tool 1 详细文档
├── VISUALIZE_HEADING_USAGE.md            # Tool 2 详细文档
└── HEADING_ERROR_VISUALIZATION_PLAN.md   # 完整分析方案
```

---

## 依赖安装

```bash
# 已包含在项目 requirements.txt 中
pip install -r requirements.txt

# 主要依赖：
# - numpy
# - opencv-python
# - matplotlib
# - tqdm
# - json (标准库)
```

---

## 性能建议

### 大数据集处理

对于大规模评估结果（如 596K 匹配）：

```bash
# 1. 先用严格阈值快速筛选
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 2.5 \
    --top-k 50 \
    --output critical_cases.json

# 2. 分批可视化
python eval_tools/visualize_heading_errors.py \
    --input critical_cases.json \
    --image-root /data/cases \
    --output runs/critical \
    --max-cases 20 \
    --viz-types combined

# 3. 根据发现再扩大分析范围
```

### 存储优化

```bash
# 只生成必要的可视化类型
python eval_tools/visualize_heading_errors.py \
    --input bad_cases.json \
    --image-root /data/cases \
    --output runs/viz \
    --viz-types bev  # 最小化存储

# 降低 DPI 节省空间（预览用）
python eval_tools/visualize_heading_errors.py \
    --input bad_cases.json \
    --image-root /data/cases \
    --output runs/preview \
    --viz-types combined \
    --dpi 80
```

---

## 下一步计划

### 立即可用
- ✅ Tool 1: 数据提取工具
- ✅ Tool 2: 可视化生成工具

### 待实现
- 🚧 Tool 3: 交互式查看器
  - Flask/Streamlit Web UI
  - 实时过滤和排序
  - 案例对比功能

- 🚧 Tool 4: 报告生成器
  - 自动化分析报告
  - 统计图表生成
  - 问题总结和建议

### 功能增强
- [ ] 3D 可视化（完整 3D 坐标系）
- [ ] 时序分析（同一目标的轨迹）
- [ ] 热力图（误差分布）
- [ ] 自动模式识别

---

## 相关文档

- [Heading Error Visualization Plan](HEADING_ERROR_VISUALIZATION_PLAN.md) - 完整分析方案
- [GT Visualization Guide](../test_scripts/GT_VISUALIZATION_COMPLETE_GUIDE.md) - GT 可视化工具
- [Metrics Summary](../eval_results_common_match_comparison_v1/.../METRICS_SUMMARY.md) - 评估指标总结

---

## 技术支持

遇到问题请：

1. 查看对应工具的详细文档
2. 运行测试脚本验证环境
3. 检查输入文件格式
4. 查看错误日志

```bash
# 调试模式运行
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 1.5 \
    --output test.json \
    --stats 2>&1 | tee debug.log
```

---

**更新日期**: 2026-02-04  
**版本**: 1.0  
**状态**: Tool 1 & 2 已完成，Tool 3 & 4 待实现
