单目3D初始代码

eval_tools/docs/HEADING_ERROR_TOOLKIT_README.md

@@ -0,0 +1,455 @@
+# 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 待实现