yolov26_3d/eval_tools/docs/HEADING_ERROR_VISUALIZATION_PLAN.md

# Heading误差可视化分析方案

## 方案概述

针对`detailed_3d_matches.json`中heading误差较大的目标，设计多维度可视化分析系统，帮助定位问题根源。

---

## 📋 方案设计

### 1. 数据筛选策略

#### 筛选条件
- **主要条件**：`heading_error > threshold`（建议threshold=1.5rad ≈ 85°）
- **辅助条件**：
  - 按类别筛选（vehicle/pedestrian/bicycle/rider）
  - 按距离范围筛选（近距离/中距离/远距离）
  - 按置信度筛选（高置信度bad cases更值得关注）
  - 按误差类型筛选（接近π的反转错误 vs 其他错误）

#### 误差分级
```python
# 误差等级定义
ERROR_LEVELS = {
    'critical': heading_error > 2.5,      # 严重错误（>143°）
    'severe': 1.5 < heading_error <= 2.5,  # 重大错误（85°-143°）
    'moderate': 0.5 < heading_error <= 1.5, # 中等错误（28°-85°）
    'minor': heading_error <= 0.5          # 轻微错误（<28°）
}
```

### 2. 可视化维度

#### A. BEV鸟瞰图视角 🗺️

**目的**：直观对比GT和预测的朝向差异

**可视化内容**：
```
┌─────────────────────────────────────┐
│  Bird's Eye View                     │
│                                      │
│  ↑ Z (Forward)                       │
│  │                                   │
│  │    ┏━━━━━━━━┓  ← GT (绿色)       │
│  │    ┃        ┃  箭头指向前方      │
│  │    ┃  →     ┃                    │
│  │    ┗━━━━━━━━┛                    │
│  │                                   │
│  │    ╔════════╗  ← Pred (红色)     │
│  │    ║    ←   ║  箭头指向相反      │
│  │    ║        ║                    │
│  │    ╚════════╝                    │
│  │                                   │
│  └────────────────→ X (Right)       │
│                                      │
│  误差：3.14 rad (180°) - 方向反转   │
└─────────────────────────────────────┘
```

**实现要点**：
- GT用绿色框+绿色箭头
- Prediction用红色框+红色箭头
- 标注误差值（弧度和角度）
- 显示自车位置
- 标注距离网格

#### B. 图像投影视角 📷

**目的**：在原图上查看目标外观和朝向关系

**可视化内容**：
- 原始图像
- 2D边界框（GT绿色，Pred红色）
- 3D边界框投影（8个顶点+12条边）
- 朝向指示箭头
- 信息标注：
  - 类别、置信度
  - heading_error值
  - GT rotation vs Pred rotation
  - 距离信息

#### C. 角度对比图 📐

**目的**：可视化角度差异的具体模式

**1. 圆形角度图（Polar Plot）**
```
        0° (Forward)
           ↑
           │
           │
  270° ────┼──── 90°
           │
           │
           ↓
        180° (Backward)

● GT角度位置（绿点）
● Pred角度位置（红点）
→ 误差向量（虚线箭头）
```

**2. 散点图（Scatter Plot）**
```
Pred Rotation
   π ┤         ●●●●●●  ← 反转错误聚集区
     │         ●
     │
     │    ●
  -π ├────●──────────────
    -π          0         π
           GT Rotation
```

**3. 误差分布直方图**
```
Count
  │  █
  │  █
  │  █  █
  │  █  █  █
  │  █  █  █  █
  └──────────────────→
     Heading Error (rad)
```

#### D. 多目标对比面板 📊

**目的**：同时展示多个bad cases，发现共性

**布局设计**：
```
┌─────────────────────────────────────────────────────┐
│  Top 10 Worst Heading Errors                        │
├──────────┬──────────┬──────────┬─────────────────────┤
│  Case 1  │  Case 2  │  Case 3  │  ...                │
│  ┌────┐  │  ┌────┐  │  ┌────┐  │                     │
│  │BEV │  │  │BEV │  │  │BEV │  │  每个case包含：     │
│  └────┘  │  └────┘  │  └────┘  │  - BEV图            │
│  ┌────┐  │  ┌────┐  │  ┌────┐  │  - 原图             │
│  │IMG │  │  │IMG │  │  │IMG │  │  - 关键信息         │
│  └────┘  │  └────┘  │  └────┘  │                     │
│  Info    │  Info    │  Info    │                     │
├──────────┴──────────┴──────────┴─────────────────────┤
│  共性分析：                                           │
│  - 80%为反转错误（error ≈ π）                        │
│  - 90%为vehicle类别                                   │
│  - 集中在中远距离（30-80m）                           │
└─────────────────────────────────────────────────────┘
```

