yolov26_3d/eval_tools/docs/HEADING_ERROR_TOOLKIT_README.md

Heading Error Analysis Toolkit

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

工具概览

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

✅ Tool 1: 数据提取工具

文件: extract_bad_heading_cases.py

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

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 输出

📖 详细文档

---

✅ Tool 2: 可视化生成工具

文件: visualize_heading_errors.py

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

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框 + 误差标注）
• 角度分析（极坐标 + 柱状图）
• 综合视图（四宫格 + 详细统计）

📖 详细文档

---

🚧 Tool 3: 交互式查看器 (待实现)

文件: heading_error_viewer.py

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

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 分析报告。

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

计划功能：

• 自动生成分析报告
• 统计图表和趋势分析
• 典型案例展示
• 问题总结和建议

---

完整工作流

1. 数据提取阶段

# 提取所有 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. 可视化生成阶段

# 生成所有类型的可视化
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. 交互式查看阶段 (待实现)

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

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

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

# 生成分析报告
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: 快速定位严重问题

# 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: 分析反转错误模式

# 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: 类别对比分析

# 分别提取和可视化不同类别
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: 距离敏感性分析

# 近距离 (< 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   # 完整分析方案

---

依赖安装

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

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

---

性能建议

大数据集处理

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

# 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. 根据发现再扩大分析范围

存储优化

# 只生成必要的可视化类型
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 - 完整分析方案
• GT Visualization Guide - GT 可视化工具
• Metrics Summary - 评估指标总结

---

技术支持

遇到问题请：

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

# 调试模式运行
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 待实现