yolov26_3d/eval_tools/docs/COMMON_MATCH_COMPARISON_USAGE.md

# 基于共同匹配集的3D指标对比 - 使用指南

## 问题背景

在比较两个模型的3D检测性能时，发现两个模型匹配到的样本数量不一致：

```
Model A: 匹配了 440,408 个 vehicle
Model B: 匹配了 491,768 个 vehicle
差异: 51,360 个样本 (11.7%)
```

**问题**：无法确定性能差异是因为模型质量不同，还是因为匹配了不同的目标。

**解决方案**：只比较两个模型都成功匹配到GT的目标，确保对比的是相同目标的3D性能。

## 快速开始

### 方法一：使用一键脚本（推荐）

```bash
bash eval_tools/compare_models_with_common_matches.sh
```

这个脚本会自动完成以下步骤：
1. 评测 Model 1（mono3d）并保存详细匹配
2. 评测 Model 2（yolov5s）并保存详细匹配
3. 找出共同匹配的GT目标
4. 生成基于共同匹配的对比报告
5. 生成传统对比报告（用于参考）

### 方法二：手动执行步骤

#### 步骤1：评测模型并保存详细匹配

```bash
# 评测 Model 1
python eval_tools/eval.py \
  --config eval_tools/configs/eval_config_mono3d.yaml \
  --save-detailed-matches

# 评测 Model 2
python eval_tools/eval.py \
  --config eval_tools/configs/eval_config_yolov5.yaml \
  --save-detailed-matches
```

**输出文件**：
- `evaluation_report.json` - 评测报告
- `detailed_3d_matches.json` - 详细匹配信息（新增）

#### 步骤2：找出共同匹配

```bash
python eval_tools/find_common_matches.py \
  --model1-matches eval_results/model1/detailed_3d_matches.json \
  --model2-matches eval_results/model2/detailed_3d_matches.json \
  --output common_matches.json \
  --model1-name "mono3d" \
  --model2-name "yolov5s-300w"
```

**输出示例**：
```
================================================================================
COMMON MATCH STATISTICS
================================================================================

Overall:
  Model 1 Total Matches: 440,408
  Model 2 Total Matches: 491,768
  Common Matches: 425,163 (96.5% of Model 1)
  Model 1 Unique: 15,245 (3.5%)
  Model 2 Unique: 66,605 (13.5%)

Per-Class Statistics:
Class           Model1     Model2     Common    Common%   M1 Unique   M2 Unique
--------------------------------------------------------------------------------
vehicle        440,408    491,768    425,163      96.5%       15,245      66,605
```

#### 步骤3：比较模型（基于共同匹配）

```bash
python eval_tools/compare_models.py \
  --model1 eval_results/model1/evaluation_report.json \
  --model2 eval_results/model2/evaluation_report.json \
  --model1-name "mono3d" \
  --model2-name "yolov5s-300w" \
  --common-matches common_matches.json \
  --output-dir comparison_common_matches
```

**关键参数**：
- `--common-matches`: 指定共同匹配数据文件
- 如果不提供此参数，将使用传统方式比较（所有匹配）

## 对比报告解读

### 共同匹配对比报告

```
================================================================================
3D METRICS COMPARISON (COMMON MATCHES ONLY)
================================================================================

Match Statistics:
  mono3d Total Matches: 440,408
  yolov5s-300w Total Matches: 491,768
  Common Matches: 425,163 (96.5% of mono3d)
  mono3d Unique: 15,245
  yolov5s-300w Unique: 66,605

VEHICLE (Common Matches: 425,163):
Metric               mono3d          yolov5s-300w    Diff            Change %     
------------------------------------------------------------------------------------
Lateral (m)          1.3251          1.2103          -0.1148         -8.66%       ✓
Longitudinal (m)     2.5892          2.4231          -0.1661         -6.42%       ✓
Heading (rad)        0.2256          0.3098          +0.0842         +37.32%      ✗

Note: 这些统计基于两个模型都成功匹配的目标，排除了只被一个模型匹配的目标。
```

### 关键信息解读

1. **匹配统计**：
   - Common Matches: 两个模型都匹配到的GT数量
   - Model Unique: 只被该模型匹配的GT数量
   - Common%: 共同匹配占该模型总匹配的百分比

2. **3D误差对比**：
   - 基于相同的GT目标进行比较
   - 可以公平评估两个模型的3D预测质量
   - ✓ 表示model2更好，✗ 表示model1更好

3. **独有匹配分析**：
   - Model 1 Unique: 15,245 (3.5%)
     * 这些是只有model1匹配到的目标
     * 可能是容易匹配的目标
   - Model 2 Unique: 66,605 (13.5%)
     * 这些是只有model2匹配到的目标
     * 说明model2的召回率更高