#### E. 交互式分析面板 🖱️

**目的**：支持深入分析和探索

**功能设计**：
```
┌─────────────────────────────────────────────────────┐
│  Heading Error Analysis Dashboard                    │
├─────────────────────────────────────────────────────┤
│  [Filters]                                           │
│  Class:    [✓All ✓Vehicle ✓Pedestrian □Bicycle]    │
│  Distance: [0-30m] [30-60m] [60-100m] [100m+]       │
│  Error:    [>2.5] [1.5-2.5] [0.5-1.5] [<0.5]        │
│  Pattern:  [Reversal (≈π)] [Other]                  │
├─────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐                 │
│  │ Distribution │  │ Scatter Plot │                 │
│  │    Chart     │  │  GT vs Pred  │                 │
│  └──────────────┘  └──────────────┘                 │
├─────────────────────────────────────────────────────┤
│  [Selected Case Detail]                             │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐    │
│  │   Image    │  │    BEV     │  │   Stats    │    │
│  │            │  │            │  │            │    │
│  └────────────┘  └────────────┘  └────────────┘    │
├─────────────────────────────────────────────────────┤
│  Navigation: [< Prev]  Case 15/234  [Next >]       │
└─────────────────────────────────────────────────────┘
```

### 3. 统计分析图表

#### A. 误差模式分析

**1. 误差类型饼图**
```
┌─────────────────────┐
│  Error Patterns     │
│                     │
│   ╱────╲            │
│  │ 68% │  反转错误  │
│  │  π  │            │
│   ╲────╱            │
│   ╱──╲ 22% 其他     │
│  │10%│  中等误差    │
│   ╲──╱              │
└─────────────────────┘
```

**2. 各类别误差对比**
```
Avg Error (rad)
   3.0 ┤
   2.5 ┤        █
   2.0 ┤     █  █
   1.5 ┤  █  █  █
   1.0 ┤  █  █  █  █
   0.5 ┤  █  █  █  █
   0.0 └──────────────→
       Veh Ped Bic Rid
```

**3. 距离-误差关系图**
```
Error (rad)
   3.0 ┤  ●●●
   2.5 ┤ ●●●●●
   2.0 ┤●●●●●●●
   1.5 ┤●●●●●●●●
   1.0 ┤ ●●●●●●●
   0.5 ┤  ●●●●●
   0.0 └────────────────→
       0   30   60   90
          Distance (m)
```

#### B. GT vs Pred角度关系矩阵

**热力图展示**：
```
Pred Angle
    π ┤ ██░░░░░░  ← 反转区域
      │ ░░░░░░░░
      │ ░░░░█░░░  ← 正常区域
      │ ░░░░░░░░
   -π └───────────
     -π    0    π
        GT Angle

颜色深度 = case数量
```

### 4. 输出报告

#### A. 自动生成分析报告

**报告结构**：
```markdown
# Heading误差分析报告

## 1. 概览
- 总样本数：596,602
- 高误差样本（>1.5rad）：5,839 (0.98%)
- 反转错误（>3.04rad）：4,012 (68.7%)

## 2. 典型Case展示
[Top 20 worst cases with images]

## 3. 误差模式
- 方向反转（≈180°）：68.7%
- 其他大误差：31.3%

## 4. 类别分布
- Vehicle: 86.8% 反转率
- Bicycle: 38.3% 反转率
- Rider: 34.0% 反转率
- Pedestrian: 11.7% 反转率

## 5. 建议
...
```

#### B. 交互式HTML报告

**功能**：
- 可筛选、排序的表格
- 点击查看详细可视化
- 导出功能
- 打印友好版本

---

## 🛠️ 实现工具

