# 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 待实现