yolov26_3d/eval_tools/docs/EVALSET_CONSTRUCTION_GUIDE.md

# 评测集构建方案

> 适用模型：YOLOv5-3D 单目3D检测模型
> 评测框架：`eval_tools/core/eval.py`
> 文档日期：2026-03-10

---

## 目录

1. [构建目标与原则](#1-构建目标与原则)
2. [类别体系与评测维度](#2-类别体系与评测维度)
3. [场景覆盖设计](#3-场景覆盖设计)
4. [2D 类别评测集构建](#4-2d-类别评测集构建)
5. [3D 类别评测集构建](#5-3d-类别评测集构建)
6. [样本量估算](#6-样本量估算)
7. [标注要求](#7-标注要求)
8. [数据集组织结构](#8-数据集组织结构)
9. [质量验证流程](#9-质量验证流程)
10. [已有数据利用建议](#10-已有数据利用建议)

---

## 1. 构建目标与原则

### 1.1 核心目标

评测集的作用是**客观衡量模型在真实场景中的性能，并定位模型的薄弱环节**。需达到：

- **代表性**：覆盖部署场景的主要驾驶条件（城市/高速/路口）
- **诊断性**：能区分距离远近、遮挡程度、heading 朝向等子条件下的性能差异
- **稳定性**：同一模型多次评测结果误差 < 0.5%（样本量足够）
- **公平性**：与训练集严格不重叠；跨版本模型在同一评测集上可横向对比

### 1.2 构建原则

| 原则 | 说明 |
|------|------|
| **不重叠** | 评测集视频/序列与训练集完全隔离 |
| **场景多样** | 按场景类型、时段、天气分层采样，避免单一场景主导指标 |
| **数量门控** | 每个子评测维度 GT 实例数 ≥ 200（否则指标置信区间过大）|
| **标注一致** | 标注规范与训练数据一致（47 维格式，坐标系相同）|
| **固定不变** | 评测集发布后不修改，模型迭代复用同一评测集 |

---

## 2. 类别体系与评测维度

### 2.1 14 类别分组

```
┌─ 3D 类别（同时参与 2D + 3D 评测）────────────────────────────────────────┐
│  ID 0  vehicle      - 车辆（含四面 3D 标注）                              │
│  ID 1  pedestrian   - 行人                                               │
│  ID 2  bicycle      - 自行车（无人骑行）                                  │
│  ID 3  rider        - 骑行者（人+车整体）                                 │
│  ID 13 tricycle     - 三轮车（标注同 vehicle，但评测框架归入 2D-only）     │
└───────────────────────────────────────────────────────────────────────────┘
┌─ 2D-only 类别（仅参与 2D 评测）──────────────────────────────────────────┐
│  ID 4  roadblock    - 路障/锥桶                                           │
│  ID 5  head         - 人头（行人头部）                                    │
│  ID 6  tsr          - 交通标志（Traffic Sign Recognition）                │
│  ID 7  guideboard   - 导向标牌                                            │
│  ID 8  plate        - 车牌                                                │
│  ID 9  wheel        - 车轮                                                │
│  ID 10 tl_border    - 信号灯外框                                          │
│  ID 11 tl_wick      - 信号灯灯芯                                          │
│  ID 12 tl_num       - 信号灯数字/倒计时                                   │
└───────────────────────────────────────────────────────────────────────────┘
```

> **注意**：tricycle(13) 虽有 3D 标注能力，但当前评测框架 `3d_classes: [0,1,2,3]` 未纳入 3D 评测。
> 评测集构建时仍需为 tricycle 提供完整 3D 标注，以便未来扩展。

### 2.2 评测维度矩阵

| 评测维度 | 适用类别 | 关键子维度 |
|----------|----------|------------|
| 2D 检测（P/R/AP/mAP） | 全部 14 类 | 场景类型、目标大小、遮挡程度 |
| 3D 横向误差（Lateral） | vehicle, pedestrian, bicycle, rider | 纵向距离区间、横向位置区间 |
| 3D 纵向误差（Longitudinal） | 同上 | 纵向距离区间（近/中/远/极远）|
| 3D 朝向误差（Heading） | 同上 | heading 朝向、strict vs relaxed |
| Cut-in/Cut-out | vehicle | 变道类型（正常/切入/切出）|
| 时序稳定性 | vehicle, pedestrian | 帧间误差方差、跟踪连续性 |

---

## 3. 场景覆盖设计

### 3.1 场景分类

评测集按场景类型分层，确保每类场景都有足够的 GT 实例：

```
评测集场景分层
├── A. 城市道路（Urban）
│   ├── A1. 主干道直行（高密度车辆，低速）
│   ├── A2. 路口（交叉行驶、遮挡多）
│   └── A3. 人行道/自行车道（行人、骑手密集）
│
├── B. 高速/快速路（Highway）
│   ├── B1. 直线段（高速车辆，大距离）
│   ├── B2. 匝道（cut-in/cut-out 频繁）
│   └── B3. 跟车场景（近距离前车，heading 接近 0）
│
├── C. 园区/停车场（Parking/Campus）
│   ├── C1. 低速场景（行人横穿，自行车）
│   └── C2. 密集停车（遮挡车辆，heading 多样）
│
├── D. 光照/天气专项
│   ├── D1. 夜间（路灯/车灯为主要光源）
│   ├── D2. 黄昏/逆光（日落逆光，曝光过渡）
│   └── D3. 雨天（反光路面，视线模糊）
│
└── E. 长尾场景专项
    ├── E1. 极远距离目标（z > 80m）
    ├── E2. 极侧向目标（|x| > 20m）
    ├── E3. 大遮挡目标（2D box 被遮 > 50%）
    └── E4. 非常规朝向（侧面、斜向）
```

### 3.2 场景比例建议

| 场景类型 | 帧数占比 | 说明 |
|----------|---------|------|
| A. 城市道路 | 40% | 最常见部署场景 |
| B. 高速/快速路 | 30% | 大距离 3D 精度关键场景 |
| C. 园区/停车场 | 10% | heading 多样性 |
| D. 光照/天气专项 | 15% | 鲁棒性测试 |
| E. 长尾专项 | 5% | 边界性能测试 |

---

## 4. 2D 类别评测集构建

### 4.1 各类别覆盖要求

#### 高频核心类别（> 2000 GT 实例）

| 类别 | 最低 GT 实例数 | 关键覆盖点 |
|------|--------------|------------|
| vehicle(0) | 5000+ | 近/中/远距离各 1/3；正面/侧面/背面均衡 |
| pedestrian(1) | 3000+ | 单人/群体；站立/行走/奔跑；正面/背面 |
| bicycle(2) | 1000+ | 有人骑行与无人停放；不同角度 |
| rider(3) | 1000+ | 自行车骑手、摩托骑手；不同速度 |
| head(5) | 2000+ | 与 pedestrian 同帧（头部检测辅助）|

#### 中频类别（> 500 GT 实例）

| 类别 | 最低 GT 实例数 | 关键覆盖点 |
|------|--------------|------------|
| roadblock(4) | 500+ | 锥桶、水马、隔离墩；单个与成排 |
| tsr(6) | 800+ | 限速牌、禁止牌、指示牌；远近各半 |
| plate(8) | 1000+ | 前牌/后牌；清晰/模糊/遮挡；不同距离 |
| wheel(9) | 1000+ | 与 vehicle 强关联；不同视角 |
| tricycle(13) | 300+ | 电动三轮、货运三轮；正面/侧面 |

#### 低频类别（> 200 GT 实例）

| 类别 | 最低 GT 实例数 | 关键覆盖点 |
|------|--------------|------------|
| guideboard(7) | 200+ | 高速路导向牌；城市路名牌 |
| tl_border(10) | 300+ | 路口信号灯；不同距离 |
| tl_wick(11) | 300+ | 红/绿/黄灯芯；清晰/模糊 |
| tl_num(12) | 200+ | 倒计时数字；不同亮度 |

### 4.2 2D 类别质量控制指标

每个类别评测集应覆盖如下目标尺寸分布（在 ROI 裁剪后的坐标系中）：

| 尺寸分级 | 框边长范围（像素） | 占比建议 |
|----------|-------------------|---------|
| 小目标 | 8 ~ 32 px | 20% |
| 中目标 | 32 ~ 96 px | 50% |
| 大目标 | > 96 px | 30% |

**遮挡程度分布**：

| 遮挡等级 | 定义 | 占比建议 |
|----------|------|---------|
| 无遮挡 | 目标全部可见 | 50% |
| 轻度遮挡 | 20%~50% 被遮挡 | 35% |
| 重度遮挡 | > 50% 被遮挡 | 15% |

---

## 5. 3D 类别评测集构建

3D 类别评测集在 2D 要求基础上，需额外覆盖以下维度。

### 5.1 纵向距离分布要求

按评测框架的距离区间（z 轴，单位米）：

| 区间 | 最低 GT 实例数 | 说明 |
|------|--------------|------|
| 0 ~ 10 m | 300+ | 近距离精度（纵向误差应 < 0.5m）|
| 10 ~ 20 m | 500+ | 城市最常用区间 |
| 20 ~ 30 m | 500+ | — |
| 30 ~ 40 m | 400+ | 中距离 |
| 40 ~ 50 m | 300+ | — |
| 50 ~ 60 m | 200+ | — |
| 60 ~ 80 m | 200+ | 远距离（高速场景）|
| 80 ~ 100 m | 100+ | — |
| > 100 m | 100+ | 极远（vehicle 为主）|

> 行人、自行车、骑手在 > 60m 处往往分辨率不足，**60m 以内为核心评测区间**。

### 5.2 横向位置分布要求

按 x3d 轴（正右为正）：

| 区间 | 最低 GT 实例数 | 说明 |
|------|--------------|------|
| -20 ~ -10 m | 200+ | 对向车道 |
| -10 ~ 0 m | 400+ | 本车左侧 |
| 0 ~ 10 m | 400+ | 本车右侧 |
| 10 ~ 20 m | 200+ | 相邻车道 |
| \|x\| > 20 m | 100+ | 极侧向（长尾）|

> **已知问题**：U 坐标误差在 |x3d| > 10m 时显著增大（见 CALIBRATION_ADJUSTMENT_VERIFICATION.md）。
> 评测集需确保极侧向样本数 ≥ 100，专门监控该区间的 3D 精度退化。

### 5.3 Heading 朝向分布要求

车辆朝向（rot_y）编码规则：`rot_y = -π/2` 表示正向行驶。
评测集需覆盖各朝向区间：

| 朝向区间 | 描述 | 最低 GT 实例数 |
|----------|------|--------------|
| [-π/2 ± π/8] | 正向行驶（同向）| 1000+ |
| [π/2 ± π/8]  | 反向行驶（对向）| 500+ |
| [0 ± π/8]    | 正侧向（左侧停车/侧向行驶）| 200+ |
| [π ± π/8]    | 负侧向（右侧停车/侧向行驶）| 200+ |
| 其他（斜向）   | 45° 斜向行驶/泊车 | 300+ |

### 5.4 Cut-in/Cut-out 场景（vehicle 专项）

| Cut 类型 | 描述 | 最低帧序列数 | 最低 GT 实例数 |
|----------|------|------------|--------------|
| 正常（label=0） | 直线行驶 | — | 2000+ |
| Cut-in（label=1） | 从侧面切入本车道 | 30+ 序列 | 500+ |
| Cut-out（label=2） | 从本车道切出 | 30+ 序列 | 300+ |

> **Cut-in/Cut-out 标注要求**：连续视频片段，切变过程完整，含后面+左右面的可见性标注。

### 5.5 各 3D 类别专项要求

#### vehicle（ID=0）—— 最重要的 3D 类别

| 子场景 | 最低样本 |
|--------|---------|
| 近距正向跟车（z < 20m，前面可见）| 500+ |
| 中距侧向超车（20m < z < 60m，侧面可见）| 400+ |
| 远距正向（z > 60m，整体预测为主）| 300+ |
| 对向来车（rot_y ≈ π/2，后面可见）| 300+ |
| 停放车辆（低速/静止，heading 多样）| 200+ |

**四面可见性分布**（面向 vehicle 的 facecls 评测）：

| 面类型 | 最低可见实例数 |
|--------|--------------|
| 前面（front） | 800+ |
| 后面（rear/back） | 600+ |
| 左侧面（left） | 400+ |
| 右侧面（right） | 400+ |

#### pedestrian（ID=1）

| 子场景 | 最低样本 |
|--------|---------|
| 路边站立/行走（z < 30m）| 600+ |
| 横穿马路（侧向 heading）| 300+ |
| 群体行人（遮挡严重）| 200+ |
| 夜间行人 | 200+ |

#### bicycle（ID=2）& rider（ID=3）

| 子场景 | 最低样本（bicycle/rider 合计）|
|--------|------------------------------|
| 单独骑行（z < 30m）| 400+ |
| 多辆并排 | 200+ |
| 侧向穿越 | 150+ |
| 夜间（有灯/无灯）| 150+ |

---

## 6. 样本量估算

### 6.1 总体规模建议

| 评测类型 | 推荐帧数 | 估算 GT 总实例数 |
|----------|---------|----------------|
| **轻量评测集**（快速迭代）| 2,000 帧 | ~15,000 GT |
| **标准评测集**（版本发布）| 8,000 帧 | ~60,000 GT |
| **全量评测集**（深度分析）| 20,000 帧 | ~150,000 GT |

> 建议维护**标准评测集**作为日常基准，**轻量评测集**作为开发快速验证（从标准集均匀抽样）。

### 6.2 帧采样策略

```
原始视频序列
    │
    ▼ 按场景类型分层采样
按 1~3 fps 稀疏采样（避免相邻帧过度相关）
    │
    ▼ 剔除：
    ├── 图像模糊（运动模糊、对焦失败）
    ├── 无目标帧（全图无任何 GT 实例）
    └── 极端曝光（过曝/欠曝）
    │
    ▼ 确保：
    ├── 每个 case（视频片段）≥ 50 帧（保证时序分析可用）
    └── 每个 case ≤ 500 帧（单 case 不主导总体指标）
```

---

## 7. 标注要求

### 7.1 标注格式

完全遵循训练数据格式（见 CLAUDE.md 3D Label Format 章节）：

| 类别 | 标注维度 | 说明 |
|------|---------|------|
| vehicle, tricycle | **50 维**（含 4 面） | 类别 + 2D + 3D整体 + 前/后/左/右面 |
| pedestrian, bicycle, rider | **18 维** | 类别 + 2D + 3D整体（无面信息）|
| 2D-only 类别 | **6 维** | 类别 + 2D bbox + 占位 -1 |

### 7.2 3D 标注质量要求

#### 精度要求（针对 vehicle）

| 标注项 | 精度要求 |
|--------|---------|
| z3d（纵向深度）| ±0.5 m（z < 50m），±2 m（50m < z < 100m）|
| x3d（横向位置）| ±0.3 m |
| y3d（垂直位置）| ±0.2 m |
| l/h/w（尺寸）| ±0.1 m |
| rot_y（朝向）| ±0.1 rad（约 6°）|
| xc/yc（投影中心）| ±3 px |

#### 面可见性标注规则

`is_visible_from_camera`（dim 22/30/38/46）标注规则：

```
面可见性 = 1：面的法向量朝向摄像机一侧（面可被相机正面看到）
面可见性 = 0：面的法向量背向摄像机（背面，被遮蔽）

经验规则：
- 同向行驶车辆：后面=1，前面=0，左右面视横向位置定
- 对向来车：前面=1，后面=0
- 侧向行驶（|rot_y - 0| < π/4）：左面或右面=1，视具体朝向
```

#### Cut-in/Cut-out 标注规则

`cut_class`（dim38~40 的索引）：

| 标注值 | 含义 | 标注判断依据 |
|--------|------|------------|
| 0 | 正常行驶 | 纵向位移 >> 横向位移 |
| 1 | Cut-in | 目标从侧方向进入本车道，且与本车道有重叠趋势 |
| 2 | Cut-out | 目标从本车道移出，向侧方变道 |

> Cut-in/Cut-out 需**逐帧**标注，连续过程中按实际状态确定每帧的标签。

### 7.3 2D 标注质量要求

- bbox 与目标视觉边界误差 ≤ 3 px（在原图 1920×1080 坐标系）
- 遮挡边界：标注**可见部分**的完整边界框（不推断遮挡物体的完整框）
- 截断处理：目标超出图像边界时，标注图像内可见部分，框至图像边缘

### 7.4 不标注情况（需剔除或标记为 ignore）

- 目标在 ROI 裁剪后边长 < 8 px（模型输入分辨率下）
- 严重模糊、无法辨认类别的目标
- 距离 > 150m 的车辆（标注误差过大）

---

## 8. 数据集组织结构

### 8.1 目录结构

评测集需兼容现有评测框架（`eval_tools/core/eval.py`）的目录规范：

```
evalset/
├── case_001/                    # 场景片段（≥ 50 帧连续视频）
│   ├── images/                  # 原始图像（1920×1080 JPEG/PNG）
│   │   ├── 000000.jpg
│   │   ├── 000001.jpg
│   │   └── ...
│   ├── labels_json/             # GT 标注（JSON 格式，与框架 gt_format 对应）
│   │   ├── 000000.json
│   │   └── ...
│   ├── camera4.json             # 相机标定文件（ROI 处理必需）
│   └── meta.json                # 场景元数据（见 8.2）
│
├── case_002/
│   └── ...
│
└── evalset_meta.json            # 整体评测集元数据
```

> **兼容性说明**：`gt_format: "json"` 对应 `labels_json/` 目录；`gt_format: "txt"` 对应 `labels_0211/` 目录。

### 8.2 场景元数据格式（meta.json）

```json
{
  "case_id": "case_001",
  "scene_type": "urban_intersection",    // 见场景分类 3.1
  "lighting": "day",                     // day / night / dusk / backlight
  "weather": "clear",                    // clear / rain / fog
  "location": "city_A",
  "camera_model": "G1M3",
  "has_3d_annotation": true,
  "frame_range": [0, 299],
  "frame_count": 300,
  "gt_class_distribution": {
    "vehicle": 1200,
    "pedestrian": 340,
    "bicycle": 80
  },
  "special_scenarios": ["cut_in", "night_pedestrian"]
}
```

### 8.3 评测集总元数据（evalset_meta.json）

```json
{
  "version": "v1.0",
  "created": "2026-03-10",
  "total_frames": 8000,
  "total_cases": 80,
  "roi_mode": "ROI1",              // 对应训练时的 ROI 配置
  "roi_config": [704, 320],
  "class_distribution": {
    "vehicle": {"total": 45000, "has_3d": 45000},
    "pedestrian": {"total": 12000, "has_3d": 12000},
    "bicycle": {"total": 4000, "has_3d": 4000},
    "rider": {"total": 3500, "has_3d": 3500},
    "roadblock": {"total": 2000, "has_3d": 0}
  },
  "scene_distribution": {
    "urban": 42,
    "highway": 22,
    "parking": 8,
    "night": 5,
    "rain": 3
  }
}
```

---

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