### 工具1：数据提取器
```bash
python extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 1.5 \
    --output bad_heading_cases.json
```

### 工具2：可视化生成器
```bash
python visualize_heading_errors.py \
    --input bad_heading_cases.json \
    --gt-dir /path/to/labels \
    --img-dir /path/to/images \
    --output-dir runs/heading_analysis
```

### 工具3：交互式查看器
```bash
python heading_error_viewer.py \
    --input bad_heading_cases.json \
    --port 8080
# 在浏览器打开 http://localhost:8080
```

### 工具4：报告生成器
```bash
python generate_heading_report.py \
    --input bad_heading_cases.json \
    --output heading_error_report.html
```

---

## 📂 输出目录结构

```
runs/heading_error_analysis/
├── overview/
│   ├── error_distribution.png
│   ├── gt_vs_pred_scatter.png
│   ├── error_by_class.png
│   ├── error_by_distance.png
│   └── pattern_analysis.png
├── bev_visualization/
│   ├── case_000001_bev.png
│   ├── case_000002_bev.png
│   └── ...
├── image_visualization/
│   ├── case_000001_img.png
│   ├── case_000002_img.png
│   └── ...
├── combined_view/
│   ├── case_000001_combined.png  # BEV + IMG + Stats
│   ├── case_000002_combined.png
│   └── ...
├── multi_case_panels/
│   ├── top10_worst.png
│   ├── reversal_cases.png
│   └── by_class.png
├── bad_heading_cases.json
├── analysis_report.md
├── analysis_report.html
└── statistics.json
```

---

## 🎯 关键洞察点

### 预期发现

1. **反转错误模式**
   - GT接近0时，Pred接近π
   - GT为负值时，Pred为大正值
   - 特定类别更易发生反转

2. **距离相关性**
   - 远距离目标误差更大？
   - 近距离反转错误比例？

3. **类别差异**
   - Vehicle反转率最高（86.8%）
   - Pedestrian相对较好（11.7%）

4. **视觉特征**
   - 反转的目标有何共同特征？
   - 遮挡、截断的影响？
   - 角度标注的歧义性？

### 可能的根因

1. **模型架构问题**
   - Heading输出范围映射错误
   - 损失函数未考虑角度周期性
   - 前后方向特征不明显

2. **数据问题**
   - 训练数据角度分布不均
   - 标注歧义（前/后定义）
   - 数据增强影响角度

3. **后处理问题**
   - 角度归一化错误
   - 坐标系转换问题

---

## 📝 使用流程

### Step 1: 提取数据
```bash
python extract_bad_heading_cases.py \
    --input eval_results_common_match_comparison/yolov5s-300w/20260203_210259/detailed_3d_matches.json \
    --threshold 1.5 \
    --top-k 100 \
    --output bad_cases.json
```

### Step 2: 生成可视化
```bash
python visualize_heading_errors.py \
    --input bad_cases.json \
    --gt-dir /data/labels \
    --img-dir /data/images \
    --output-dir runs/heading_viz
```

### Step 3: 查看分析
```bash
# 方式1：静态报告
open runs/heading_viz/analysis_report.html

# 方式2：交互式查看
python heading_error_viewer.py --input bad_cases.json --port 8080
```

### Step 4: 深入分析
- 根据可视化结果筛选特定模式
- 对比不同条件下的误差
- 定位具体问题原因

---

## 🔄 迭代优化

基于分析结果，可以：

1. **模型改进**
   - 优化heading损失函数
   - 添加角度歧义解决机制
   - 增强前后方向特征学习

2. **数据改进**
   - 检查和修正标注错误
   - 平衡角度分布
   - 添加难例样本

3. **评估改进**
   - 区分反转错误和其他错误
   - 添加角度置信度评估
   - 引入人工review机制

---

## 📌 总结

这套方案提供：
- ✅ 多维度可视化（BEV、图像、统计图）
- ✅ 自动化工具链
- ✅ 交互式分析能力
- ✅ 完整的输出报告
- ✅ 可扩展的分析框架

通过这套方案，可以：
1. 快速定位heading误差大的样本
2. 直观理解误差模式
3. 发现问题根因
4. 指导模型改进