## 数据文件说明

### detailed_3d_matches.json

保存每个匹配对的详细信息：

```json
{
  "case_019b178d": {
    "frame_000018": {
      "vehicle": [
        {
          "gt_id": "a1b2c3d4e5f6g7h8",
          "gt_bbox": [90.48, 561.98, 241.52, 714.00],
          "gt_center_3d": [-7.13, 0.91, 8.20],
          "det_bbox": [91.2, 562.5, 240.8, 713.2],
          "det_center_3d": [-7.25, 0.89, 8.35],
          "iou": 0.89,
          "confidence": 0.87478,
          "errors": {
            "lateral": 0.12,
            "longitudinal": 0.15,
            "heading": 0.05
          },
          "distance": {
            "longitudinal": 8.20,
            "lateral": -7.13
          }
        }
      ]
    }
  }
}
```

### common_matches.json

包含共同匹配索引和重新计算的统计：

```json
{
  "match_statistics": {
    "model1_total": 440408,
    "model2_total": 491768,
    "common": 425163,
    "common_percentage_of_model1": 96.5
  },
  "model1_3d_stats": {
    "vehicle": {
      "num_samples": 425163,
      "lateral_error": {"mean": 1.3251, "std": 0.8745},
      "longitudinal_error": {"mean": 2.5892, "std": 1.2341}
    }
  },
  "model2_3d_stats": { ... }
}
```

## 使用场景

### 场景1：公平对比两个模型的3D性能

**问题**：两个模型召回率不同，匹配的目标不一样。

**方案**：使用共同匹配对比，确保比较相同目标的预测质量。

```bash
# 使用 --common-matches 参数
python eval_tools/compare_models.py \
  --model1 model1_report.json \
  --model2 model2_report.json \
  --common-matches common_matches.json \
  --output-dir fair_comparison
```

### 场景2：分析模型独有匹配的特点

**问题**：想知道为什么一个模型能匹配更多目标。

**方案**：查看 common_matches.json 中的统计信息。

```python
import json

with open('common_matches.json') as f:
    data = json.load(f)

stats = data['match_statistics']
print(f"Model 1 Unique: {stats['model1_unique']}")
print(f"Model 2 Unique: {stats['model2_unique']}")

# 可以进一步分析独有匹配的距离分布、置信度等
```

### 场景3：对比不同训练策略的效果

**问题**：调整了训练参数，想知道3D精度是否真的提升。

**方案**：基于共同匹配对比，排除召回率变化的影响。

## 注意事项

1. **存储开销**：
   - `detailed_3d_matches.json` 约为 `evaluation_report.json` 的 5-10 倍
   - 建议只在需要对比时使用 `--save-detailed-matches`

2. **GT唯一标识**：
   - 基于2D bbox坐标生成MD5哈希
   - 确保同一个GT在两个模型中有相同的ID

3. **向后兼容**：
   - 不使用 `--save-detailed-matches` 时，行为与之前完全一致
   - 不使用 `--common-matches` 时，compare_models.py 执行传统对比

4. **性能考虑**：
   - 保存详细匹配会略微增加评测时间（约5-10%）
   - 主要开销在JSON序列化

## 常见问题

### Q1: 为什么Common Matches不是100%？

A: 有以下几种可能：
- 模型的召回率不同
- IoU阈值导致的边界情况
- 2D检测质量差异

### Q2: 独有匹配有什么特点？

A: 可以使用以下分析：
```bash
# find_common_matches.py 会输出Per-Class统计
python eval_tools/find_common_matches.py ... 
```

查看输出中的 "Model X Unique" 数量和比例。

### Q3: 如何可视化独有匹配？

A: 可以基于 detailed_3d_matches.json 找出独有匹配的case和frame，然后可视化：

```python
# 找出 model2 独有的匹配
for case in model2_matches:
    for frame in model2_matches[case]:
        for cls in model2_matches[case][frame]:
            for match in model2_matches[case][frame][cls]:
                gt_id = match['gt_id']
                if gt_id not in common_gt_ids:
                    # 这是 model2 独有的匹配
                    visualize(case, frame, match)
```

## 总结

使用共同匹配对比方案：
- ✅ 公平对比：确保比较相同目标的预测质量
- ✅ 问题诊断：识别哪些目标一个模型能匹配而另一个不能
- ✅ 性能分析：可以单独分析各模型独有匹配的特点
- ✅ 向后兼容：不影响现有评测流程

## 相关文档

- [COMMON_MATCH_COMPARISON_DESIGN.md](COMMON_MATCH_COMPARISON_DESIGN.md) - 详细设计方案
- [eval_tools/find_common_matches.py](find_common_matches.py) - 共同匹配查找工具
- [eval_tools/compare_models.py](compare_models.py) - 模型比较工具