yolov26_3d/eval_tools/docs/EVAL_FRAMEWORK_GUIDE.md

# 模型评测框架使用指南

> 入口脚本：`eval_tools/core/run_eval_with_config.sh`

---

## 目录

1. [框架概览](#1-框架概览)
2. [目录结构](#2-目录结构)
3. [核心流程](#3-核心流程)
4. [配置文件说明](#4-配置文件说明)
5. [命令行参数说明](#5-命令行参数说明)
6. [数据格式](#6-数据格式)
7. [评测指标](#7-评测指标)
8. [ROI GT 处理](#8-roi-gt-处理)
9. [模型对比（共同匹配集）](#9-模型对比共同匹配集)
10. [Heading 误差分析](#10-heading-误差分析)
11. [输出结果](#11-输出结果)
12. [使用示例](#12-使用示例)
13. [常见问题](#13-常见问题)

---

## 1. 框架概览

本框架用于评测 YOLOv5-3D 模型的 2D 检测与 3D 定位性能，支持：

- **2D 检测评测**：全部 14 个类别的 Precision / Recall / AP / mAP
- **3D 检测评测**：vehicle / pedestrian / bicycle / rider 的横向误差、纵向误差、heading 误差
- **ROI GT 过滤**：评测坐标系与训练时保持一致
- **距离区间分析**：按纵向距离（z轴）和横向距离（x轴）分段统计 3D 指标
- **多模型对比**：基于共同匹配集（Common Matches）公平比较两个模型的 3D 性能
- **Heading 误差分析**：提取、可视化、分析方向预测误差

### 架构图

```
eval_tools/core/run_eval_with_config.sh
            │
            ▼
eval_tools/core/eval.py            ← 主入口 Python 脚本
            │
            ├─── eval_tools/configs/*.yaml   ← 配置文件
            │
            └─── eval_tools/evaluator/       ← 核心评测引擎
                      ├── evaluator.py       ← 主控流程、并行调度
                      ├── parser.py          ← GT / 检测结果解析
                      ├── matcher.py         ← 2D IoU 匹配
                      ├── metrics_2d.py      ← 2D 指标计算
                      ├── metrics_3d.py      ← 3D 指标计算
                      └── roi_processor.py   ← ROI 坐标系对齐
```

---

## 2. 目录结构

```
eval_tools/
├── core/
│   ├── eval.py                         # 主评测脚本
│   ├── run_eval_with_config.sh         # 单模型评测入口（当前默认入口）
│   ├── run_eval.sh                     # 早期版本入口（无配置文件）
│   ├── run_eval_2d_only.sh             # 仅 2D 评测
│   ├── run_eval_3d_only.sh             # 仅 3D 评测
│   └── run_evaluation_example.sh       # 示例脚本
│
├── configs/
│   ├── eval_config_mono3d-roi0.yaml        # mono3d 模型 ROI0 配置
│   ├── eval_config_mono3d-roi1.yaml        # mono3d 模型 ROI1 配置
│   ├── eval_config_yolov5s-roi0.yaml       # yolov5s 模型 ROI0 配置
│   ├── eval_config_yolov5s-roi1.yaml       # yolov5s 模型 ROI1 配置
│   ├── eval_config_yolov5s_cncap-roi0.yaml # yolov5s CNCAP 测试集 ROI0（当前默认）
│   └── eval_config_yolov5s_cncap-roi1.yaml # yolov5s CNCAP 测试集 ROI1
│
├── evaluator/
│   ├── __init__.py
│   ├── evaluator.py       # 主评测器（数据加载、调度、报告生成）
│   ├── parser.py          # 真值 / 检测结果解析器
│   ├── matcher.py         # 2D IoU 匹配器
│   ├── metrics_2d.py      # 2D 指标计算（P/R/AP/mAP）
│   ├── metrics_3d.py      # 3D 指标计算（Lat/Long/Heading）
│   └── roi_processor.py   # ROI GT 处理器
│
├── model_comparison/
│   ├── find_common_matches.py           # 找出两模型共同匹配的 GT
│   ├── compare_models.py                # 生成双模型对比报告
│   ├── compare_models_with_common_matches.sh  # 一键双模型对比脚本
│   ├── generate_eval_report.py          # 从 JSON 生成 Markdown 评测报告
│   ├── generate_comparison_report.py    # 生成对比 Markdown 报告
│   └── ...
│
├── heading_analysis/
│   ├── extract_bad_heading_cases.py     # 提取 heading 误差大的案例
│   ├── visualize_heading_errors.py      # 可视化 heading 误差（BEV/图像/极坐标）
│   └── ...
│
├── visualization/
│   └── test_val_visualize_from_paths.py # 从路径可视化检测结果
│
├── utilities/
│   ├── check_img_exists.py              # 检查图像文件是否存在
│   └── extract_video_frames.py          # 视频帧提取
│
└── docs/                                # 详细设计文档（本文件所在目录）
```

---

## 3. 核心流程

### 单模型评测（`run_eval_with_config.sh`）

```
┌─────────────────────────────────────────────────────┐
│  run_eval_with_config.sh                            │
│                                                     │
│  1. 设置 PYTHONPATH                                  │
│  2. 指定配置文件路径 (MODEL_CONFIG)                   │
│  3. 指定输出目录  (OUTPUT_BASE/MODEL_NAME/TIMESTAMP) │
│  4. 调用 eval_tools/core/eval.py                    │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│  eval.py                                            │
│                                                     │
│  1. 解析 YAML 配置 + 命令行参数                       │
│  2. 初始化 Evaluator（含 ROIProcessor）              │
│  3. 加载检测结果 & 真值文件对                         │
│  4. 并行处理每张图 (IoU 匹配 + 指标统计)              │
│  5. 汇总指标并生成报告                                │
└─────────────────────────────────────────────────────┘
                        │
           ┌────────────┴─────────────┐
           ▼                          ▼
  evaluation_report.json      detailed_3d_matches.json
  evaluation_report.txt       (--save-detailed-matches)
  per_case_reports/
```

### 双模型对比（`compare_models_with_common_matches.sh`）

```
Model 1 评测 → detailed_3d_matches.json
                                        ┐
                                        ├─ find_common_matches.py → common_matches.json
                                        │
Model 2 评测 → detailed_3d_matches.json ┘
                                        │
                                        └─ compare_models.py → 对比报告
```

---

## 4. 配置文件说明

配置文件位于 `eval_tools/configs/`，YAML 格式，分以下几个部分：

### 4.1 数据集路径 (`dataset`)

```yaml
dataset:
  det_path: "/data1/.../evalset_roi0"  # 检测结果根目录（含 case 文件夹）
  gt_path:  "/data1/xdzhu/Testdata"    # 真值标签根目录（含 case 文件夹）
  path_depth: 1       # 目录层级：1 = det_path/case/txt_results
                      #           2 = det_path/level1/case/txt_results
  det_format: "json"  # 检测结果格式：auto / json / txt
  gt_format:  "json"  # 真值格式：auto / json / txt
```

**目录结构要求（`path_depth: 1`）**：
```
det_path/
└── case_019b178d/
    └── json_results/   ← det_format="json"
        ├── 000000.json
        └── 000001.json

gt_path/
└── case_019b178d/
    └── labels_json/    ← gt_format="json"
        ├── 000000.json
        └── 000001.json
```

### 4.2 图像尺寸 (`image`)

```yaml
image:
  width:  1920
  height: 1080
```

### 4.3 模型配置与 GT 过滤 (`model`)

```yaml
model:
  input_size: 704               # 模型输入宽度（像素）
  min_box_size_at_input_scale: 8  # 模型输入分辨率下的最小框尺寸
  # GT 过滤阈值自动计算：min_box_size = 8 * roi_width / 704
  # ROI0 (1920→704): ≈ 21.8 像素；ROI1 (704→704): 8 像素
```

### 4.4 并行性能 (`performance`)

```yaml
performance:
  num_workers: 32   # 并行 worker 数（null = auto-detect CPU 核数）
```

### 4.5 ROI GT 处理 (`roi_gt`)

```yaml
roi_gt:
  enabled: true
  calib_root: "/data1/xdzhu/Testdata"  # 标定文件根目录（含 camera4.json）
  roi_config: [1920, 960]              # ROI 配置，与训练保持一致
  # ROI0: [1920, 960]
  # ROI1: [704, 352]
```

> **重要**：`roi_config` 必须与训练时的 ROI 配置完全一致，否则坐标系不对齐，IoU 计算将不准确。

### 4.6 类别定义 (`classes`)

```yaml
classes:
  3d_classes: [0, 1, 2, 3]    # 参与 3D 评测的类别
  2d_classes: [4, 5, ..., 13]  # 仅参与 2D 评测的类别
  class_names:
    0: "vehicle"
    1: "pedestrian"
    ...
    13: "tricycle"
```

### 4.7 匹配参数 (`matching`)

```yaml
matching:
  iou_threshold: 0.5   # 2D 匹配 IoU 阈值
```

### 4.8 2D 指标 (`metrics_2d`)

```yaml
metrics_2d:
  enabled: true
  conf_threshold: 0.4      # Precision/Recall 置信度阈值
  ap_method: "voc2010"     # AP 计算方法：voc2010（11点插值）/ coco（全点插值）
```

### 4.9 3D 指标 (`metrics_3d`)

```yaml
metrics_3d:
  enabled: true
  heading_tolerance: "both"  # strict / relaxed / both
  distance_ranges:           # 纵向距离区间（米）
    - [0, 10]
    - [10, 20]
    - ...
    - [100, 999]
  lateral_distance_ranges:   # 横向距离区间（米，x 轴）
    - [-50, -40]
    - ...
    - [40, 50]
```

**`heading_tolerance` 说明**：
| 值 | 含义 |
|---|---|
| `strict` | 标准计算（默认）|
| `relaxed` | 对称物体允许 180° 对称：`error = min(error, π - error)` |
| `both` | 同时计算并输出 strict 和 relaxed 两套结果 |

### 4.10 输出配置 (`output`)

```yaml
output:
  save_path: "evaluation_results/my_model/{timestamp}"
  formats: ["json", "txt"]
  print_details: true
  per_case_reports: true
```

---

## 5. 命令行参数说明

`eval_tools/core/eval.py` 支持以下参数（命令行参数优先级高于配置文件）：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--config` | str | — | YAML 配置文件路径 |
| `--det-path` | str | — | 检测结果根目录 |
| `--gt-path` | str | — | 真值标签根目录 |
| `--path-depth` | int | 1 | 目录层级（1 或 2）|
| `--det-format` | str | auto | 检测结果格式（auto/json/txt）|
| `--gt-format` | str | auto | 真值格式（auto/json/txt）|
| `--output-dir` | str | eval_results | 输出目录 |
| `--img-width` | int | 1920 | 图像宽度（像素）|
| `--img-height` | int | 1080 | 图像高度（像素）|
| `--iou-threshold` | float | 0.5 | IoU 匹配阈值 |
| `--conf-threshold` | float | 0.5 | 置信度阈值 |
| `--ap-method` | str | voc2010 | AP 计算方法（voc2010/coco）|
| `--heading-tolerance` | str | strict | heading 容忍模式（strict/relaxed/both）|
| `--num-workers` | int | auto | 并行 worker 数 |
| `--eval-2d-only` | flag | — | 仅评测 2D |
| `--eval-3d-only` | flag | — | 仅评测 3D |
| `--save-detailed-matches` | flag | — | 保存详细 3D 匹配信息（供模型对比使用）|

---

## 6. 数据格式

### 6.1 真值（Ground Truth）格式

**车辆类别（50 个值）**：
```
[class, x, y, w, h,                          # 0-4: 类别 + 归一化 2D 框
 x3d, y3d, z3d,                              # 5-7: 3D 中心点（相机坐标系）
 l, h, w,                                   # 8-10: 3D 尺寸（长高宽）
 rot_y,                                      # 11: 绕 Y 轴旋转角
 xc, yc,                                     # 12-13: 3D 中心点的图像投影
 xc_d, yc_d,                                 # 14-15: 深度相关投影
 alpha,                                      # 16: 观测角
 0,                                          # 17: 占位符
 前面(x3d,y3d,z3d,alpha,xc,yc,score,occ),    # 18-25
 后面(x3d,y3d,z3d,alpha,xc,yc,score,occ),    # 26-33
 左面(x3d,y3d,z3d,alpha,xc,yc,score,occ),    # 34-41
 右面(x3d,y3d,z3d,alpha,xc,yc,score,occ)]    # 42-49
```

**行人/自行车/骑手（18 个值）**：
上述 0-17，无四面信息。

**仅 2D 标注（6 个值）**：
```
[class, x, y, w, h, -1]
```

### 6.2 检测结果格式

**车辆（15 个字段）**：
```
vehicle  0.95  368.08 574.17 437.89 617.20  cam  -30.14 1.43 68.55  5.52 2.50 2.31  2.70  left
label    conf  x1     y1     x2     y2       cs   x3d    y3d  z3d    l    h    w     rot_y face_type
```
`face_type` 取值：`front` / `back`（或 `rear`/`tail`）/ `left` / `right`

**行人/骑手等（15 个字段）**：同上，`face_type` 固定为 `whole`。

**纯 2D 类别（6 个字段）**：
```
plate  0.94246  532.12 203.26 558.73 214.86
label  conf     x1     y1     x2     y2
```

---

## 7. 评测指标

### 7.1 2D 检测指标

- **Precision**：TP / (TP + FP)，按 `conf_threshold` 过滤
- **Recall**：TP / (TP + FN)
- **F1-Score**：2 × P × R / (P + R)
- **AP**：PR 曲线下面积（IoU 阈值 0.5）
- **mAP**：所有类别 AP 的算术平均

**匹配规则**：
1. 按置信度从高到低排序预测框
2. 与真值框 IoU ≥ 0.5 且类别相同 → TP（每个真值框只匹配一次）
3. 未匹配预测框 → FP；未被匹配真值框 → FN

**类别划分（14 类）**：

| ID | 类别 | 3D 评测 |
|----|------|---------|
| 0 | vehicle | ✓ |
| 1 | pedestrian | ✓ |
| 2 | bicycle | ✓ |
| 3 | rider | ✓ |
| 4 | roadblock | — |
| 5 | head | — |
| 6 | tsr | — |
| 7 | guideboard | — |
| 8 | plate | — |
| 9 | wheel | — |
| 10 | tl_border | — |
| 11 | tl_wick | — |
| 12 | tl_num | — |
| 13 | tricycle | — |

### 7.2 3D 检测指标

> 前提：2D IoU 匹配成功（≥ 0.5）且真值包含完整 3D 标注。

**车辆类别**（基于最近面中心点对比）：

根据检测结果的 `face_type` 字段，在真值中选取对应面的中心点进行比较：
```
face_type → 真值面中心点索引
  front  →  [18, 19, 20]  (x3d, y3d, z3d)
  back   →  [26, 27, 28]
  left   →  [34, 35, 36]
  right  →  [42, 43, 44]
```

**行人/骑手/自行车**：使用整体中心点 `[5, 6, 7]` 进行比较。

**误差指标**：
- **横向误差（Lateral Error）**：`|x3d_pred - x3d_gt|`（米）
- **纵向误差（Longitudinal Error）**：`|z3d_pred - z3d_gt|`（米）
- **Heading 误差**：`|rot_y_pred - rot_y_gt|`（弧度）

每个指标输出：均值（Mean）、中位数（Median）、标准差（Std）、90 百分位数（P90）。

---

## 8. ROI GT 处理

### 动机

训练时图像经过 ROI 裁剪和缩放（坐标系改变），但历史评测代码中检测结果在 ROI 坐标系，GT 在原图坐标系，导致 IoU 计算不准确。

### 解决方案

`ROIProcessor`（`eval_tools/evaluator/roi_processor.py`）在评测时对 GT 标签执行与训练完全相同的 ROI 处理：

1. 读取标定文件（`case_root/camera4.json`）中的 `focal_u, focal_v, cu, cv, pitch`
2. 计算裁剪中心：`cx = oriW // 2`，`cy = cv - focal_v × tan(pitch × π/180)`
3. 以 `(cx, cy)` 为中心按 `roi_config` 裁剪 ROI
4. 过滤完全在 ROI 外的目标；将部分在 ROI 内的框 clip 到边界
5. 将坐标转换到 ROI 相对坐标系 → 再缩放到模型输入分辨率

**配置对应关系**：
| 训练 ROI 配置 | `roi_config` 值 |
|---|---|
| ROI0（大 crop） | `[1920, 960]` |
| ROI1（小 crop） | `[704, 352]` |

---

## 9. 模型对比（共同匹配集）

### 问题背景

直接比较两个模型的 3D 指标时，若双方匹配到的 GT 对象数量不同（如相差 11.7%），差异可能来自**匹配集差异**而非模型质量。

### 解决方案

只统计两个模型**都成功匹配**的 GT 对象（Common Matches）的 3D 指标。

### 使用方式

#### 方式一：一键脚本（推荐）

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

该脚本自动完成：
1. 评测 Model 1，保存 `detailed_3d_matches.json`
2. 评测 Model 2，保存 `detailed_3d_matches.json`
3. 调用 `find_common_matches.py` 得到 `common_matches.json`
4. 调用 `compare_models.py` 生成对比报告
5. 调用 `generate_eval_report.py` 为各模型生成 Markdown 报告

#### 方式二：手动分步执行

```bash
# Step 1: 评测两个模型
python eval_tools/core/eval.py \
  --config eval_tools/configs/eval_config_mono3d-roi1.yaml \
  --output-dir eval_results/model1 \
  --heading-tolerance both \
  --save-detailed-matches

python eval_tools/core/eval.py \
  --config eval_tools/configs/eval_config_yolov5s_cncap-roi1.yaml \
  --output-dir eval_results/model2 \
  --heading-tolerance both \
  --save-detailed-matches

# Step 2: 找出共同匹配
python eval_tools/model_comparison/find_common_matches.py \
  --model1-matches eval_results/model1/detailed_3d_matches.json \
  --model2-matches eval_results/model2/detailed_3d_matches.json \
  --output eval_results/common_matches.json \
  --model1-name "mono3d" \
  --model2-name "yolov5s-300w"

# Step 3: 生成对比报告
python eval_tools/model_comparison/compare_models.py \
  --model1 eval_results/model1/evaluation_report.json \
  --model2 eval_results/model2/evaluation_report.json \
  --common-matches eval_results/common_matches.json \
  --output-dir eval_results/comparison \
  --model1-name "mono3d" \
  --model2-name "yolov5s-300w"
```

### 生成 Markdown 报告

```bash
python eval_tools/model_comparison/generate_eval_report.py \
  eval_results/model1/evaluation_report.json \
  --model "yolov5s-300w-cncap" \
  --date 2026-03-03
```

输出：`eval_results/model1/EVALUATION_REPORT.md`

---

## 10. Heading 误差分析

对于 heading 预测较差的案例，可使用以下工具进行深入分析：

### Step 1：提取 bad cases

```bash
python eval_tools/heading_analysis/extract_bad_heading_cases.py \
  --input eval_results/model1/detailed_3d_matches.json \
  --threshold 1.5 \      # heading 误差阈值（弧度）
  --top-k 100 \
  --output bad_heading.json \
  --stats
```

### Step 2：可视化

```bash
python eval_tools/heading_analysis/visualize_heading_errors.py \
  --input bad_heading.json \
  --image-root /path/to/images \
  --output runs/heading_viz \
  --viz-types bev image angle combined
```

可视化类型：
- `bev`：鸟瞰图（GT / Pred 的 3D 框 + 方向箭头）
- `image`：原图视图（2D 框 + 误差标注）
- `angle`：角度分析（极坐标 + 柱状图）
- `combined`：四宫格综合视图

---

## 11. 输出结果

### 11.1 文件列表

| 文件 | 说明 |
|------|------|
| `evaluation_report.json` | 完整评测报告（JSON 格式，含所有类别和距离区间）|
| `evaluation_report.txt` | 人类可读的文本报告 |
| `detailed_3d_matches.json` | 每帧每目标的 3D 匹配详情（`--save-detailed-matches`）|
| `per_case_reports/*.json` | 每个 case 的独立报告（`per_case_reports: true`）|
| `EVALUATION_REPORT.md` | Markdown 格式摘要报告（由 `generate_eval_report.py` 生成）|

### 11.2 JSON 报告结构

```json
{
  "evaluation_config": {...},
  "2d_evaluation": {
    "overall": {
      "precision": 0.85,
      "recall": 0.78,
      "f1_score": 0.81,
      "map": 0.72
    },
    "per_class": {
      "vehicle": {"precision": ..., "recall": ..., "ap": ...},
      ...
    }
  },
  "3d_evaluation": {
    "vehicle": {
      "overall": {
        "n_samples": 440408,
        "lateral_mean": 0.647,
        "longitudinal_mean": 1.680,
        "heading_mean_strict": 0.258
      },
      "by_distance": {
        "[0-10m]": {...},
        ...
      }
    }
  }
}
```

### 11.3 控制台输出示例

```
3D Metrics:
  vehicle [overall]: Lat=0.647m, Long=1.680m, Head=0.258rad (n=440408)
    [0-10m]:   Lat=0.423m, Long=0.891m, Head=0.153rad (n=98241)
    [10-20m]:  Lat=0.501m, Long=1.203m, Head=0.177rad (n=142038)
    [30-60m]:  Lat=1.149m, Long=5.074m, Head=0.607rad (n=18432)
    [100-999m]:Lat=2.341m, Long=9.221m, Head=1.036rad (n=871)
```

---

## 12. 使用示例

### 例 1：单模型评测（当前默认入口）

```bash
cd /deeplearning_team/ydong/dongying/projects/yolov5-3d
conda activate slot

bash eval_tools/core/run_eval_with_config.sh
```

脚本使用 `eval_tools/configs/eval_config_yolov5s_cncap-roi0.yaml`，结果保存至：
```
evaluation_results/eval_results_common_match_comparison_cncap_yolov5s_20260303_roi0/
└── yolov5s-300w-newdata-cncap-test/
    └── 20260303_HHMMSS/
        ├── evaluation_report.json
        ├── evaluation_report.txt
        └── detailed_3d_matches.json
```

### 例 2：命令行直接评测（不使用配置文件）

```bash
python eval_tools/core/eval.py \
  --det-path /data1/.../inference_results/model/evalset_roi0 \
  --gt-path  /data1/xdzhu/Testdata \
  --output-dir evaluation_results/my_test \
  --heading-tolerance both \
  --conf-threshold 0.4 \
  --num-workers 16
```

### 例 3：仅 2D 评测

```bash
python eval_tools/core/eval.py \
  --config eval_tools/configs/eval_config_yolov5s_cncap-roi0.yaml \
  --eval-2d-only \
  --output-dir evaluation_results/2d_only_test
```

### 例 4：双模型对比

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

### 例 5：修改配置直接运行

仅修改 `run_eval_with_config.sh` 中的以下三个变量即可适配新模型：

```bash
MODEL_CONFIG="eval_tools/configs/eval_config_yolov5s_cncap-roi0.yaml"
OUTPUT_BASE="evaluation_results/eval_results_my_model"
MODEL_NAME="my-model-name"
```

---

## 13. 常见问题

### Q1：No image pairs found

**原因**：`det_path` 与 `gt_path` 下的 case 名称不匹配，或 `det_format` / `gt_format` 设置错误。

**排查**：
```bash
ls ${det_path}/        # 查看 case 目录名
ls ${det_path}/case_xxx/  # 查看是 json_results/ 还是 txt_results/
```

### Q2：IoU 始终为 0，评测指标异常

**原因**：`roi_gt` 配置未启用，或 `roi_config` 与训练时不匹配，导致坐标系不对齐。

**排查**：检查配置中 `roi_gt.enabled: true` 且 `roi_config` 与训练 YAML 中的 `roi:` 字段一致。

### Q3：3D 指标样本数 (n=0)

**原因**：真值中该类别无完整 3D 标注（仅有 6 维的 2D-only 标注），或 2D 匹配 IoU < 0.5。

### Q4：如何添加新模型配置

复制现有配置文件，仅修改 `dataset.det_path` 和 `dataset.gt_path` 即可：
```bash
cp eval_tools/configs/eval_config_yolov5s_cncap-roi0.yaml \
   eval_tools/configs/eval_config_my_model-roi0.yaml
# 编辑新文件中的 det_path 和 output.save_path
```

### Q5：如何加速评测

调大 `performance.num_workers`（建议不超过 CPU 核数 × 2）：
```bash
python eval_tools/core/eval.py --config ... --num-workers 64
```

---

*文档生成日期：2026-03-03*