zhao.zhu/yolov26_3d
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

单目3D初始代码

Browse Source
This commit is contained in:
zhao.zhu
2026-06-24 09:35:46 +08:00
commit 04a5895b6b
1153 changed files with 340700 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

250
eval_tools/docs/CALIBRATION_FILE_FIX_CN.md Executable file
View File

@@ -0,0 +1,250 @@
# 两级路径下校准文件查找问题修复
## 问题描述
运行 `eval_tools/model_comparison/compare_models_with_common_matches.sh` 时出现警告：
```
Warning: Calibration file not found for case seq-27
```
## 问题原因
在启用两级路径结构（`path_depth: 2`）和 ROI 地面真值处理（`roi_gt.enabled: true`）时，ROI processor 需要加载校准文件来计算 ROI 边界。
原有的校准文件查找逻辑只支持一级路径：
```python
# 原有逻辑（仅支持一级路径）
case_calib_path = self.calib_root / case_name / "calib/L2_calib/camera4.json"
```
对于两级路径结构：
```
calib_root/
level1_dir/ # 第一级目录（如 G1M3_AFS1616）
case_name/ # 第二级目录（如 seq-27）
calib/L2_calib/camera4.json
```
原有逻辑会查找：
```
calib_root/seq-27/calib/L2_calib/camera4.json ❌ 错误路径
```
正确路径应该是：
```
calib_root/G1M3_AFS1616/seq-27/calib/L2_calib/camera4.json ✓ 正确路径
```
## 解决方案
### 1. 修改 `evaluator.py`
在 `image_pairs` 中添加 `level1_name` 信息：
```python
self.image_pairs.append({
'case': case_name,
'frame': frame_name,
'det_file': str(det_file),
'gt_file': str(gt_file),
'img_width': img_width,
'img_height': img_height,
'min_box_size': self.min_box_size,
'level1_name': level1_name # 新增：第一级目录名称
})
```
### 2. 修改 `roi_processor.py`
#### 2.1 更新 `load_calibration` 方法
添加 `level1_name` 参数支持：
```python
def load_calibration(self, case_name, frame_name=None, level1_name=None):
"""
加载 case 的校准参数。
Args:
case_name: str, case 标识符
frame_name: str, 可选的帧名称
level1_name: str, 可选的第一级目录名称（用于两级路径结构）
Returns:
dict 包含校准参数: focal_u, focal_v, cu, cv, yaw, pitch, 等
"""
if self.calib_root is None:
return None
# 缓存键包含 level1_name
cache_key = f"{level1_name}/{case_name}" if level1_name else f"{case_name}"
if cache_key in self.calib_cache:
return self.calib_cache[cache_key]
# 根据是否有 level1_name 构建不同的路径
if level1_name:
# 两级路径: calib_root/level1/case/calib/L2_calib/camera4.json
case_calib_path = self.calib_root / level1_name / case_name / "calib/L2_calib/camera4.json"
else:
# 一级路径: calib_root/case/calib/L2_calib/camera4.json
case_calib_path = self.calib_root / case_name / "calib/L2_calib/camera4.json"
# ... 后续处理
```
#### 2.2 更新 `process_case_frame` 方法
添加 `level1_name` 参数：
```python
def process_case_frame(self, case_name, frame_name, annotations, level1_name=None):
"""
处理特定 case 和帧的标注。
Args:
case_name: str, case 标识符
frame_name: str, 帧标识符
annotations: list, 来自 GroundTruthParser 的标注
level1_name: str, 可选的第一级目录名称（用于两级路径结构）
Returns:
tuple: (processed_annotations, roi_bounds) 或 (annotations, None) 如果没有 ROI
"""
if self.roi_config is None:
return annotations, None
# 加载校准参数，传入 level1_name
calib_params = self.load_calibration(case_name, frame_name, level1_name)
# ...
```
### 3. 更新调用点
在 `evaluator.py` 中调用 `process_case_frame` 时传入 `level1_name`：
```python
# Apply ROI processing to ground truth if enabled
if roi_processor is not None:
gts, _ = roi_processor.process_case_frame(
pair['case'],
pair['frame'],
gts,
level1_name=pair.get('level1_name') # 传入 level1_name
)
```
## 修改的文件
1. **eval_tools/evaluator/evaluator.py**
- 在 `load_data_from_paths()` 中添加 `level1_name` 到 `image_pairs`
- 在调用 `process_case_frame()` 时传入 `level1_name`
2. **eval_tools/evaluator/roi_processor.py**
- 更新 `load_calibration()` 方法签名和实现
- 更新 `process_case_frame()` 方法签名和实现
3. **eval_tools/tests/test_roi_processor_2level.py** (新增)
- 测试脚本验证 ROI processor 在两级路径下的功能
## 测试验证
运行测试脚本：
```bash
python eval_tools/tests/test_roi_processor_2level.py
```
测试结果：
```
============================================================
Test Summary
============================================================
1-level structure: ✓ PASSED
2-level structure: ✓ PASSED
✓ All tests passed!
```
## 向后兼容性
- 对于一级路径结构（`path_depth: 1`），`level1_name` 为 `None`，行为与之前完全相同
- 对于两级路径结构（`path_depth: 2`），`level1_name` 包含第一级目录名称，正确构建校准文件路径
- 所有现有配置和脚本无需修改即可继续工作
## 使用示例
### 配置文件设置
```yaml
dataset:
det_path: "/data1/dongying/Mono3d/G1M3/CNCAP_results/mono3d/evalset_roi0"
gt_path: "/mnt/mono3d/xdzhu_data/Mono3d/Mono3d_4face_2m_g1m3/driving_png/G1M3_AFS1616"
path_depth: 2 # 启用两级路径
roi_gt:
enabled: true
calib_root: "/mnt/mono3d/xdzhu_data/Mono3d/Mono3d_4face_2m_g1m3/driving_png/G1M3_AFS1616"
roi_config: [1920, 960]
```
### 目录结构
```
calib_root (G1M3_AFS1616)/
├── level1_dir_A/
│ ├── seq-27/
│ │ └── calib/L2_calib/camera4.json ✓ 现在可以正确找到
│ └── seq-28/
│ └── calib/L2_calib/camera4.json
└── level1_dir_B/
└── seq-29/
└── calib/L2_calib/camera4.json
```
## 预期效果
修复后，运行评测脚本时：
1. **不再出现校准文件找不到的警告**（对于存在的校准文件）
2. ROI 处理能够正确加载两级路径下的校准文件
3. 地面真值的 ROI 过滤和裁剪能够正常工作
4. 评测结果更加准确
## 注意事项
1. **校准文件必须存在**: 如果某个 case 确实没有校准文件，仍然会显示警告，但这是正常的
2. **路径结构必须一致**: `calib_root` 的目录结构必须与 `gt_path` 的结构匹配
3. **level1 目录名称必须匹配**: 在两级路径下，第一级目录名称在检测结果、真值和校准文件路径中必须完全相同
## 故障排查
### 问题：仍然提示找不到校准文件
**检查项**:
1. 确认 `path_depth: 2` 已设置
2. 确认 `calib_root` 路径正确
3. 确认校准文件路径为: `calib_root/level1/case/calib/L2_calib/camera4.json`
4. 确认 level1 目录名称在所有路径中一致
**调试方法**:
```python
# 在 roi_processor.py 的 load_calibration 方法中添加调试输出
print(f"Looking for calibration at: {case_calib_path}")
print(f"File exists: {case_calib_path.exists()}")
```
### 问题：某些 case 找到了，某些找不到
**可能原因**:
- 部分 case 的校准文件确实不存在
- 部分 case 的目录结构不一致
**解决方案**:
- 检查缺失的校准文件
- 统一目录结构
- 或者在配置中禁用 ROI GT 处理: `roi_gt.enabled: false`
## 总结
此修复确保了评测系统在两级路径结构下能够正确查找和加载校准文件，使得 ROI 地面真值处理功能能够正常工作。修改保持了向后兼容性，不影响现有的一级路径结构使用。

272
eval_tools/docs/COMBINED_MULTI_TARGET_SUPPORT.md Executable file
View File

@@ -0,0 +1,272 @@
# Combined 可视化支持多目标合并显示
## 问题
之前的实现中，当使用 `--merge-same-frame` 参数时：
- ✅ **BEV** 和 **image** 支持多目标合并显示
- ❌ **combined** 仍然为每个目标生成单独的文件
- ⚠️ **angle** 无法合并（每个目标需要独立的极坐标图）
这导致用户无法在一个 combined 视图中同时看到同一帧的多个目标。
## 解决方案
### 新增功能：`visualize_combined_multi()`
实现了一个新的函数来支持多目标的 combined 可视化：
```python
def visualize_combined_multi(cases, image_path, bev_range=(-20, 20, 0, 80)):
"""Generate combined visualization for multiple objects in the same frame."""
```
### 功能特性
1. **BEV 视图（左上）**: 使用 `visualize_bev_multi()` 显示所有目标
2. **图像视图（右上）**: 使用 `visualize_image_multi()` 显示所有目标
3. **角度对比（左下）**: 在同一个极坐标图上显示所有目标的 GT 和 Pred 角度
- 使用不同颜色区分目标 (green/darkgreen/lightgreen vs red/darkred/lightcoral)
- 使用不同线型区分目标 (-, --, -., :)
- 标签格式: GT#1, Pred#1, GT#2, Pred#2
4. **统计面板（右下）**: 显示所有目标的详细信息
- 按对象逐一列出统计数据
- 自动调整字体大小（对象越多，字体越小）
- 如果有任何目标存在 reversal 错误，使用红色背景
## 使用方法
### 基本用法
```bash
# Combined 现在也支持多目标合并
python eval_tools/visualize_heading_errors.py \
--input bad_heading_cases.json \
--image-root /data/images \
--output runs/heading_viz \
--viz-types combined \
--merge-same-frame
```
### 对比示例
#### 不使用 --merge-same-frame（默认）
```bash
python eval_tools/visualize_heading_errors.py \
--input bad_heading_cases.json \
--image-root /data/images \
--output runs/separate \
--viz-types combined
```
**输出结构**:
```
runs/separate/combined/
├── case_001/
│ ├── frame_001_combined.png # 单目标
│ ├── frame_002_obj1_combined.png # 多目标：第1个
│ ├── frame_002_obj2_combined.png # 多目标：第2个
│ └── frame_002_obj3_combined.png # 多目标：第3个
```
**特点**:
- 每个目标单独一个文件
- 适合详细分析单个目标
- 文件数量 = 目标总数
#### 使用 --merge-same-frame（合并）
```bash
python eval_tools/visualize_heading_errors.py \
--input bad_heading_cases.json \
--image-root /data/images \
--output runs/merged \
--viz-types combined \
--merge-same-frame
```
**输出结构**:
```
runs/merged/combined/
├── case_001/
│ ├── frame_001_combined.png # 单目标
│ └── frame_002_combined.png # 多目标合并在一个文件
```
**特点**:
- 所有目标合并在一个文件
- 适合对比分析多个目标
- 文件数量 = 唯一帧数
## 可视化效果
### 单目标帧
与原来相同，显示单个目标的完整信息。
### 多目标帧（2个目标）
**布局**:
```
┌─────────────────────┬─────────────────────┐
│ BEV View │ Image View │
│ (All objects) │ (All objects) │
│ │ │
│ GT#1 (green) │ GT#1, Pred#1 │
│ Pred#1 (red) │ GT#2, Pred#2 │
│ GT#2 (dark green) │ │
│ Pred#2 (dark red) │ │
├─────────────────────┼─────────────────────┤
│ Heading Comparison │ Statistics │
│ (Polar plot) │ │
│ │ OBJECT #1 - VEHICLE│
│ GT#1 (solid) │ Heading: 175.2° │
│ Pred#1 (solid) │ GT: 3.5° │
│ GT#2 (dashed) │ Pred: 178.7° │
│ Pred#2 (dashed) │ Confidence: 0.85 │
│ │ ... │
│ │ OBJECT #2 - VEHICLE│
│ │ Heading: 12.3° │
│ │ ... │
└─────────────────────┴─────────────────────┘
```
### 多目标帧（3个目标）
- 极坐标图会使用 3 种线型和颜色
- 统计面板字体自动缩小以容纳更多信息
- 如果有任何目标是 reversal 错误，整个面板会有红色背景警告
## 技术实现
### 关键改动
1. **新增函数**: `visualize_combined_multi(cases, image_path, bev_range)`
- 复用 `visualize_bev_multi()` 和 `visualize_image_multi()`
- 新实现多目标极坐标图
- 新实现多目标统计面板
2. **修改处理流程**: `process_merged_frame()`
```python
if 'combined' in viz_types:
fig_combined = visualize_combined_multi(frame_cases, image_path)
combined_path = combined_case_dir / f'{frame_id}_combined.png'
fig_combined.savefig(combined_path, dpi=dpi, bbox_inches='tight')
```
3. **更新提示信息**:
```
⚠️ Merge mode enabled: BEV/image/combined will show all targets
Angle plots will still generate separate files for each target
```
### 颜色方案
**极坐标图**:
- GT: green, darkgreen, lightgreen, seagreen
- Pred: red, darkred, lightcoral, crimson
**线型**:
- 对象1: 实线 `-`
- 对象2: 虚线 `--`
- 对象3: 点划线 `-.`
- 对象4+: 点线 `:`
## 性能影响
合并模式生成更少的文件，实际上**更快**：
| 模式 | 6,377 cases | 3,464 frames | Combined 文件数 | 处理时间 |
|-----------|-------------|--------------|----------------|---------|
| 分离模式 | 6,377 | 3,464 | 6,377 | ~6 分钟 |
| 合并模式 | 6,377 | 3,464 | 3,464 | ~4 分钟 |
**加速原因**:
- 减少文件 I/O 操作
- 每帧只渲染一次 BEV 和 image
- 多进程处理帧级任务而非目标级
## 使用建议
### 何时使用合并模式
✅ **推荐场景**:
1. 快速浏览和对比多个目标
2. 分析目标之间的空间关系
3. 生成汇报材料（更简洁）
4. 数据集有大量多目标帧（68.7%）
### 何时使用分离模式
✅ **推荐场景**:
1. 需要详细分析每个目标
2. 生成技术文档（完整记录）
3. 自动化工具处理（每个目标独立文件）
4. 对比特定目标对
## 兼容性
### 向后兼容
✅ 默认行为不变：
- 不使用 `--merge-same-frame` 时，每个目标仍然生成单独的 combined 文件
- 所有现有脚本无需修改
### 与其他类型的关系
| Viz Type | 默认模式 | --merge-same-frame 模式 |
|----------|-------------------|------------------------|
| bev | 单独文件 | 合并到一张图 |
| image | 单独文件 | 合并到一张图 |
| angle | 单独文件 | **仍然单独文件** ⚠️ |
| combined | 单独文件 | 合并到一张图 ✨**新** |
**注意**: angle 类型无法合并，因为每个目标需要独立的极坐标图来显示详细信息。
## 示例对比
### 17 个多目标帧，39 个目标
```bash
# 测试数据
Total cases: 39
Unique frames: 20
Frames with multiple targets: 17
Max targets in one frame: 3
```
**分离模式输出**:
```
combined/: 39 个文件
- 3 个单目标帧 → 3 个文件
- 17 个多目标帧 → 36 个文件 (2-3个目标/帧)
```
**合并模式输出**:
```
combined/: 20 个文件
- 3 个单目标帧 → 3 个文件
- 17 个多目标帧 → 17 个文件 (所有目标合并)
```
**文件减少**: 39 → 20 (减少 49%)
## 总结
✨ **新功能亮点**:
1. Combined 可视化现在支持多目标合并显示
2. 在一个视图中同时看到所有目标的 BEV、图像、角度对比和统计信息
3. 更少的文件，更快的生成速度
4. 更好的多目标对比分析体验
🎯 **适用场景**:
- 快速分析多目标场景
- 生成简洁的可视化报告
- 减少存储空间占用
- 提高处理速度
📊 **性能提升**:
- 文件数量减少约 50%
- 处理时间减少约 30%
- 更适合大规模数据集
现在，使用 `--merge-same-frame --viz-types combined` 可以获得最完整的多目标合并可视化效果！

383
eval_tools/docs/COMMON_MATCH_COMPARISON_DESIGN.md Executable file
View File

@@ -0,0 +1,383 @@
# 基于共同匹配集的3D指标对比方案
## 问题分析
### 当前问题
两个模型评测时匹配的样本数量不一致：
- **Model A**: 匹配 440,408 个 vehicle
- **Model B**: 匹配 491,768 个 vehicle
- 差异：51,360 个样本（11.7%）
**导致的问题**：
- 无法确定性能差异是因为**模型质量**还是**匹配了不同的目标**
- 比较的不是相同目标的预测质量
### 解决方案
只比较两个模型**都成功匹配到GT的目标**，确保对比的是相同目标的3D性能差异。
## 实现方案
### 方案架构
```
┌─────────────────┐
│ Model 1 Eval │
│ + Save Matches │──┐
└─────────────────┘ │
│ ┌──────────────────────┐
├─→│ Common Match Finder │
│ └──────────────────────┘
┌─────────────────┐ │ ↓
│ Model 2 Eval │ │ ┌──────────────────────┐
│ + Save Matches │──┘ │ Recompute 3D Stats │
└─────────────────┘ │ (Common Matches Only)│
└──────────────────────┘
↓
┌──────────────────────┐
│ Comparison Report │
└──────────────────────┘
```
### 数据结构设计
#### 1. 详细匹配数据文件 (`detailed_3d_matches.json`)
```json
{
"case_019b178d": {
"frame_000018": {
"vehicle": [
{
"gt_id": "hash_of_gt_bbox", // 用于唯一标识GT
"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
}
}
]
}
}
}
```
#### 2. 共同匹配索引 (`common_matches_index.json`)
```json
{
"statistics": {
"model1_total": 440408,
"model2_total": 491768,
"common_matches": 425163,
"model1_unique": 15245,
"model2_unique": 66605,
"common_percentage": 96.5
},
"common_matches": {
"case_019b178d": {
"frame_000018": {
"vehicle": [
{
"gt_id": "hash_of_gt_bbox",
"model1_idx": 0,
"model2_idx": 0
}
]
}
}
}
}
```
### 实现步骤
#### 步骤1：扩展评测器保存详细匹配
修改 `eval_tools/evaluator/evaluator.py`：
```python
def evaluate_3d(self):
# ... 现有代码 ...
# 新增：保存详细匹配信息
self.detailed_3d_matches = {}
for case_name, case_pairs in cases.items():
self.detailed_3d_matches[case_name] = {}
for pair in case_pairs:
frame_name = pair['frame']
gts = self.gt_parser.parse_file(...)
dets = self.det_parser.parse_file(...)
self.detailed_3d_matches[case_name][frame_name] = {}
for class_id in Metrics3D.CLASSES_3D:
match_result = self.matcher.match(gts, dets, class_id)
matches_list = []
for gt_idx, det_idx, iou in match_result['matches']:
gt = match_result['gts_filtered'][gt_idx]
det = match_result['dets_sorted'][det_idx]
if gt['has_3d'] and det['3d_info']:
# 计算3D误差
errors = self._compute_3d_errors(gt, det)
# 保存匹配详情
matches_list.append({
'gt_id': self._generate_gt_id(gt),
'gt_bbox': gt['bbox_2d'],
'det_bbox': det['bbox_2d'],
'errors': errors,
'distance': {
'longitudinal': gt['3d_info']['center'][2],
'lateral': gt['3d_info']['center'][0]
}
})
if matches_list:
class_name = self.gt_parser.get_class_name(class_id)
self.detailed_3d_matches[case_name][frame_name][class_name] = matches_list
```
#### 步骤2：创建共同匹配查找工具
新建 `eval_tools/find_common_matches.py`：
```python
def find_common_matches(model1_matches, model2_matches):
"""
找出两个模型共同匹配的GT目标
Args:
model1_matches: Model 1的详细匹配数据
model2_matches: Model 2的详细匹配数据
Returns:
common_matches: 共同匹配的索引
stats: 统计信息
"""
common_matches = {}
stats = {
'model1_total': 0,
'model2_total': 0,
'common': 0,
'model1_unique': 0,
'model2_unique': 0
}
for case_name in model1_matches:
if case_name not in model2_matches:
continue
common_matches[case_name] = {}
for frame_name in model1_matches[case_name]:
if frame_name not in model2_matches[case_name]:
continue
common_matches[case_name][frame_name] = {}
for class_name in model1_matches[case_name][frame_name]:
if class_name not in model2_matches[case_name][frame_name]:
continue
m1_list = model1_matches[case_name][frame_name][class_name]
m2_list = model2_matches[case_name][frame_name][class_name]
# 建立GT ID映射
m1_gt_ids = {m['gt_id']: i for i, m in enumerate(m1_list)}
m2_gt_ids = {m['gt_id']: i for i, m in enumerate(m2_list)}
# 找共同的GT ID
common_gt_ids = set(m1_gt_ids.keys()) & set(m2_gt_ids.keys())
stats['model1_total'] += len(m1_list)
stats['model2_total'] += len(m2_list)
stats['common'] += len(common_gt_ids)
stats['model1_unique'] += len(m1_gt_ids) - len(common_gt_ids)
stats['model2_unique'] += len(m2_gt_ids) - len(common_gt_ids)
# 保存共同匹配的索引
common_list = []
for gt_id in common_gt_ids:
common_list.append({
'gt_id': gt_id,
'model1_idx': m1_gt_ids[gt_id],
'model2_idx': m2_gt_ids[gt_id]
})
if common_list:
common_matches[case_name][frame_name][class_name] = common_list
return common_matches, stats
```
#### 步骤3：扩展模型比较器
修改 `eval_tools/compare_models.py`：
```python
class ModelComparator:
def __init__(self, model1_report, model2_report,
model1_matches=None, model2_matches=None,
use_common_matches=False):
"""
Args:
use_common_matches: 是否只比较共同匹配的样本
"""
self.use_common_matches = use_common_matches
if use_common_matches:
# 找出共同匹配
self.common_matches, self.common_stats = find_common_matches(
model1_matches, model2_matches
)
# 基于共同匹配重新计算3D统计
self.model1_3d_filtered = self._recompute_3d_stats(
model1_matches, 'model1'
)
self.model2_3d_filtered = self._recompute_3d_stats(
model2_matches, 'model2'
)
def _recompute_3d_stats(self, matches_data, model_name):
"""基于共同匹配重新计算3D统计"""
stats = {}
for case_name, frames in self.common_matches.items():
for frame_name, classes in frames.items():
for class_name, common_list in classes.items():
if class_name not in stats:
stats[class_name] = {
'lateral': [],
'longitudinal': [],
'heading': []
}
for match_info in common_list:
idx = match_info[f'{model_name}_idx']
match = matches_data[case_name][frame_name][class_name][idx]
stats[class_name]['lateral'].append(match['errors']['lateral'])
stats[class_name]['longitudinal'].append(match['errors']['longitudinal'])
stats[class_name]['heading'].append(match['errors']['heading'])
return stats
```
### 使用流程
#### 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
```
#### 2. 比较（基于共同匹配）
```bash
python eval_tools/compare_models_with_common_matches.py \
--model1-report eval_results_multiprocess/mono3d/20260203_162537/evaluation_report.json \
--model1-matches eval_results_multiprocess/mono3d/20260203_162537/detailed_3d_matches.json \
--model2-report eval_results_multiprocess/yolov5s/20260203_161644/evaluation_report.json \
--model2-matches eval_results_multiprocess/yolov5s/20260203_161644/detailed_3d_matches.json \
--output-dir comparison_results_common_matches \
--use-common-matches
```
#### 3. 对比报告示例
```
================================================================================
3D METRICS COMPARISON (COMMON MATCHES ONLY)
================================================================================
Match Statistics:
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%)
VEHICLE (Common Matches: 420,158):
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. **公平对比**：确保比较的是相同目标的预测质量
2. **性能分析**：可以单独分析各模型独有匹配的特点
3. **问题诊断**：识别哪些目标一个模型能匹配而另一个不能
## 可选扩展
### 1. 分析独有匹配
```python
def analyze_unique_matches(model1_matches, model2_matches, common_matches):
"""分析每个模型独有匹配的特征"""
model1_unique = []
model2_unique = []
# ... 找出独有匹配 ...
return {
'model1_unique_analysis': {
'count': len(model1_unique),
'avg_distance': ...,
'avg_iou': ...,
'difficulty': ... # 小目标、遮挡等
},
'model2_unique_analysis': {
...
}
}
```
### 2. 可视化差异
生成可视化图表展示：
- 共同匹配 vs 独有匹配的分布
- 不同距离/横向位置的共同匹配率
- 独有匹配的特征分析
## 实现优先级
1. **P0（必须）**：保存详细匹配信息
2. **P0（必须）**：找出共同匹配并重新计算统计
3. **P1（重要）**：生成基于共同匹配的对比报告
4. **P2（可选）**：分析独有匹配特征
5. **P3（可选）**：可视化工具
## 兼容性
- **向后兼容**：默认不启用，保持现有行为
- **可选启用**：通过 `--use-common-matches` 标志启用
- **存储开销**：详细匹配文件约为评测报告的 5-10 倍大小

332
eval_tools/docs/COMMON_MATCH_COMPARISON_SUMMARY.md Executable file
View File

@@ -0,0 +1,332 @@
# 基于共同匹配集的3D指标对比 - 实现总结
## 实现概述
已完成基于共同匹配集的3D指标对比功能，解决了两个模型匹配样本数量不一致导致无法公平对比的问题。
## 核心实现
### 1. 评测器扩展 (evaluator.py)
**修改内容**：
- 添加 `save_detailed_matches` 参数到 `__init__()` 方法
- 添加 `detailed_3d_matches` 存储结构
- 修改 `_process_frame_3d()` 保存每个匹配对的详细信息：
* GT唯一ID (基于bbox坐标的MD5哈希)
* GT和检测的2D bbox
* GT和检测的3D中心点
* IoU和置信度
* 3D误差（lateral、longitudinal、heading）
* 距离信息（用于区间统计）
- 在 `evaluate_3d()` 中聚合详细匹配数据（支持多进程）
- 在 `generate_report()` 中保存 `detailed_3d_matches.json`
**输出文件**：
- `detailed_3d_matches.json` - 包含所有匹配对的详细信息
### 2. 共同匹配查找工具 (find_common_matches.py)
**功能**：
- 加载两个模型的详细匹配数据
- 基于GT唯一ID找出共同匹配的目标
- 计算匹配统计（总数、共同、独有）
- 基于共同匹配重新计算3D统计
- 生成详细的统计报告
**核心函数**：
- `find_common_matches()` - 找出共同匹配
- `recompute_3d_stats_from_common_matches()` - 重新计算3D统计
- `print_statistics()` - 打印匹配统计
**输出文件**：
- `common_matches.json` - 包含共同匹配索引和重新计算的统计
### 3. 模型比较器扩展 (compare_models.py)
**修改内容**：
- `__init__()` 添加 `common_matches_data` 参数
- `compare_3d_metrics()` 检测是否使用共同匹配
- 新增 `_compare_3d_metrics_common_matches()` 方法：
* 使用预计算的共同匹配统计
* 显示匹配统计摘要
* 生成基于共同匹配的对比
- `main()` 添加 `--common-matches` 参数
**使用方式**：
```bash
# 不使用共同匹配（传统方式）
python eval_tools/compare_models.py --model1 m1.json --model2 m2.json
# 使用共同匹配
python eval_tools/compare_models.py \
--model1 m1.json --model2 m2.json \
--common-matches common_matches.json
```
### 4. 评测脚本扩展 (eval.py)
**修改内容**：
- 添加 `--save-detailed-matches` 参数
- 传递参数到 Evaluator 构造函数
- 在输出中显示是否保存详细匹配
**使用方式**：
```bash
# 普通评测
python eval_tools/eval.py --config config.yaml
# 保存详细匹配
python eval_tools/eval.py --config config.yaml --save-detailed-matches
```
### 5. 完整流程脚本 (compare_models_with_common_matches.sh)
**功能**：
自动化执行完整流程：
1. 评测 Model 1 并保存详细匹配
2. 评测 Model 2 并保存详细匹配
3. 找出共同匹配
4. 生成基于共同匹配的对比报告
5. 生成传统对比报告（用于参考）
**使用方式**：
```bash
bash eval_tools/compare_models_with_common_matches.sh
```
## 工作流程
```
┌─────────────────────────┐
│ Model 1 Eval │
│ + save-detailed-matches │
└────────────┬────────────┘
│ detailed_3d_matches.json
│
↓
┌─────────────────────────┐
│ find_common_matches.py │←──┐
└─────────────────────────┘ │
│ │
│ common_matches.json │ detailed_3d_matches.json
│ │
↓ │
┌─────────────────────────┐ │
│ compare_models.py │ │
│ --common-matches │ │
└─────────────────────────┘ │
│ │
↓ │
comparison_report.txt │
(based on common matches) │
│
┌─────────────────────────┐ │
│ Model 2 Eval │ │
│ + save-detailed-matches │─────────┘
└─────────────────────────┘
```
## 数据结构
### detailed_3d_matches.json
```json
{
"case_name": {
"frame_name": {
"class_name": [
{
"gt_id": "unique_hash",
"gt_bbox": [x1, y1, x2, y2],
"gt_center_3d": [x, y, z],
"det_bbox": [x1, y1, x2, y2],
"det_center_3d": [x, y, z],
"iou": 0.89,
"confidence": 0.87,
"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,
"model1_unique": 15245,
"model2_unique": 66605,
"common_percentage_of_model1": 96.5,
"per_class": { ... }
},
"common_matches": {
"case_name": {
"frame_name": {
"class_name": [
{
"gt_id": "unique_hash",
"model1_idx": 0,
"model2_idx": 0
}
]
}
}
},
"model1_3d_stats": {
"vehicle": {
"num_samples": 425163,
"lateral_error": {"mean": 1.3251, "std": 0.8745, ...},
"longitudinal_error": {"mean": 2.5892, "std": 1.2341, ...},
"heading_error": {"mean": 0.2256, "std": 0.1234, ...}
}
},
"model2_3d_stats": { ... },
"model_names": {
"model1": "mono3d",
"model2": "yolov5s-300w"
}
}
```
## 使用示例
### 示例1：完整流程（推荐）
```bash
bash eval_tools/compare_models_with_common_matches.sh
```
### 示例2：手动步骤
```bash
# 步骤1：评测并保存详细匹配
python eval_tools/eval.py \
--config eval_tools/configs/eval_config_mono3d.yaml \
--save-detailed-matches
python eval_tools/eval.py \
--config eval_tools/configs/eval_config_yolov5.yaml \
--save-detailed-matches
# 步骤2：找出共同匹配
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
# 步骤3：比较（基于共同匹配）
python eval_tools/compare_models.py \
--model1 eval_results/model1/evaluation_report.json \
--model2 eval_results/model2/evaluation_report.json \
--common-matches common_matches.json \
--output-dir comparison_results
```
## 对比报告示例
```
================================================================================
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 (3.5%)
yolov5s-300w Unique: 66,605 (13.5%)
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. **公平对比**：只比较相同目标的3D预测质量，排除召回率差异的影响
2. **问题诊断**：识别哪些目标一个模型能匹配而另一个不能
3. **性能分析**：可以单独分析各模型独有匹配的特点
4. **向后兼容**：不影响现有评测流程，可选启用
5. **灵活性**：支持传统对比和共同匹配对比两种模式
## 性能考虑
- **存储开销**：`detailed_3d_matches.json` 约为 `evaluation_report.json` 的 5-10 倍
- **时间开销**：保存详细匹配会增加约 5-10% 的评测时间
- **建议**：只在需要对比时使用 `--save-detailed-matches`
## 文件清单
### 新增文件
1. `eval_tools/find_common_matches.py` - 共同匹配查找工具
2. `eval_tools/compare_models_with_common_matches.sh` - 完整流程脚本
3. `eval_tools/COMMON_MATCH_COMPARISON_DESIGN.md` - 设计方案文档
4. `eval_tools/COMMON_MATCH_COMPARISON_USAGE.md` - 使用指南
5. `eval_tools/COMMON_MATCH_COMPARISON_SUMMARY.md` - 本文档
### 修改文件
1. `eval_tools/evaluator/evaluator.py` - 添加详细匹配保存功能
2. `eval_tools/compare_models.py` - 添加共同匹配对比功能
3. `eval_tools/eval.py` - 添加 `--save-detailed-matches` 参数
## 测试建议
建议进行以下测试：
1. **功能测试**：
```bash
bash eval_tools/compare_models_with_common_matches.sh
```
2. **验证测试**：
- 检查 `detailed_3d_matches.json` 是否正确生成
- 检查共同匹配数量是否合理
- 验证对比报告中的统计是否基于共同匹配
3. **性能测试**：
- 对比启用/不启用 `--save-detailed-matches` 的评测时间
- 检查文件大小是否在预期范围内
## 下一步扩展（可选）
1. **独有匹配分析**：
- 分析独有匹配的特征（距离、大小、置信度等）
- 生成独有匹配的可视化
2. **距离区间对比**：
- 支持基于共同匹配的距离区间统计
- 横向/纵向距离区间的共同匹配对比
3. **可视化工具**：
- 共同匹配 vs 独有匹配的分布图
- 不同距离/位置的共同匹配率热力图
4. **性能优化**：
- 使用更高效的序列化格式（如 MessagePack）
- 按需加载详细匹配数据
## 总结
已成功实现基于共同匹配集的3D指标对比功能，解决了两个模型匹配样本数量不一致的问题。该方案：
- ✅ 确保公平对比相同目标的3D性能
- ✅ 提供独有匹配的统计分析
- ✅ 保持向后兼容性
- ✅ 提供完整的自动化流程
- ✅ 包含详细的使用文档
可以立即使用此功能进行模型对比分析。

309
eval_tools/docs/COMMON_MATCH_COMPARISON_USAGE.md Executable file
View File

@@ -0,0 +1,309 @@
# 基于共同匹配集的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) - 模型比较工具

139
eval_tools/docs/DISTANCE_RANGES_GUIDE.md Executable file
View File

@@ -0,0 +1,139 @@
# 距离区间3D评测功能说明
## 功能描述
新增了按距离区间统计3D检测误差的功能，可以分析模型在不同距离范围内的性能表现。
## 配置方法
在配置文件 `eval_config.yaml` 中的 `metrics_3d` 部分添加 `distance_ranges`：
```yaml
metrics_3d:
enabled: true
distance_ranges:
- [0, 30] # 0-30米
- [30, 60] # 30-60米
- [60, 100] # 60-100米
- [100, 999] # 100米以上
```
## 距离定义
- 使用GT目标的**z坐标**（纵向距离）作为距离值
- 单位：米（meter）
- 区间为左闭右开：`[min, max)`
## 评测结果
### 控制台输出示例
```
3D Metrics:
vehicle [overall]: Lat=0.647m, Long=1.680m, Head=0.258rad (n=2407)
[0-30m]: Lat=0.500m, Long=1.203m, Head=0.177rad (n=2142)
[30-60m]: Lat=1.149m, Long=5.074m, Head=0.607rad (n=194)
[60-100m]: Lat=0.897m, Long=5.624m, Head=1.036rad (n=37)
```
### 文本报告示例
```
VEHICLE:
[0-30m]:
Samples: 2142
Lateral Error (m):
Mean: 0.4995
Median: 0.2247
Std: 0.8574
90%: 1.2385
Longitudinal Error (m):
Mean: 1.2026
Median: 0.5173
Std: 1.8009
90%: 3.1931
Heading Error (rad):
Mean: 0.1768
Median: 0.0526
Std: 0.5410
90%: 0.2019
[30-60m]:
Samples: 194
...
[OVERALL]:
Samples: 2407
...
```
## 使用示例
### 1. 使用配置文件
```bash
python eval_tools/eval.py \
--config eval_tools/configs/eval_config.yaml \
--roi 0 120 1920 1080 \
--roi-input-size 704 352
```
### 2. 快速测试
```bash
bash eval_tools/test_distance_ranges.sh
```
## 性能分析
从测试结果可以看出：
### Vehicle类别（2407个样本）
- **0-30m**（近距离，2142样本）：
- 横向误差：0.50m
- 纵向误差：1.20m
- 朝向误差：0.18rad
- **性能最好**
- **30-60m**（中距离，194样本）：
- 横向误差：1.15m（↑2.3倍）
- 纵向误差：5.07m（↑4.2倍）
- 朝向误差：0.61rad（↑3.4倍）
- **误差明显增大**
- **60-100m**（远距离，37样本）：
- 横向误差：0.90m
- 纵向误差：5.62m
- 朝向误差：1.04rad（↑5.9倍）
- **朝向估计最困难**
### Rider类别（65个样本）
- **0-30m**（44样本）：误差较小
- **30-60m**（21样本）：纵向误差显著增加（0.96m → 2.33m）
## 关键发现
1. **距离越远，误差越大**：符合预期，远距离目标分辨率低
2. **纵向误差增长最快**：距离估计是3D检测的主要挑战
3. **朝向误差对距离敏感**：远距离目标的朝向估计困难
4. **样本分布不均**：89%的vehicle样本在30米内
## 向后兼容
- 如果不配置 `distance_ranges`，评测脚本将只输出整体统计（兼容旧版本）
- 现有评测脚本无需修改即可继续使用
## 实现细节
- **匹配方式**：仍使用2D IoU匹配，距离区间只用于统计分组
- **数据结构**：`errors[class_id][range_key]` 存储分组误差
- **统计指标**：每个区间独立计算mean/median/std/90%分位数
- **JSON输出**：完整保存所有区间数据，便于后续分析
## 相关文件
- `eval_tools/evaluator/metrics_3d.py` - 核心实现
- `eval_tools/evaluator/evaluator.py` - 配置传递和报告生成
- `eval_tools/configs/eval_config.yaml` - 配置示例
- `eval_tools/test_distance_ranges.sh` - 测试脚本

286
eval_tools/docs/DUPLICATE_CASE_NAMES_FIX_CN.md Executable file
View File

@@ -0,0 +1,286 @@
# 两级路径下重复 Case 名称问题修复
## 问题描述
在使用两级路径结构（`path_depth: 2`）时，发现：
- **数据加载阶段**: 找到 155 个 cases
- **评测阶段**: 只处理了 59 个 cases
```
Found 155 case(s) in detection root: ... (path_depth=2)
Processing case [1/59]: seq-03 (1278 frames)
```
## 问题原因
在两级路径结构下，不同的 level1 目录可能包含相同名称的 case：
```
det_root/
dataset_A/
seq-03/ ← 同名 case
seq-27/
dataset_B/
seq-03/ ← 同名 case
seq-28/
```
原有代码在评测阶段按 case 名称分组时，只使用了 `case_name` 作为键：
```python
# 原有代码（有问题）
cases = {}
for pair in self.image_pairs:
case_name = pair['case'] # 只使用 case 名称
if case_name not in cases:
cases[case_name] = []
cases[case_name].append(pair)
```
这导致：
- `dataset_A/seq-03` 和 `dataset_B/seq-03` 都被归到 `cases['seq-03']` 中
- 两个不同的 case 被合并成一个
- 155 个实际 case 被合并成 59 个唯一名称的 case
## 解决方案
### 修改分组逻辑
在 `evaluate_2d()` 和 `evaluate_3d()` 方法中，使用唯一的 case 标识符进行分组：
```python
# 修复后的代码
cases = {}
for pair in self.image_pairs:
# 创建唯一的 case 标识符
level1_name = pair.get('level1_name')
case_name = pair['case']
if level1_name:
case_key = f"{level1_name}/{case_name}" # 两级路径: "dataset_A/seq-03"
else:
case_key = case_name # 一级路径: "seq-03"
if case_key not in cases:
cases[case_key] = []
cases[case_key].append(pair)
```
### 更新循环变量
将循环中的 `case_name` 改为 `case_key`，并在所有相关位置使用：
```python
# 修复前
for case_idx, (case_name, case_pairs) in enumerate(cases.items(), 1):
print(f"Processing case [{case_idx}/{len(cases)}]: {case_name} ...")
self.per_case_metrics_2d[case_name] = ...
# 修复后
for case_idx, (case_key, case_pairs) in enumerate(cases.items(), 1):
print(f"Processing case [{case_idx}/{len(cases)}]: {case_key} ...")
self.per_case_metrics_2d[case_key] = ...
```
## 修改的文件
**eval_tools/evaluator/evaluator.py**
修改了三个方法：
1. `evaluate_2d()` - 2D 评测的分组逻辑（第 494-556 行）
2. `evaluate_3d()` - 3D 评测的分组逻辑（第 580-662 行）
3. `_write_per_case_reports()` - Per-case 报告生成，添加文件名安全处理（第 862-864 行）
主要改动：
- 第 494-507 行：2D 评测的分组和循环
- 第 556 行：保存 per-case 结果时使用 `case_key`
- 第 580-596 行：3D 评测的分组和循环
- 第 627、636、640、662 行：保存 detailed matches 时使用 `case_key`
- 第 862-864 行：生成报告文件时将 "/" 替换为 "_"
## 测试验证
创建了测试脚本 `eval_tools/tests/test_duplicate_case_names.py`：
```bash
python eval_tools/tests/test_duplicate_case_names.py
```
测试结果：
```
============================================================
Test Summary
============================================================
✓ TEST PASSED
The fix correctly handles duplicate case names across
different level1 directories by using unique case identifiers.
```
测试验证了：
1. 数据加载阶段正确识别所有 cases（包括重名的）
2. 评测阶段正确处理所有 cases（不会合并重名的）
3. Per-case 报告使用唯一标识符
## 预期效果
修复后，运行评测时：
### 修复前
```
Found 155 case(s) in detection root: ... (path_depth=2)
Processing case [1/59]: seq-03 (1278 frames) ← 合并了多个同名 case
```
### 修复后
```
Found 155 case(s) in detection root: ... (path_depth=2)
Processing case [1/155]: dataset_A/seq-03 (640 frames)
Processing case [2/155]: dataset_B/seq-03 (638 frames) ← 正确分开
Processing case [3/155]: dataset_A/seq-27 (512 frames)
...
```
## Case 标识符格式
### 一级路径（`path_depth: 1`）
- Case 标识符: `seq-03`
- 显示格式: `seq-03`
### 两级路径（`path_depth: 2`）
- Case 标识符: `dataset_A/seq-03`
- 显示格式: `dataset_A/seq-03`
## Per-Case 报告
Per-case 报告文件名会将 "/" 替换为 "_" 以兼容文件系统：
### 一级路径
```
per_case_reports/
seq-03_report.txt
seq-27_report.txt
```
### 两级路径
```
per_case_reports/
dataset_A_seq-03_report.txt ← "/" 被替换为 "_"
dataset_B_seq-03_report.txt
dataset_A_seq-27_report.txt
```
**重要**: 由于文件系统不允许文件名中包含 "/"，在生成报告文件时，`case_key` 中的 "/" 会被自动替换为 "_"。这个转换在 `_write_per_case_reports()` 方法中自动完成：
```python
# 在 evaluator.py 中
for case_name in sorted(case_names):
# 将 "/" 替换为 "_" 以兼容文件系统
safe_case_name = case_name.replace('/', '_')
case_report_path = os.path.join(per_case_dir, f'{safe_case_name}_report.txt')
```
## 向后兼容性
- 对于一级路径结构（`path_depth: 1`），`level1_name` 为 `None`，`case_key` 就是 `case_name`
- 行为与之前完全相同，不会有任何变化
- 所有现有配置和脚本无需修改
## 使用示例
### 示例 1: 查看评测输出
修复前（合并了重名 case）：
```
Processing case [1/59]: seq-03 (1278 frames)
seq-03: 100%|████████| 1278/1278 [00:05<00:00, 245.67it/s]
```
修复后（正确分开）：
```
Processing case [1/155]: dataset_A/seq-03 (640 frames)
dataset_A/seq-03: 100%|████████| 640/640 [00:02<00:00, 248.12it/s]
Processing case [2/155]: dataset_B/seq-03 (638 frames)
dataset_B/seq-03: 100%|████████| 638/638 [00:02<00:00, 246.89it/s]
```
### 示例 2: 查看 Per-Case 报告
```bash
# 列出所有 per-case 报告
ls evaluation_results/*/per_case_reports/
# 输出（修复后）：
dataset_A_seq-03_report.txt
dataset_A_seq-27_report.txt
dataset_B_seq-03_report.txt
dataset_B_seq-28_report.txt
...
```
### 示例 3: 查看评测报告 JSON
```python
import json
with open('evaluation_results/.../evaluation_report.json', 'r') as f:
report = json.load(f)
# 查看 per-case 2D 结果
for case_key, metrics in report['per_case_2d'].items():
print(f"{case_key}: mAP={metrics['overall']['map']:.4f}")
# 输出（修复后）：
# dataset_A/seq-03: mAP=0.8234
# dataset_A/seq-27: mAP=0.8156
# dataset_B/seq-03: mAP=0.8312
# dataset_B/seq-28: mAP=0.8089
```
## 故障排查
### 问题：仍然看到 case 数量不匹配
**检查项**:
1. 确认已经更新到最新代码
2. 确认 `path_depth: 2` 已设置
3. 检查是否有其他原因导致 case 被跳过（如缺少文件）
**调试方法**:
```python
# 在 load_data_from_paths 后添加调试输出
print(f"Total image pairs: {len(evaluator.image_pairs)}")
print(f"Unique cases: {len(set(pair['case'] for pair in evaluator.image_pairs))}")
print(f"Unique case_keys: {len(set(f\"{pair.get('level1_name', '')}/{pair['case']}\" for pair in evaluator.image_pairs))}")
```
### 问题：Per-case 报告文件名包含特殊字符
**原因**: `case_key` 中的 "/" 在文件名中不合法，会被操作系统误认为是目录分隔符
**错误示例**:
```python
# 错误：会尝试创建 per_case_reports/20251115/seq-03_report.txt
case_report_path = os.path.join(per_case_dir, f'{case_key}_report.txt')
# 如果 case_key = "20251115/seq-03"，会导致 FileNotFoundError
```
**解决方案**: 代码会自动将 "/" 替换为 "_"
```python
# 正确：创建 per_case_reports/20251115_seq-03_report.txt
safe_case_name = case_key.replace('/', '_')
case_report_path = os.path.join(per_case_dir, f'{safe_case_name}_report.txt')
```
**修复位置**: `evaluator.py` 第 862-864 行
## 相关文档
- [TWO_LEVEL_PATH_SUPPORT.md](TWO_LEVEL_PATH_SUPPORT.md) - 两级路径功能说明
- [CALIBRATION_FILE_FIX_CN.md](CALIBRATION_FILE_FIX_CN.md) - 校准文件问题修复
## 总结
此修复确保了评测系统在两级路径结构下能够正确处理重复的 case 名称，通过使用唯一的 case 标识符（`level1/case`）来区分不同 level1 目录下的同名 case。修改保持了向后兼容性，不影响现有的一级路径结构使用。
修复后，评测结果将更加准确，每个 case 都会被独立评测和报告，不会因为名称重复而被错误地合并。

463
eval_tools/docs/EVALSET_CONSTRUCTION_GUIDE.md Executable file
View File

@@ -0,0 +1,463 @@
# 评测集构建方案
> 适用模型：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*

598
eval_tools/docs/EVALUATION_DESIGN.md Executable file
View File

@@ -0,0 +1,598 @@
# 模型输出评测方案设计
## 1. 评测概述
### 1.1 评测目标
- **2D检测评测**: 评估所有类别的2D边界框检测性能
- **3D检测评测**: 评估3D类别的空间定位和朝向估计性能
### 1.2 评测类别划分
- **3D目标类别** (0-3): vehicle, pedestrian, bike, rider
- **纯2D目标类别** (4-13): roadblock, head, tsr, guideboard, plate, wheel, tl_border, tl_wick, tl_num, tricycle
## 2. 数据格式解析
### 2.1 真值数据格式
#### 2.1.1 3D类别真值格式
**完整3D标注（车辆类别）- 50个值**:
```
[label, x, y, w, h, # 0-4: 类别和2D框（归一化）
x3d_ori, y3d_ori, z3d_ori, # 5-7: 原始3D中心点
l3d, h3d, w3d, # 8-10: 3D尺寸
rot_y, # 11: 旋转角
xc_ori, yc_ori, # 12-13: 原始中心点2D投影
xc_ori_d, yc_ori_d, # 14-15: 深度相关中心点
alpha_ori, # 16: 原始alpha角
0, # 17: 占位符
# 前面 (18-25)
x3d_front, y3d_front, z3d_front, alpha_front, xc_front, yc_front, score_front, is_occ_front,
# 后面 (26-33)
x3d_back, y3d_back, z3d_back, alpha_back, xc_back, yc_back, score_back, is_occ_back,
# 左面 (34-41)
x3d_left, y3d_left, z3d_left, alpha_left, xc_left, yc_left, score_left, is_occ_left,
# 右面 (42-49)
x3d_right, y3d_right, z3d_right, alpha_right, xc_right, yc_right, score_right, is_occ_right]
```
**完整3D标注（非车辆类别）- 18个值**:
```
[label, x, y, w, h, # 0-4: 类别和2D框（归一化）
x3d_ori, y3d_ori, z3d_ori, # 5-7: 3D中心点
l3d, h3d, w3d, # 8-10: 3D尺寸
rot_y, # 11: 旋转角
xc_ori, yc_ori, # 12-13: 中心点2D投影
xc_ori_d, yc_ori_d, # 14-15: 深度相关中心点
alpha_ori, # 16: alpha角
0] # 17: 占位符
```
**仅2D标注 - 6个值**:
```
[label, x, y, w, h, -1] # 最后一位为-1表示无3D标注
```
#### 2.1.2 纯2D类别真值格式（6个值）
```
[label, x, y, w, h, -1] # label ∈ {4,5,6,7,8,9,10,11,12,13}
```
### 2.2 检测结果格式
#### 2.2.1 3D类别检测格式（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, coord_sys, x3d, y3d, z3d, l3d, h3d, w3d, rot_y, face_type]
```
注：face_type可以是 front, back, left, right，也支持 rear 和 tail 作为 back 的别名
**非车辆类别**:
```
pedestrian 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 whole
[label, conf, x1, y1, x2, y2, coord_sys, x3d, y3d, z3d, l3d, h3d, w3d, rot_y, whole]
```
#### 2.2.2 纯2D类别检测格式（5个值）
```
plate 0.94246 532.12 203.26 558.73 214.86
[label, conf, x1, y1, x2, y2]
```
## 3. 评测指标设计
### 3.1 2D检测指标
#### 3.1.1 基础指标
- **Precision (精确率)**: TP / (TP + FP)
- **Recall (召回率)**: TP / (TP + FN)
- **AP (Average Precision)**: PR曲线下面积，IoU阈值=0.5
- **mAP (mean Average Precision)**: 所有类别AP的平均值
#### 3.1.2 匹配规则
- **IoU阈值**: 0.5
- **匹配策略**:
1. 计算预测框与真值框的IoU
2. 按置信度从高到低排序预测框
3. 每个真值框最多匹配一个预测框
4. IoU >= 0.5 且类别相同视为匹配成功（TP）
5. 未匹配的预测框为FP，未匹配的真值框为FN
#### 3.1.3 分类别评测
- 对每个类别分别计算 Precision, Recall, AP
- 类别包括: vehicle, pedestrian, bike, rider, roadblock, head, tsr, guideboard, plate, wheel, tl_border, tl_wick, tl_num, tricycle
#### 3.1.4 整体评测
- **总Precision**: 所有类别的总TP / (总TP + 总FP)
- **总Recall**: 所有类别的总TP / (总TP + 总FN)
- **mAP**: 所有类别AP的算术平均
### 3.2 3D检测指标
#### 3.2.1 评测范围
仅评测3D类别：vehicle, pedestrian, bike, rider
#### 3.2.2 前提条件
只有在2D检测匹配成功（IoU >= 0.5）且真值包含完整3D标注的情况下，才进行3D指标评测
#### 3.2.3 3D评测指标
**车辆类别的测距误差计算**:
车辆类别需要根据预测结果中的最近面信息（front/back/left/right），选取真值中对应的最近面中心点进行比较：
1. 根据预测结果中的`face_type`字段（front/back/left/right），确定预测的最近面
2. 从真值的4个面信息中，选取对应面的中心点坐标
3. 计算预测最近面中心点与真值对应面中心点的误差
```
# 车辆类别
face_mapping = {
'front': [18, 19, 20], # x3d_front, y3d_front, z3d_front 在真值中的索引
'back': [26, 27, 28], # x3d_back, y3d_back, z3d_back
'left': [34, 35, 36], # x3d_left, y3d_left, z3d_left
'right': [42, 43, 44] # x3d_right, y3d_right, z3d_right
}
# 根据预测的face_type选择真值中对应的面中心点
face_type = det_result['face_type'] # 'front', 'back', 'left', 'right'
x3d_gt, y3d_gt, z3d_gt = gt_values[face_mapping[face_type]]
# 获取预测的最近面中心点
x3d_pred, y3d_pred, z3d_pred = det_result['3d_info']['center']
# 计算误差
lateral_error = |x3d_pred - x3d_gt|
longitudinal_error = |z3d_pred - z3d_gt|
```
**非车辆类别的测距误差计算**:
非车辆类别（pedestrian, bike, rider）直接使用3D框中心点计算误差：
```
# 非车辆类别
x3d_gt, y3d_gt, z3d_gt = gt_values[5:8] # x3d_ori, y3d_ori, z3d_ori
x3d_pred, y3d_pred, z3d_pred = det_result['3d_info']['center']
lateral_error = |x3d_pred - x3d_gt|
longitudinal_error = |z3d_pred - z3d_gt|
```
**Heading偏差 (Heading Error)**:
所有3D类别使用相同的方式计算heading误差：
```
heading_error = |normalize_angle(rot_y_pred - rot_y_gt)|
```
其中 normalize_angle 将角度差归一化到 [-π, π]
#### 3.2.4 统计指标
对每个3D类别分别统计：
- **横向误差**: 平均值、中位数、标准差、90%分位数
- **纵向误差**: 平均值、中位数、标准差、90%分位数
- **Heading误差**: 平均值、中位数、标准差、90%分位数
## 4. 评测流程设计
### 4.1 数据预处理
#### 4.1.1 真值数据解析
```python
def parse_ground_truth(gt_line, img_width, img_height):
"""
解析真值标注
返回: {
'label': int,
'bbox_2d': [x1, y1, x2, y2], # 像素坐标
'has_3d': bool,
'3d_info': {
'center': [x3d, y3d, z3d], # 原始中心点(用于非车辆类别)
'dimensions': [l3d, h3d, w3d],
'rotation': rot_y,
'faces': { # 仅车辆类别有此字段
'front': [x3d, y3d, z3d, alpha, xc, yc, score, is_occ],
'back': [x3d, y3d, z3d, alpha, xc, yc, score, is_occ],
'left': [x3d, y3d, z3d, alpha, xc, yc, score, is_occ],
'right': [x3d, y3d, z3d, alpha, xc, yc, score, is_occ]
} if label == 0 else None
} if has_3d else None
}
"""
```
#### 4.1.2 检测结果解析
```python
def parse_detection(det_line):
"""
解析检测结果
返回: {
'label': str -> int,
'confidence': float,
'bbox_2d': [x1, y1, x2, y2],
'3d_info': {
'center': [x3d, y3d, z3d],
'dimensions': [l3d, h3d, w3d],
'rotation': rot_y,
'face_type': str
} if is_3d_class else None
}
"""
```
### 4.2 2D评测流程
```
对每张图像:
1. 加载真值和检测结果
2. 对每个类别:
a. 筛选出该类别的GT和DET
b. 计算所有配对的IoU矩阵
c. 按置信度排序DET
d. 贪婪匹配（Hungarian or Greedy）
e. 统计TP, FP, FN
f. 记录置信度和匹配状态
对每个类别:
3. 根据所有图像的统计:
a. 按置信度排序所有预测
b. 计算不同阈值下的Precision-Recall
c. 计算AP (使用插值或积分)
整体统计:
4. 计算总Precision, Recall
5. 计算mAP
```
### 4.3 3D评测流程
```
对每张图像:
1. 基于2D匹配结果
2. 对每对匹配成功的(GT, DET):
a. 检查GT是否有完整3D标注
b. 检查DET是否为3D类别
c. 如果都满足:
- 如果是车辆类别(label=0):
* 根据DET的face_type选择GT中对应面的中心点
* 计算预测最近面与真值对应面的横向/纵向误差
- 如果是非车辆类别(label=1,2,3):
* 直接使用3D框中心点计算横向/纵向误差
- 计算Heading误差（所有类别相同）
- 按类别记录
对每个3D类别:
3. 统计所有图像的误差:
- 横向: mean, median, std, 90th percentile
- 纵向: mean, median, std, 90th percentile
- Heading: mean, median, std, 90th percentile
```
## 5. 实现架构
### 5.1 模块划分
```
eval_tools/
├── evaluator/
│ ├── __init__.py
│ ├── parser.py # 数据解析模块
│ ├── matcher.py # 2D匹配模块
│ ├── metrics_2d.py # 2D指标计算
│ ├── metrics_3d.py # 3D指标计算
│ ├── evaluator.py # 主评测器
│ └── visualizer.py # 结果可视化
├── configs/
│ └── eval_config.yaml # 评测配置
└── eval.py # 评测入口脚本
```
### 5.2 核心类设计
#### 5.2.1 数据解析器
```python
class GroundTruthParser:
def parse_line(self, line, img_shape)
def is_3d_annotated(self, values)
def get_class_name(self, label_id)
class DetectionParser:
def parse_line(self, line)
def map_class_name(self, name_str)
```
#### 5.2.2 匹配器
```python
class Matcher2D:
def __init__(self, iou_threshold=0.5)
def compute_iou(self, box1, box2)
def match(self, gts, dets) # 返回匹配对列表
```
#### 5.2.3 指标计算器
```python
class Metrics2D:
def __init__(self)
def add_image_results(self, matches, gts, dets, class_id)
def compute_ap(self, class_id)
def compute_map(self), face_type=None)
def compute_statistics(self, class_id)
def get_summary(self)
def _get_vehicle_face_center(self, gt_faces, face_type) # 根据face_type获取对应面中心
class Metrics3D:
def __init__(self)
def add_sample(self, gt_3d, det_3d, class_id)
def compute_statistics(self, class_id)
def get_summary(self)
```
#### 5.2.4 主评测器
```python
class Evaluator:
def __init__(self, config)
def load_ground_truth(self, gt_file)
def load_detections(self, det_file)
def evaluate_2d(self)
def evaluate_3d(self)
def generate_report(self, output_path)
```
### 5.3 配置文件示例
```yaml
# eval_config.yaml
dataset:
gt_path: "path/to/ground_truth"
det_path: "path/to/detections"
image_list: "path/to/image_list.txt"
classes:
3d_classes: [0, 1, 2, 3] # vehicle, pedestrian, bike, rider
2d_classes: [4, 5, 6, 7, 8, 9, 10, 11, 12, 13]
class_names:
0: "vehicle"
1: "pedestrian"
2: "bike"
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"
matching:
iou_threshold: 0.5
metrics_2d:
enabled: true
confidence_threshold: [0.1, 0.3, 0.5, 0.7, 0.9]
metrics_3d:
enabled: true
distance_ranges: # 可选：分距离段统计
- [0, 30]
- [30, 60]
- [60, 100]
- [100, 999]
output:
save_path: "eval_results"
format: ["json", "csv", "txt"]
visualize: true
```
## 6. 输出报告格式
### 6.1 2D评测报告
```json
{
"2d_evaluation": {
"per_class": {
"vehicle": {
"precision": 0.92,
"recall": 0.88,
"ap": 0.90,
"num_gt": 1500,
"num_det": 1450,
"tp": 1320,
"fp": 130,
"fn": 180
},
"pedestrian": {...},
...
},
"overall": {
"precision": 0.87,
"recall": 0.84,
"map": 0.85,
"num_classes": 14
}
}
}
```
### 6.2 3D评测报告
```json
{
"3d_evaluation": {
"vehicle": {
"lateral_error": {
"mean": 0.25,
"median": 0.18,
"std": 0.15,
"percentile_90": 0.45
},
"longitudinal_error": {
"mean": 1.2,
"median": 0.9,
"std": 0.8,
"percentile_90": 2.1
},
"heading_error": {
"mean": 0.08,
"median": 0.05,
"std": 0.06,
"percentile_90": 0.15
},
"num_samples": 1320
},
"pedestrian": {...},
...
}
}
```
## 7. 关键实现细节
### 7.1 IoU计算
```python
def compute_iou(box1, box2):
"""
box: [x1, y1, x2, y2]
"""
x1 = max(box1[0], box2[0])
y1 = max(box1[1], box2[1])
x2 = min(box1[2], box2[2])
y2 = min(box1[3], box2[3])
if x2 < x1 or y2 < y1:
return 0.0
intersection = (x2 - x1) * (y2 - y1)
area1 = (box1[2] - box1[0]) * (box1[3] - box1[1])
area2 = (box2[2] - box2[0]) * (box2[3] - box2[1])
union = area1 + area2 - intersection
return intersection / union if union > 0 else 0.0
```
### 7.2 AP计算（11点插值法）
```python
def compute_ap(precisions, recalls):
"""
使用VOC 11点插值法计算AP
"""
ap = 0.0
for t in np.linspace(0, 1, 11):
if np.sum(recalls >= t) == 0:
p = 0
else:
p = np.max(precisions[recalls >= t])
ap += p / 11.0
return ap
```
### 7.3 角度归一化
```python
def normalize_angle(angle):
"""
将角度归一化到[-π, π]
"""
while angle > np.pi:
angle -= 2 * np.pi
while angle < -np.pi:
angle += 2 * np.pi
return angle
```
### 7.4 坐标系转换
```python
def normalized_to_pixel(bbox_norm, img_width, img_height):
"""
归一化坐标转像素坐标
bbox_norm: [x_center, y_center, w, h] (normalized)
返回: [x1, y1, x2, y2] (pixel)
"""
x_center = bbox_norm[0] * img_width
y_center = bbox_norm[1] * img_height
w = bbox_norm[2] * img_width
h = bbox_norm[3] * img_height
x1 = x_center - w / 2
y1 = y_center - h / 2
x2 = x_center + w / 2
y2 = y_center + h / 2
return [x1, y1, x2, y2]
```
## 8. 使用示例
### 8.1 命令行使用
```bash
# 基础评测
python eval_tools/eval.py \
--gt-path /path/to/labels \
--det-path /path/to/predictions \
--output-dir eval_results
# 指定配置文件
python eval_tools/eval.py \
--config eval_tools/configs/eval_config.yaml
# 只评测2D
python eval_tools/eval.py \
--config eval_config.yaml \
--eval-2d-only
# 只评测3D
python eval_tools/eval.py \
--config eval_config.yaml \
--eval-3d-only
```
### 8.2 Python API使用
```python
from eval_tools.evaluator import Evaluator
# 创建评测器
evaluator = Evaluator(config_path='eval_config.yaml')
# 加载数据
evaluator.load_data(
gt_path='/path/to/labels',
det_path='/path/to/predictions'
)
# 执行评测
results_2d = evaluator.evaluate_2d()
results_3d = evaluator.evaluate_3d()
# 生成报告
evaluator.generate_report(
output_dir='eval_results',
formats=['json', 'csv', 'html']
)
```
## 9. 扩展性考虑
### 9.1 多IoU阈值评测
可扩展支持COCO风格的多IoU阈值（0.5:0.05:0.95）
### 9.2 距离分段评测
对3D指标按不同距离段分别统计（近距离、中距离、远距离）
### 9.3 场景分类评测
可按不同场景（白天/夜晚、晴天/雨天等）分别评测
### 9.4 时序一致性评测
对视频序列评测跟踪一致性和稳定性
## 10. 注意事项
1. **坐标系统一**: 确保GT和DET使用相同的坐标系和图像尺寸
2. **类别映射**: 注意字符串类别名和数字ID的映射关系
3. **边界情况**: 处理空检测、空真值、图像尺寸不一致等情况
4. **性能优化**: 对于大规模数据，考虑并行处理和内存优化
5. **数值精度**: 3D指标计算注意浮点数精度问题
6. **可视化**: 提供检测结果和误差分布的可视化，便于分析

712
eval_tools/docs/EVAL_FRAMEWORK_GUIDE.md Executable file
View File

@@ -0,0 +1,712 @@
# 模型评测框架使用指南
> 入口脚本：`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*

560
eval_tools/docs/EXTRACT_BAD_HEADING_USAGE.md Executable file
View File

@@ -0,0 +1,560 @@
# Bad Heading Cases Extraction Tool 使用说明
## 工具概述
`extract_bad_heading_cases.py` 用于从评估结果中提取 heading 误差较大的案例，为后续可视化分析提供数据支持。
## 功能特性
- ✅ **多条件筛选**：支持误差阈值、类别、距离、置信度等多维度过滤
- ✅ **反转错误检测**：自动识别 ≈180° 的方向反转错误
- ✅ **统计分析**：输出详细的分类统计、误差分布、距离分布等
- ✅ **Top-K 选择**：支持仅提取误差最大的 K 个案例
- ✅ **结构化输出**：生成包含元数据和统计信息的 JSON 文件
## 快速开始
### 基本用法
```bash
# 提取所有误差 > 1.5 rad 的案例
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 bad_heading_cases.json \
--stats
```
### 运行测试脚本
```bash
# 给脚本添加执行权限
chmod +x eval_tools/test_extract_bad_cases.sh
# 运行多个测试用例
./eval_tools/test_extract_bad_cases.sh
```
## 命令行参数
### 必需参数
- `--input`: 输入的 detailed_3d_matches.json 文件路径
### 可选参数
#### 筛选参数
- `--threshold`: Heading 误差阈值（弧度），默认 1.5 (≈ 85°)
- `--top-k`: 仅提取误差最大的 K 个案例
- `--classes`: 指定类别（可选多个），支持：
- `vehicle`: 车辆
- `pedestrian`: 行人
- `bicycle`: 自行车
- `rider`: 骑行者
- `--min-distance`: 最小距离（米）
- `--max-distance`: 最大距离（米）
- `--min-confidence`: 最小置信度 (0-1)
- `--reversal-only`: 仅提取反转错误（误差 > π - 0.1 ≈ 174°）
#### 输出参数
- `--output`: 输出 JSON 文件路径，默认：`bad_heading_cases.json`
- `--stats`: 打印详细统计信息
## 使用示例
### 示例 1：提取所有 bad cases
```bash
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--threshold 1.5 \
--output all_bad_cases.json \
--stats
```
**输出统计示例**：
```
Processing: 596602 matches...
Filtered: 5839 cases
=== Statistics ===
vehicle: 4012 cases (68.7% reversal)
pedestrian: 1523 cases (42.3% reversal)
bicycle: 304 cases (55.6% reversal)
Error distribution:
Mean: 2.45 rad (140.4°)
Median: 2.89 rad (165.6°)
Std: 0.78 rad
Range: [1.50, 3.14] rad
```
### 示例 2：提取 Top 50 最差案例
```bash
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--threshold 1.5 \
--top-k 50 \
--output top50_worst.json \
--stats
```
**适用场景**：
- 聚焦最严重的问题案例
- 快速定位典型错误模式
- 限制可视化数量以提高效率
### 示例 3：仅提取反转错误
```bash
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--reversal-only \
--top-k 100 \
--output reversal_errors.json \
--stats
```
**适用场景**：
- 专门分析 180° 方向反转问题
- yolov5s-300w 模型的主要问题（68.7% bad cases 是反转错误）
### 示例 4：分析特定类别
```bash
# 仅分析车辆类别
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--threshold 1.5 \
--classes vehicle \
--min-confidence 0.5 \
--top-k 50 \
--output vehicle_bad_cases.json \
--stats
```
```bash
# 分析多个类别
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--classes vehicle pedestrian \
--output vehicle_pedestrian_cases.json \
--stats
```
### 示例 5：距离筛选
```bash
# 提取中距离范围的 bad cases (30-80m)
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--threshold 1.5 \
--min-distance 30 \
--max-distance 80 \
--output mid_distance_cases.json \
--stats
```
```bash
# 提取近距离 bad cases (< 30m)
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--threshold 1.5 \
--max-distance 30 \
--output near_distance_cases.json \
--stats
```
### 示例 6：高置信度案例
```bash
# 提取高置信度但方向错误的案例（模型问题而非检测问题）
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--threshold 1.5 \
--min-confidence 0.7 \
--top-k 50 \
--output high_confidence_bad.json \
--stats
```
## 输出格式
### JSON 结构
```json
{
"metadata": {
"source": "detailed_3d_matches.json",
"threshold": 1.5,
"total_processed": 596602,
"total_extracted": 5839,
"filters": {
"classes": ["vehicle", "pedestrian"],
"min_distance": 30,
"max_distance": 80,
"min_confidence": 0.5,
"reversal_only": false,
"top_k": 100
},
"extraction_time": "2026-02-04T10:30:15"
},
"statistics": {
"vehicle": {
"count": 4012,
"reversal_count": 3266,
"reversal_percentage": 81.4,
"avg_error": 2.85,
"avg_error_deg": 163.3,
"error_distribution": {
"min": 1.50,
"max": 3.14,
"mean": 2.85,
"median": 3.02,
"std": 0.45
},
"distance_distribution": {
"min": 5.2,
"max": 98.7,
"mean": 45.3,
"median": 42.1
},
"confidence_distribution": {
"min": 0.25,
"max": 0.98,
"mean": 0.67
}
},
"pedestrian": {
"count": 1523,
"reversal_count": 644,
"reversal_percentage": 42.3,
"avg_error": 2.34,
"avg_error_deg": 134.1,
...
}
},
"cases": [
{
"case_id": "019b18ef-ca2b-7e97-8ca5-d4b1d7eefdbb_roi0",
"frame_id": "019b18f3-8d8e-70bb-8b4e-cef51fbb7089.jpg",
"class": "vehicle",
"heading_error": 3.1389,
"heading_error_deg": 179.87,
"gt_rotation": -0.0145,
"det_rotation": 3.1244,
"is_reversal": true,
"distance": 45.23,
"confidence": 0.8567,
"iou": 0.7234,
"gt_center": [42.5, -3.2, 1.5],
"det_center": [42.8, -3.4, 1.6],
"gt_dimensions": [4.5, 1.8, 1.6],
"det_dimensions": [4.3, 1.7, 1.5],
"gt_bbox_2d": [120, 340, 245, 480],
"det_bbox_2d": [118, 338, 243, 478],
"lateral_error": 0.22,
"longitudinal_error": 0.31
},
...
]
}
```
### 字段说明
#### metadata 元数据
- `source`: 输入文件路径
- `threshold`: 使用的误差阈值
- `total_processed`: 处理的总匹配数
- `total_extracted`: 提取的案例数
- `filters`: 应用的筛选条件
- `extraction_time`: 提取时间
#### statistics 统计信息
- `count`: 该类别的案例数量
- `reversal_count`: 反转错误数量
- `reversal_percentage`: 反转错误比例
- `avg_error`: 平均误差（弧度/度）
- `error_distribution`: 误差分布统计
- `distance_distribution`: 距离分布统计
- `confidence_distribution`: 置信度分布统计
#### cases 案例详情
- `case_id`, `frame_id`: 案例和帧 ID
- `class`: 目标类别
- `heading_error`: Heading 误差（弧度）
- `heading_error_deg`: Heading 误差（度）
- `gt_rotation`, `det_rotation`: 真值和检测的旋转角度
- `is_reversal`: 是否为反转错误
- `distance`: 目标距离（米）
- `confidence`: 检测置信度
- `iou`: 2D IoU
- `gt_center`, `det_center`: 3D 中心坐标
- `gt_dimensions`, `det_dimensions`: 3D 尺寸
- `gt_bbox_2d`, `det_bbox_2d`: 2D 边界框
- `lateral_error`, `longitudinal_error`: 横向和纵向误差
## 数据分析工作流
### 1. 初步探索
```bash
# 查看所有 bad cases 的统计信息
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--threshold 1.5 \
--output all_cases.json \
--stats
```
### 2. 聚焦问题
```bash
# 基于统计结果，聚焦特定问题（如反转错误）
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--reversal-only \
--classes vehicle \
--top-k 100 \
--output vehicle_reversal.json \
--stats
```
### 3. 可视化分析
```bash
# 使用提取的案例进行可视化（Tool 2）
python eval_tools/visualize_heading_errors.py \
--input vehicle_reversal.json \
--gt-dir path/to/labels \
--img-dir path/to/images \
--calib-dir path/to/calib \
--output runs/heading_viz
```
### 4. 生成报告
```bash
# 生成分析报告（Tool 4）
python eval_tools/generate_heading_report.py \
--input vehicle_reversal.json \
--viz-dir runs/heading_viz \
--output heading_analysis_report.html
```
## 典型分析场景
### 场景 1：定位反转错误根因
**目标**：理解为什么 yolov5s-300w 有 68.7% 的反转错误
```bash
# Step 1: 提取反转错误
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--reversal-only \
--top-k 200 \
--output reversal_errors.json \
--stats
# Step 2: 按类别分析
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--reversal-only \
--classes vehicle \
--output vehicle_reversal.json \
--stats
# Step 3: 按距离分析
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--reversal-only \
--min-distance 30 \
--max-distance 60 \
--output mid_dist_reversal.json \
--stats
```
### 场景 2：分析高置信度错误
**目标**：找出模型"很确信但预测错误"的案例
```bash
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--threshold 2.0 \
--min-confidence 0.8 \
--top-k 50 \
--output high_conf_bad.json \
--stats
```
### 场景 3：类别间差异分析
**目标**：对比不同类别的 heading 预测问题
```bash
# 车辆
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--classes vehicle \
--top-k 100 \
--output vehicle_analysis.json \
--stats
# 行人
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--classes pedestrian \
--top-k 100 \
--output pedestrian_analysis.json \
--stats
```
### 场景 4：距离敏感性分析
**目标**：分析 heading 误差与距离的关系
```bash
# 近距离 (< 30m)
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--max-distance 30 \
--output near_cases.json \
--stats
# 中距离 (30-60m)
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--min-distance 30 \
--max-distance 60 \
--output mid_cases.json \
--stats
# 远距离 (> 60m)
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--min-distance 60 \
--output far_cases.json \
--stats
```
## 常见问题
### Q1: 如何选择合适的阈值？
**A**: 根据评估指标选择：
- `1.0 rad (57°)`: 严格标准，仅提取严重错误
- `1.5 rad (86°)`: 推荐标准，平衡数量和质量
- `2.0 rad (115°)`: 宽松标准，包含更多一般错误
### Q2: 提取的案例太多怎么办？
**A**: 使用 `--top-k` 限制数量，或添加更多筛选条件：
```bash
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--threshold 1.5 \
--top-k 100 \
--min-confidence 0.5 \
--min-distance 20 \
--max-distance 80
```
### Q3: 如何只看反转错误？
**A**: 使用 `--reversal-only` 参数：
```bash
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--reversal-only \
--top-k 100
```
### Q4: 如何验证提取的案例是否正确？
**A**: 使用 `--stats` 查看统计信息，并检查输出 JSON 的前几个案例：
```bash
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--top-k 5 \
--stats
# 然后查看输出文件
python -m json.tool bad_heading_cases.json | head -n 100
```
## 性能优化
### 大数据集处理
对于非常大的数据集（如 596K+ 匹配），可以：
1. **先筛选再提取**：
```bash
# 先用严格条件提取少量案例
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--threshold 2.5 \
--top-k 50
```
2. **分批处理**：
```bash
# 按类别分批
for class in vehicle pedestrian bicycle rider; do
python eval_tools/extract_bad_heading_cases.py \
--input detailed_3d_matches.json \
--classes $class \
--top-k 100 \
--output ${class}_bad_cases.json
done
```
## 下一步
提取完案例后，可以使用：
1. **可视化工具** (Tool 2): `visualize_heading_errors.py`
- 生成 BEV、图像投影、角度分析图
2. **交互式查看器** (Tool 3): `heading_error_viewer.py`
- Web 界面浏览案例
3. **报告生成器** (Tool 4): `generate_heading_report.py`
- 生成 HTML/Markdown 分析报告
## 相关文档
- [Heading Error Visualization Plan](HEADING_ERROR_VISUALIZATION_PLAN.md)
- [GT Visualization Guide](../test_scripts/GT_VISUALIZATION_COMPLETE_GUIDE.md)
- [Metrics Summary](../eval_results_common_match_comparison_v1/.../METRICS_SUMMARY.md)
## 技术支持
如果遇到问题，请检查：
1. 输入文件路径是否正确
2. JSON 格式是否符合预期（包含 case_id → frames → classes → matches 结构）
3. 筛选条件是否过于严格（导致无结果）
4. Python 环境是否安装必要的库（numpy）
```bash
# 检查输入文件结构
python -c "import json; data = json.load(open('detailed_3d_matches.json')); print(f'Cases: {len(data)}, First case: {list(data.keys())[0]}')"
```

455
eval_tools/docs/HEADING_ERROR_TOOLKIT_README.md Executable file
View File

@@ -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 待实现

465
eval_tools/docs/HEADING_ERROR_VISUALIZATION_PLAN.md Executable file
View File

@@ -0,0 +1,465 @@
# 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. 指导模型改进

149
eval_tools/docs/QUICKSTART.md Executable file
View File

@@ -0,0 +1,149 @@
# 快速开始：双ROI融合模型测试
## 5分钟快速上手
### 1. 检查依赖
```bash
# 确保在项目根目录
cd /path/to/yolov5-3d
# 检查Python包
python -c "import numpy, cv2, torch; print('基础依赖OK')"
# 如果测试ONNX模型，检查onnxruntime
python -c "import onnxruntime; print('ONNX Runtime已安装')"
```
### 2. 准备模型和数据
确保以下文件存在：
- 模型文件：`release/yolov5s-30w/merged_model.onnx` 或 `.torchscript`
- 测试数据：视频bin文件或图像目录
### 3. 运行测试
#### 方式一：使用交互式脚本（推荐）
```bash
./eval_tools/test_merged_model.sh
# 然后按提示选择测试模式（1-7）
```
#### 方式二：直接命令
```bash
# ONNX模型
python eval_tools/test_val_merged_model.py \
--source /data1/dongying/Mono3d/G1M3/eval_dataset/20251210222153/sigmastar.1/camera4.bin \
--weights release/yolov5s-30w/merged_model.onnx \
--model-type onnx
# TorchScript模型
python eval_tools/test_val_merged_model.py \
--source /data1/dongying/Mono3d/G1M3/eval_dataset/20251210222153/sigmastar.1/camera4.bin \
--weights release/yolov5s-30w/merged_model.torchscript \
--model-type torchscript \
--device cuda
```
### 4. 查看结果
```bash
# 结果保存在
ls runs/val_viz_merged/exp/
# 用图像查看器打开
eog runs/val_viz_merged/exp/000000_*.jpg
# 或
display runs/val_viz_merged/exp/000000_*.jpg
```
## 常用配置
### 提高检测精度（减少误检）
```bash
python eval_tools/test_val_merged_model.py \
--source your/data/path \
--weights your/model.onnx \
--model-type onnx \
--conf-thres 0.4 \
--iou-thres 0.5
```
### 获取更多检测（增加召回）
```bash
python eval_tools/test_val_merged_model.py \
--source your/data/path \
--weights your/model.onnx \
--model-type onnx \
--conf-thres 0.15 \
--iou-thres 0.6
```
## 文件说明
| 文件 | 说明 |
|------|------|
| `test_val_merged_model.py` | 主测试脚本 |
| `test_merged_model.sh` | 交互式测试脚本（推荐） |
| `README_MERGED_MODEL.md` | 完整文档（详细说明） |
| `QUICKSTART_MERGED.md` | 本文件（快速入门） |
## 故障排查
### 问题1：找不到模块
```
ModuleNotFoundError: No module named 'utils'
```
**解决**：确保在项目根目录运行
```bash
cd /deeplearning_team/ydong/dongying/projects/yolov5-3d
python eval_tools/test_val_merged_model.py ...
```
### 问题2：ONNX Runtime错误
```
ImportError: onnxruntime not installed
```
**解决**：
```bash
pip install onnxruntime-gpu # GPU版本
# 或
pip install onnxruntime # CPU版本
```
### 问题3：CUDA内存不足
```
RuntimeError: CUDA out of memory
```
**解决**：使用CPU推理
```bash
# TorchScript模型
python eval_tools/test_val_merged_model.py \
--model-type torchscript \
--device cpu \
...
```
## 下一步
- 阅读完整文档：`README_MERGED_MODEL.md`
- 调整检测参数优化效果
- 修改代码处理更多帧（默认10帧）
- 集成到自己的推理流程
## 技术支持
遇到问题？请检查：
1. 完整文档 `README_MERGED_MODEL.md`
2. 脚本帮助 `python eval_tools/test_val_merged_model.py --help`
3. 交互式脚本选项7查看详细帮助

303
eval_tools/docs/README_VAL_MERGED.md Executable file
View File

@@ -0,0 +1,303 @@
# 合并模型评测指南
## 概述
`val_merged_model.py` 是专门用于评测合并双ROI模型的脚本。它基于 `val.py` 的评测逻辑，但针对双ROI模型进行了适配。
## 功能特性
1. **双ROI数据加载**：为ROI0和ROI1分别创建数据加载器
2. **同步推理**：同时对两个ROI进行推理
3. **跨ROI结果融合**：使用NmsForScale算法合并两个ROI的检测结果，避免重复检测
4. **完整指标计算**：计算2D mAP和3D指标（深度误差、方向误差、中心点误差）
## 工作流程
```
输入数据
↓
ROI0 Dataloader → 推理 → NMS → ↘
跨ROI融合 → 2D/3D指标计算
ROI1 Dataloader → 推理 → NMS → ↗
```
### 详细步骤
1. **加载合并模型**：加载包含 `model_roi0` 和 `model_roi1` 的合并模型
2. **创建数据加载器**：
- ROI0: 裁剪区域 [0, 120, 1920, 1080]
- ROI1: 中心区域 [704, 352]，原始图像 [1920, 1080]
3. **推理**：对两个ROI同时进行前向传播
4. **NMS**：对每个ROI的检测结果独立进行NMS
5. **跨ROI融合**：使用NmsForScale算法合并检测结果：
- 移除边缘伪影（IoU > 0.9且超出ROI边界）
- 抑制重复检测（IoU > 0.3，保留更靠近ROI中心的检测）
- 移除高度包含的检测（IoU_in > 0.8）
6. **指标计算**：对融合后的结果计算评测指标
## 使用方法
### 基本用法
```bash
python eval_tools/val_merged_model.py \
--data data/mono3d.yaml \
--weights release/yolov5s-30w/merged_model.pt \
--imgsz 704 352 \
--batch-size 1
```
### 参数说明
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--data` | `data/mono3d.yaml` | 数据集配置文件路径 |
| `--weights` | 必需 | 合并模型权重文件路径（.pt格式）|
| `--batch-size` | `1` | 批大小（仅支持1）|
| `--imgsz` | `[704, 352]` | 推理图像尺寸 [宽度, 高度] |
| `--conf-thres` | `0.001` | NMS置信度阈值（低值用于AP计算）|
| `--conf-thres-plot` | `0.25` | 可视化和3D指标的置信度阈值 |
| `--iou-thres` | `0.6` | NMS的IoU阈值 |
| `--max-det` | `300` | 每张图片最大检测数 |
| `--device` | `''` | 设备（如'0'或'cpu'）|
| `--workers` | `8` | 数据加载器工作线程数 |
| `--project` | `runs/val_merged` | 结果保存目录 |
| `--name` | `exp` | 实验名称 |
| `--verbose` | - | 按类别报告mAP |
| `--half` | - | 使用FP16半精度推理 |
### 完整示例
```bash
# 基本评测
python eval_tools/val_merged_model.py \
--data data/mono3d.yaml \
--weights release/yolov5s-30w/merged_model.pt \
--imgsz 704 352
# 使用GPU加速和半精度
python eval_tools/val_merged_model.py \
--data data/mono3d.yaml \
--weights release/yolov5s-30w/merged_model.pt \
--imgsz 704 352 \
--device 0 \
--half
# 详细输出（按类别显示mAP）
python eval_tools/val_merged_model.py \
--data data/mono3d.yaml \
--weights release/yolov5s-30w/merged_model.pt \
--imgsz 704 352 \
--verbose
# 自定义输出目录
python eval_tools/val_merged_model.py \
--data data/mono3d.yaml \
--weights release/yolov5s-30w/merged_model.pt \
--imgsz 704 352 \
--project runs/my_eval \
--name merged_exp1
```
## 输出结果
### 控制台输出
评测过程中会实时显示：
```
Class Images Instances P R mAP50 mAP50-95 Matched Depth(m) Orient(°) Center(m)
all 50 150 0.856 0.823 0.891 0.672 89 2.345 12.678 0.234
```
- **Class**: 类别名称
- **Images**: 处理的图片数量
- **Instances**: 真实标注数量
- **P**: 精确率
- **R**: 召回率
- **mAP50**: mAP@0.5
- **mAP50-95**: mAP@0.5:0.95
- **Matched**: 3D匹配的检测数
- **Depth(m)**: 平均深度误差（米）
- **Orient(°)**: 平均方向误差（度）
- **Center(m)**: 平均中心点误差（米）
### 最终统计
```
3D Metrics (Fused ROI0+ROI1):
Total matched: 89
Depth error (abs): 2.345m
Orientation error: 12.678°
Center error: 0.234m
```
### 保存的文件
结果保存在 `--project/--name` 目录下：
- `confusion_matrix.png`: 混淆矩阵图
- `F1_curve.png`: F1曲线
- `P_curve.png`: 精确率曲线
- `R_curve.png`: 召回率曲线
- `PR_curve.png`: PR曲线
## ROI配置
脚本内置了ROI配置，与 `test_val_merged_model.py` 保持一致：
```python
# ROI0: 裁剪区域
roi0 = (0, 120, 1920, 1080)
ori_img_size_roi0 = None
# ROI1: 中心区域
roi1 = (704, 352)
ori_img_size_roi1 = (1920, 1080)
# 跨ROI NMS使用的ROI坐标（原始图像坐标系）
roi_list = [
(0, 120, 1920, 1080), # ROI0
(608, 364, 1312, 716) # ROI1在原始图像中的坐标
]
```
## 跨ROI NMS算法
`NmsForScale` 函数实现了跨ROI的检测融合：
1. **边缘伪影过滤**：
- 计算检测框与ROI的IoU
- 如果IoU > 0.9且检测框超出ROI边界，则移除
2. **重复检测抑制**：
- 对于来自不同ROI的检测框
- 如果IoU > 0.3（高度重叠）
- 保留距离ROI中心更近的检测
3. **包含关系处理**：
- 如果一个检测框被另一个检测框高度包含（IoU_in > 0.8）
- 移除被包含的检测框
## 注意事项
1. **批大小限制**：合并模型评测仅支持 `batch_size=1`
2. **模型格式**：仅支持PyTorch .pt格式的合并模型（包含Model_Merged类）
3. **数据集要求**：数据集必须包含3D标注（48列标签格式）
4. **内存使用**：同时加载两个ROI的数据会增加内存使用
5. **速度**：由于需要推理两个ROI和跨ROI融合，速度会比单ROI评测慢
## 与单ROI评测的对比
| 特性 | val.py (单ROI) | val_merged_model.py (双ROI) |
|------|----------------|------------------------------|
| 批大小 | 支持任意 | 仅支持1 |
| 数据加载器 | 单个 | 两个（ROI0+ROI1）|
| 推理次数 | 1次/图像 | 2次/图像 |
| NMS | 单次 | 2次独立+跨ROI融合 |
| 结果 | 单ROI检测 | 融合后的全图检测 |
| 速度 | 快 | 较慢（约2倍推理时间）|
| 覆盖范围 | 单个ROI | 全图覆盖 |
## 故障排除
### 问题1：模型加载失败
```
ValueError: Model at xxx is not a merged dual-ROI model
```
**解决方法**：确保模型是通过 `merge_models_of_2roi.py` 创建的合并模型，包含 `model_roi0` 和 `model_roi1` 属性。
### 问题2：数据加载器长度不匹配
```
WARNING Dataloader lengths mismatch: ROI0=100, ROI1=98
```
**解决方法**：检查数据集配置，确保两个ROI访问相同的图像文件。
### 问题3：路径不匹配
```
WARNING Path mismatch: xxx vs yyy
```
**解决方法**：这通常表示两个数据加载器返回的图像顺序不一致，检查数据集配置和路径。
### 问题4：内存不足
**解决方法**：
- 减少 `--workers` 数量
- 使用 `--half` 启用FP16推理
- 在CPU上运行：`--device cpu`
## 相关文件
- `val.py`: 单ROI模型评测脚本
- `merge_models_of_2roi.py`: 合并两个ROI模型的脚本
- `test_val_merged_model.py`: 合并模型推理测试脚本（仅推理，不计算指标）
- `val_merged_model.py`: 本脚本，合并模型完整评测
## 工作流程示例
完整的训练+合并+评测流程：
```bash
# 1. 训练ROI0模型
python train_mono3d.py --data data/mono3d.yaml --roi 0 120 1920 1080 --weights yolov5s.pt
# 2. 训练ROI1模型
python train_mono3d.py --data data/mono3d.yaml --roi 704 352 --ori-img-size 1920 1080 --weights yolov5s.pt
# 3. 评测单个模型（可选）
python val.py --weights runs/train/roi0_exp/weights/last.pt --data data/mono3d.yaml --roi 0 120 1920 1080
python val.py --weights runs/train/roi1_exp/weights/last.pt --data data/mono3d.yaml --roi 704 352 --ori-img-size 1920 1080
# 4. 合并模型
python eval_tools/merge_models_of_2roi.py \
--roi0_model_path runs/train/roi0_exp/weights/last.pt \
--roi1_model_path runs/train/roi1_exp/weights/last.pt \
--save_dir release/merged \
--skip-export # 仅保存合并模型，不导出ONNX
# 5. 评测合并模型
python eval_tools/val_merged_model.py \
--data data/mono3d.yaml \
--weights release/merged/merged_model.pt \
--imgsz 704 352
# 6. 推理测试（可选）
python eval_tools/test_val_merged_model.py \
--source /path/to/test/images \
--weights release/merged/merged_model.pt \
--model-type torchscript
```
## 扩展说明
如果需要修改ROI配置，编辑脚本中的以下部分：
```python
# 在 run() 函数中，约第375行
roi0 = (0, 120, 1920, 1080) # 修改ROI0坐标
roi1 = (704, 352) # 修改ROI1尺寸
ori_img_size_roi1 = (1920, 1080) # 修改原始图像尺寸
# 在跨ROI NMS部分，约第431行
roi_list = [
(0, 120, 1920, 1080), # ROI0坐标
(608, 364, 1312, 716) # ROI1在原始图像中的坐标（需要计算）
]
```
计算ROI1在原始图像中的坐标：
```python
# 如果ROI1是中心裁剪，计算方式：
ori_w, ori_h = 1920, 1080
roi1_w, roi1_h = 704, 352
x1 = (ori_w - roi1_w) // 2 # 608
y1 = (ori_h - roi1_h) // 2 # 364
x2 = x1 + roi1_w # 1312
y2 = y1 + roi1_h # 716
```

146
eval_tools/docs/ROI_FIX_GUIDE.md Executable file
View File

@@ -0,0 +1,146 @@
# ROI坐标转换问题解决方案
## 问题描述
评测结果中precision和recall都为0，经过诊断发现是**ROI坐标转换问题**。
## 根本原因
1. **检测结果使用ROI坐标系**：保存在`txt_results`中的检测框坐标是在ROI裁剪区域的坐标系中（尺寸: 704x352）
2. **Ground Truth使用原图坐标系**：GT标注使用的是归一化的原图坐标（尺寸: 1920x1080）
3. **坐标不匹配导致IoU=0**：两个坐标系不一致，所有框的IoU都是0，无法匹配
## ROI参数
针对`evalset_roi0`数据集：
- **ROI区域**: [0, 120, 1920, 1080] (xyxy格式)
- **ROI输入尺寸**: 704 x 352 (模型输入尺寸)
- **原图尺寸**: 1920 x 1080
### 坐标转换公式
检测框从ROI坐标转换到原图坐标：
```python
# 1. 缩放
scale_x = (1920 - 0) / 704 = 2.7273
scale_y = (1080 - 120) / 352 = 2.7273
x1_scaled = x1 * scale_x
x2_scaled = x2 * scale_x
y1_scaled = y1 * scale_y
y2_scaled = y2 * scale_y
# 2. 偏移
x1_final = x1_scaled + 0
x2_final = x2_scaled + 0
y1_final = y1_scaled + 120
y2_final = y2_scaled + 120
```
## 解决方案
### 1. 修改DetectionParser
在`parser.py`中添加ROI缩放和偏移支持：
```python
def __init__(self, roi_offset=None, roi_scale=None):
self.roi_offset = roi_offset or (0, 0)
self.roi_scale = roi_scale or (1.0, 1.0)
```
在解析2D框时应用转换：
```python
# 先缩放
x1 *= self.roi_scale[0]
x2 *= self.roi_scale[0]
y1 *= self.roi_scale[1]
y2 *= self.roi_scale[1]
# 再偏移
x1 += self.roi_offset[0]
y1 += self.roi_offset[1]
x2 += self.roi_offset[0]
y2 += self.roi_offset[1]
```
### 2. 更新Evaluator和eval.py
添加`roi_offset`和`roi_scale`参数传递。
### 3. 更新命令行参数
```bash
--roi 0 120 1920 1080 # ROI区域
--roi-input-size 704 352 # ROI输入尺寸
```
## 验证结果
### 修复前
```
GT bbox range: x=[18.0, 1919.0], y=[465.0, 751.0]
Det bbox range: x=[9.5, 704.6], y=[126.1, 236.8]
IoU: 0.0000
Matches: 0
```
### 修复后
```
GT bbox range: x=[18.0, 1919.0], y=[465.0, 751.0]
Det bbox range (scaled): x=[25.9, 1921.6], y=[463.9, 765.8]
Matches: 16/20
First match IoU: 0.8397
```
### 评测结果（100帧测试）
```
2D Metrics:
Precision: 0.9141
Recall: 0.6105
mAP: 0.2066
3D Metrics:
pedestrian: Lat=0.795m, Long=1.726m, Head=1.140rad (n=8)
vehicle: Lat=0.987m, Long=1.731m, Head=0.247rad (n=995)
```
## 使用方法
### 完整评测（81443帧）
```bash
bash eval_tools/run_evaluation_example.sh
```
### 快速测试（100帧）
```bash
bash eval_tools/run_evaluation_quick_test.sh
```
### 手动运行
```bash
python eval_tools/eval.py \
--det-path /path/to/detections \
--gt-path /path/to/gt \
--output-dir results \
--img-width 1920 \
--img-height 1080 \
--roi 0 120 1920 1080 \
--roi-input-size 704 352
```
## 注意事项
1. **ROI1的参数不同**：如果评测ROI1的结果，需要修改ROI参数
2. **不同模型的输入尺寸可能不同**：根据实际模型调整`--roi-input-size`
3. **大数据集评测耗时**：81443帧约需10-20分钟，建议先用quick test验证
## 相关文件
- `eval_tools/evaluator/parser.py` - 添加ROI转换逻辑
- `eval_tools/evaluator/evaluator.py` - 传递ROI参数
- `eval_tools/eval.py` - 命令行参数处理
- `eval_tools/run_evaluation_example.sh` - 完整评测脚本
- `eval_tools/run_evaluation_quick_test.sh` - 快速测试脚本

437
eval_tools/docs/ROI_GT_PROCESSING_GUIDE.md Executable file
View File

@@ -0,0 +1,437 @@
# Ground Truth ROI Processing for Evaluation
## 概述
为了确保评测指标的准确性，评测时需要对Ground Truth（真值标签）进行与训练时相同的ROI过滤和截断处理。这确保了评测时GT和检测结果在同一坐标系下进行比较。
## 问题背景
### 训练时的处理
在模型训练时，数据经过以下ROI处理（参考 `utils/dataloaders3d.py`中的`post_process_labels_to_roi`）：
1. **ROI计算**：基于标定参数计算灭点（vanishing point），以灭点为中心裁剪ROI区域
2. **标签过滤**：移除完全在ROI外的目标
3. **边界截断**：将部分在ROI内的目标边界框clip到ROI边界
4. **坐标转换**：将标签坐标从原图坐标系转换到ROI相对坐标系
5. **特殊处理**：对cut-in/cut-out目标进行特殊标记
### 评测时的问题
之前的评测代码中：
- **检测结果**：在ROI坐标系中（已经过ROI裁剪和resize）
- **GT标签**：在原图坐标系中（未经ROI处理）
- **结果**：坐标系不匹配，导致IoU为0，评测指标不准确
## 解决方案
新增 `ROIProcessor` 模块，在评测时对GT标签进行与训练时相同的ROI处理。
### 核心模块
#### 1. ROIProcessor 类
位置：`eval_tools/evaluator/roi_processor.py`
**主要功能**：
- 加载标定参数
- 计算ROI区域（基于灭点）
- 对GT标签进行ROI过滤和截断
**关键方法**：
```python
class ROIProcessor:
def __init__(self, calib_root, roi_config, ori_img_size):
"""初始化ROI处理器
Args:
calib_root: 标定文件根目录
roi_config: ROI配置（[width, height]或[x1, y1, x2, y2]）
ori_img_size: 原图尺寸 (width, height)
"""
def compute_roi(self, calib_params):
"""计算ROI区域
基于灭点计算规则：
- crop_center_x = oriW // 2
- crop_center_y = cy - fy * tan(pitch)
- ROI以crop_center为中心裁剪
"""
def process_annotations_with_roi(self, annotations, roi_bounds):
"""对标注进行ROI过滤和截断
处理逻辑：
1. 移除完全在ROI外的目标
2. clip边界框到ROI范围
3. 转换坐标到ROI相对坐标系
"""
```
#### 2. Evaluator 更新
位置：`eval_tools/evaluator/evaluator.py`
**主要更新**：
- 集成 `ROIProcessor`
- 在worker函数中对GT进行ROI处理
- 支持多进程评测时的ROI处理
## 使用方法
### 1. 配置文件方式（推荐）
创建配置文件（参考 `eval_tools/configs/eval_config_with_roi_gt.yaml`）：
```yaml
# Dataset paths
dataset:
det_path: "/path/to/detection_results"
gt_path: "/path/to/ground_truth"
# Image properties
image:
width: 1920
height: 1080
# ROI Ground Truth Processing
roi_gt:
enabled: true # 启用GT的ROI处理
calib_root: "/path/to/calibrations" # 标定文件根目录（包含各case的camera4.json）
roi_config: [1920, 960] # ROI配置，必须与训练配置一致！
# 其他配置...
```
运行评测：
```bash
python eval_tools/core/eval.py --config eval_tools/configs/eval_config_with_roi_gt.yaml
```
### 2. ROI配置说明
#### 方式1：尺寸模式（常用）
```yaml
roi_config: [1920, 960] # [width, height]
```
- ROI以灭点为中心裁剪
- width和height指定ROI的宽度和高度
- **必须与训练时yaml中的roi配置一致**
训练配置对应（`data/mono3d.yaml`）：
```yaml
# For ROI0
roi: [1920, 960] # 训练时配置
# For ROI1
# roi: [704, 352] # 训练时配置
```
#### 方式2：边界模式
```yaml
roi_config: [0, 120, 1920, 1080] # [x1, y1, x2, y2]
```
- 固定的ROI边界
- 适用于已知固定ROI的情况
### 3. 标定文件要求
ROI处理需要标定参数来计算灭点。标定文件结构：
```
calib_root/
├── case1/
│ └── camera4.json # 标定文件
├── case2/
│ └── camera4.json
└── ...
```
标定文件格式（`camera4.json`）：
```json
{
"focal_u": 1450.0,
"focal_v": 1450.0,
"cu": 960.0,
"cv": 540.0,
"yaw": 0.0,
"pitch": -5.0,
"distort_coeffs": [0.1, 0.05, 0.02, 0.01]
}
```
**关键参数**：
- `focal_u`, `focal_v`: 焦距
- `cu`, `cv`: 主点坐标
- `pitch`: 俯仰角（用于计算灭点）
### 4. 完整评测示例
#### ROI0模型评测
```bash
python eval_tools/core/eval.py \
--config eval_tools/configs/eval_config_with_roi_gt.yaml \
--det-path /data/inference_results/roi0 \
--gt-path /data/ground_truth
```
配置文件中：
```yaml
roi_gt:
enabled: true
calib_root: "/data/ground_truth"
roi_config: [1920, 960] # ROI0配置
```
#### ROI1模型评测
配置文件中修改：
```yaml
roi_gt:
enabled: true
calib_root: "/data/ground_truth"
roi_config: [704, 352] # ROI1配置
```
## ROI处理流程
### 1. GT标签ROI处理流程
```
原始GT标签（原图坐标系）
↓
加载标定参数
↓
计算灭点位置
vanish_y = cy - fy * tan(pitch)
crop_center = (oriW//2, vanish_y)
↓
计算ROI区域
roi_x1 = crop_center_x - roi_width/2
roi_y1 = crop_center_y - roi_height/2
roi_x2 = roi_x1 + roi_width
roi_y2 = roi_y1 + roi_height
↓
过滤GT标签
1. 移除完全在ROI外的目标
2. 保留完全在ROI内的目标
3. 保留部分在ROI内的目标
↓
截断边界框
clip bbox到ROI边界
↓
坐标转换
转换到ROI相对坐标系
↓
处理后的GT标签（ROI坐标系）
↓
与检测结果匹配和评测
```
### 2. 核心计算公式
#### 灭点计算
```python
vanish_y = cy - fy * tan(pitch * π/180)
crop_center_x = image_width // 2
crop_center_y = vanish_y
```
#### ROI边界计算
```python
roi_x1 = crop_center_x - roi_width / 2
roi_y1 = crop_center_y - roi_height / 2
roi_x2 = roi_x1 + roi_width
roi_y2 = roi_y1 + roi_height
```
#### 坐标转换
```python
# 原图坐标 -> ROI相对坐标
new_x1 = x1 - roi_x1
new_y1 = y1 - roi_y1
new_x2 = x2 - roi_x1
new_y2 = y2 - roi_y1
# Clip到ROI边界
new_x1 = clip(new_x1, 0, roi_width-1)
new_y1 = clip(new_y1, 0, roi_height-1)
new_x2 = clip(new_x2, 0, roi_width-1)
new_y2 = clip(new_y2, 0, roi_height-1)
```
## 实现细节
### 1. 多进程支持
ROI处理支持多进程评测，每个worker进程独立创建ROI处理器：
```python
@staticmethod
def _process_frame_3d(pair, ...):
from .roi_processor import ROIProcessor
# 在worker中创建ROI处理器
if 'roi_processor_config' in pair:
roi_processor = ROIProcessor(...)
gts, _ = roi_processor.process_case_frame(...)
```
### 2. 标定缓存
ROI处理器会缓存已加载的标定参数，避免重复读取：
```python
self.calib_cache = {} # case_name -> calib_params
```
### 3. 处理标记
处理后的标注会添加额外标记：
```python
{
'bbox_2d': [x1, y1, x2, y2], # ROI相对坐标
'roi_relative': True, # 标记已转换
'roi_bounds': (x1, y1, x2, y2), # 记录ROI边界
'was_clipped': False, # 是否被clip
'3d_info': {
'partially_visible': True # 3D目标是否部分可见
}
}
```
## 注意事项
### 1. ROI配置一致性
**关键**：评测时的ROI配置必须与训练时完全一致！
- 训练配置：`data/mono3d.yaml` 中的 `roi: [width, height]`
- 评测配置：`eval_config_with_roi_gt.yaml` 中的 `roi_config: [width, height]`
不一致会导致评测结果不准确。
### 2. 标定文件路径
确保 `calib_root` 指向正确的标定文件目录：
```python
calib_root/
├── case_name1/
│ └── camera4.json
├── case_name2/
│ └── camera4.json
```
### 3. 坐标系说明
- **原图坐标系**：(0, 0)在左上角，范围[0, 1920]×[0, 1080]
- **ROI坐标系**：(0, 0)在ROI左上角，范围[0, roi_width]×[0, roi_height]
- **归一化坐标**：YOLO格式，范围[0, 1]
### 4. 边界情况处理
- 完全在ROI外的目标：直接过滤
- 部分在ROI内的目标：保留并clip到边界
- 3D信息处理：部分可见目标标记为 `partially_visible`
## 验证方法
### 1. 检查ROI处理是否生效
运行评测时查看日志：
```
ROI processor enabled for GT filtering with config: [1920, 960]
```
### 2. 对比有无ROI处理的结果
```bash
# 不使用ROI处理
python eval_tools/core/eval.py --config eval_config_no_roi.yaml
# 使用ROI处理
python eval_tools/core/eval.py --config eval_config_with_roi_gt.yaml
```
预期：使用ROI处理后，评测指标应该更准确（Precision和Recall不会异常低）。
### 3. 验证GT数量
- ROI处理前：所有原图中的GT
- ROI处理后：仅ROI内的GT（数量应该减少）
可以在代码中添加调试输出：
```python
print(f"GT before ROI: {len(gts_before)}")
print(f"GT after ROI: {len(gts_after)}")
```
## 性能考虑
1. **标定缓存**：每个case的标定参数只加载一次
2. **多进程支持**：支持多进程并行评测
3. **内存优化**：按需加载和处理
## 故障排查
### 问题1：找不到标定文件
```
Warning: Calibration file not found for case xxx
```
**解决**：检查 `calib_root` 路径和标定文件名（camera4.json）
### 问题2：评测结果仍然异常
**检查项**：
1. ROI配置是否与训练一致
2. 标定文件是否正确
3. 图像尺寸配置是否正确
### 问题3：GT数量为0
**原因**：所有GT都在ROI外被过滤
**检查**：ROI配置是否过小或位置偏移
## 示例脚本
### Python API使用
```python
from eval_tools.evaluator import Evaluator, ROIProcessor
# 创建ROI处理器
roi_processor = ROIProcessor(
calib_root="/path/to/calibrations",
roi_config=[1920, 960],
ori_img_size=(1920, 1080)
)
# 处理GT标签
annotations, roi_bounds = roi_processor.process_case_frame(
case_name="case1",
frame_name="frame001",
annotations=gt_annotations
)
# 创建评测器（配置版）
config = {
'roi_gt': {
'enabled': True,
'calib_root': '/path/to/calibrations',
'roi_config': [1920, 960]
}
}
evaluator = Evaluator(config=config)
```
## 总结
通过引入 `ROIProcessor` 和更新评测流程，现在评测时的GT标签会经过与训练时相同的ROI处理，确保了：
1. ✅ GT和检测结果在同一坐标系
2. ✅ 完全在ROI外的目标被正确过滤
3. ✅ 部分在ROI内的目标被正确截断
4. ✅ 评测指标准确反映模型性能
**关键要点**：
- 评测配置必须与训练配置一致
- 需要提供正确的标定文件
- 支持多进程和不同ROI配置

379
eval_tools/docs/TWO_LEVEL_PATH_EXAMPLE.md Executable file
View File

@@ -0,0 +1,379 @@
# Example: Using 2-Level Path Structure for Model Evaluation
This example demonstrates how to evaluate models with 2-level directory structures.
## Scenario
You have organized your test data with an additional level of hierarchy:
```
/data/detections/
├── G1M3_AFS1616/ # Level 1: Dataset/configuration name
│ ├── case_001/ # Level 2: Individual test cases
│ │ └── txt_results/
│ │ ├── frame001.txt
│ │ └── frame002.txt
│ └── case_002/
│ └── txt_results/
│ └── frame001.txt
└── G1M3_AFS1920/
└── case_003/
└── txt_results/
└── frame001.txt
/data/ground_truth/
├── G1M3_AFS1616/
│ ├── case_001/
│ │ └── labels/
│ │ ├── frame001.txt
│ │ └── frame002.txt
│ └── case_002/
│ └── labels/
│ └── frame001.txt
└── G1M3_AFS1920/
└── case_003/
└── labels/
└── frame001.txt
```
## Step 1: Create Configuration File
Create `eval_tools/configs/eval_config_2level_example.yaml`:
```yaml
# Evaluation Configuration for 2-Level Path Structure
dataset:
det_path: "/data/detections"
gt_path: "/data/ground_truth"
path_depth: 2 # Enable 2-level structure
image:
width: 1920
height: 1080
model:
input_size: 704
min_box_size_at_input_scale: 8
performance:
num_workers: 32
roi_gt:
enabled: true
calib_root: "/data/ground_truth"
roi_config: [1920, 960]
roi:
enabled: false
region: [0, 120, 1920, 1080]
input_size: [704, 352]
classes:
3d_classes: [0, 1, 2, 3]
2d_classes: [4, 5, 6, 7, 8, 9, 10, 11, 12, 13]
class_names:
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"
matching:
iou_threshold: 0.5
metrics_2d:
enabled: true
conf_threshold: 0.3
ap_method: "voc2010"
metrics_3d:
enabled: true
heading_tolerance: "both"
distance_ranges:
- [0, 20]
- [20, 40]
- [40, 60]
- [60, 80]
- [80, 100]
- [100, 999]
lateral_distance_ranges:
- [-50, -40]
- [-40, -30]
- [-30, -20]
- [-20, -10]
- [-10, 0]
- [0, 10]
- [10, 20]
- [20, 30]
- [30, 40]
- [40, 50]
output:
save_path: "evaluation_results/2level_example/{timestamp}"
formats: ["json", "txt"]
print_details: true
per_case_reports: true
```
## Step 2: Run Evaluation
### Method 1: Using Config File
```bash
python eval_tools/core/eval.py \
--config eval_tools/configs/eval_config_2level_example.yaml \
--save-detailed-matches
```
### Method 2: Command Line Override
```bash
python eval_tools/core/eval.py \
--config eval_tools/configs/eval_config_2level_example.yaml \
--path-depth 2 \
--det-path /data/detections \
--gt-path /data/ground_truth \
--output-dir evaluation_results/custom_output
```
### Method 3: Without Config File
```bash
python eval_tools/core/eval.py \
--det-path /data/detections \
--gt-path /data/ground_truth \
--path-depth 2 \
--img-width 1920 \
--img-height 1080 \
--iou-threshold 0.5 \
--conf-threshold 0.3 \
--heading-tolerance both \
--output-dir evaluation_results/2level_test
```
## Step 3: Compare Two Models with 2-Level Paths
### Create Config for Model 1
`eval_tools/configs/eval_config_model1_2level.yaml`:
```yaml
dataset:
det_path: "/data/model1/detections"
gt_path: "/data/ground_truth"
path_depth: 2
# ... other settings ...
```
### Create Config for Model 2
`eval_tools/configs/eval_config_model2_2level.yaml`:
```yaml
dataset:
det_path: "/data/model2/detections"
gt_path: "/data/ground_truth"
path_depth: 2
# ... other settings ...
```
### Update Comparison Script
Edit `eval_tools/model_comparison/compare_models_with_common_matches.sh`:
```bash
#!/bin/bash
set -e
# Configuration
MODEL1_CONFIG="eval_tools/configs/eval_config_model1_2level.yaml"
MODEL2_CONFIG="eval_tools/configs/eval_config_model2_2level.yaml"
OUTPUT_BASE="evaluation_results/2level_comparison"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
MODEL1_NAME="model1"
MODEL2_NAME="model2"
# Step 1: Evaluate Model 1
echo "Step 1: Evaluating Model 1..."
MODEL1_OUTPUT="${OUTPUT_BASE}/${MODEL1_NAME}/${TIMESTAMP}"
python eval_tools/core/eval.py \
--config ${MODEL1_CONFIG} \
--output-dir ${MODEL1_OUTPUT} \
--save-detailed-matches
# Step 2: Evaluate Model 2
echo "Step 2: Evaluating Model 2..."
MODEL2_OUTPUT="${OUTPUT_BASE}/${MODEL2_NAME}/${TIMESTAMP}"
python eval_tools/core/eval.py \
--config ${MODEL2_CONFIG} \
--output-dir ${MODEL2_OUTPUT} \
--save-detailed-matches
# Step 3: Find common matches
echo "Step 3: Finding common matches..."
COMMON_MATCHES_DIR="${OUTPUT_BASE}/common_matches_${TIMESTAMP}"
mkdir -p ${COMMON_MATCHES_DIR}
python eval_tools/model_comparison/find_common_matches.py \
--model1-matches ${MODEL1_OUTPUT}/detailed_3d_matches.json \
--model2-matches ${MODEL2_OUTPUT}/detailed_3d_matches.json \
--output ${COMMON_MATCHES_DIR}/common_matches.json \
--model1-name "${MODEL1_NAME}" \
--model2-name "${MODEL2_NAME}"
# Step 4: Compare models
echo "Step 4: Comparing models..."
COMPARISON_DIR="${OUTPUT_BASE}/comparison_${TIMESTAMP}"
python eval_tools/model_comparison/compare_models.py \
--model1 ${MODEL1_OUTPUT}/evaluation_report.json \
--model2 ${MODEL2_OUTPUT}/evaluation_report.json \
--model1-name "${MODEL1_NAME}" \
--model2-name "${MODEL2_NAME}" \
--common-matches ${COMMON_MATCHES_DIR}/common_matches.json \
--output-dir ${COMPARISON_DIR}
echo "✓ Comparison complete!"
echo "Results: ${COMPARISON_DIR}/comparison_report.txt"
```
### Run Comparison
```bash
bash eval_tools/model_comparison/compare_models_with_common_matches.sh
```
## Expected Output
```
================================================================================
YOLOv5-3D Model Evaluation
================================================================================
Detection path: /data/detections
Ground truth path: /data/ground_truth
Path depth: 2
Output directory: evaluation_results/2level_example/20260211_143022
Image size: 1920x1080
IoU threshold: 0.5
Confidence threshold: 0.3
AP method: voc2010
Heading tolerance: both
Number of workers: 32
Evaluate 2D: True
Evaluate 3D: True
Save detailed matches: Yes
================================================================================
Loading data...
Found 3 case(s) in detection root: /data/detections (path_depth=2)
Loaded 5 image pairs for evaluation
==================================================
Evaluating 2D Detection Metrics
==================================================
Processing case [1/3]: case_001 (2 frames)
case_001: 100%|████████████████████| 2/2 [00:00<00:00, 45.23it/s]
Processing case [2/3]: case_002 (1 frames)
case_002: 100%|████████████████████| 1/1 [00:00<00:00, 48.12it/s]
Processing case [3/3]: case_003 (2 frames)
case_003: 100%|████████████████████| 2/2 [00:00<00:00, 46.87it/s]
==================================================
Evaluating 3D Detection Metrics
==================================================
Processing case [1/3]: case_001 (2 frames)
case_001: 100%|████████████████████| 2/2 [00:00<00:00, 42.15it/s]
Processing case [2/3]: case_002 (1 frames)
case_002: 100%|████████████████████| 1/1 [00:00<00:00, 43.89it/s]
Processing case [3/3]: case_003 (2 frames)
case_003: 100%|████████████████████| 2/2 [00:00<00:00, 41.76it/s]
Detailed 3D matches saved to: evaluation_results/2level_example/20260211_143022/detailed_3d_matches.json
JSON report saved to: evaluation_results/2level_example/20260211_143022/evaluation_report.json
Text report saved to: evaluation_results/2level_example/20260211_143022/evaluation_report.txt
Per-case reports saved to: evaluation_results/2level_example/20260211_143022/per_case_reports/ (3 cases)
================================================================================
EVALUATION SUMMARY - OVERALL
================================================================================
2D Metrics:
Precision: 0.8542
Recall: 0.8123
mAP: 0.8234
3D Metrics:
vehicle [overall]: Lat=0.234m, Long=0.456m, Head=0.123rad (relaxed=0.098rad, rev=12) (n=145)
pedestrian [overall]: Lat=0.189m, Long=0.312m, Head=0.234rad (relaxed=0.187rad, rev=8) (n=67)
================================================================================
✓ Evaluation completed successfully!
```
## Troubleshooting
### Issue: No cases found
**Check:**
1. Verify `path_depth` is set correctly (1 or 2)
2. Ensure directory structure matches the expected format
3. Check that level1 directory names match between det_path and gt_path
### Issue: Some cases are skipped
**Check:**
1. Each case must have `txt_results/` subdirectory (for detections)
2. Each case must have `labels/` subdirectory (for ground truth)
3. Frame names must match between detections and labels
### Issue: GT case directory not found
**Check:**
1. Level1 directory names must be identical in both paths
2. Case names must be identical in both paths
3. Path structure must be consistent
## Benefits of 2-Level Structure
1. **Better Organization**: Group related test cases by dataset or configuration
2. **Flexible Comparison**: Compare models across different datasets easily
3. **Scalability**: Handle large numbers of test cases more efficiently
4. **Backward Compatible**: Existing 1-level structures continue to work
## Migration from 1-Level to 2-Level
If you have existing 1-level structure and want to migrate:
```bash
# Original structure
/data/detections/case1/txt_results/
/data/detections/case2/txt_results/
# Create 2-level structure
mkdir -p /data/detections_2level/dataset_A
mv /data/detections/case1 /data/detections_2level/dataset_A/
mv /data/detections/case2 /data/detections_2level/dataset_A/
# Update config
# path_depth: 1 → path_depth: 2
# det_path: /data/detections → /data/detections_2level
```

228
eval_tools/docs/TWO_LEVEL_PATH_SUPPORT.md Executable file
View File

@@ -0,0 +1,228 @@
# Two-Level Path Support for Model Evaluation
## Overview
The evaluation system now supports both 1-level and 2-level directory structures for detection results and ground truth labels. This allows for more flexible organization of test data.
## Directory Structures
### 1-Level Structure (Default)
```
det_root/
case1/
txt_results/
frame001.txt
frame002.txt
case2/
txt_results/
frame001.txt
gt_root/
case1/
labels/
frame001.txt
frame002.txt
case2/
labels/
frame001.txt
```
### 2-Level Structure
```
det_root/
level1_dir/
case1/
txt_results/
frame001.txt
frame002.txt
case2/
txt_results/
frame001.txt
level2_dir/
case3/
txt_results/
frame001.txt
gt_root/
level1_dir/
case1/
labels/
frame001.txt
frame002.txt
case2/
labels/
frame001.txt
level2_dir/
case3/
labels/
frame001.txt
```
## Configuration
### YAML Configuration File
Add the `path_depth` parameter to your config file:
```yaml
dataset:
det_path: "/path/to/detection/results"
gt_path: "/path/to/ground/truth"
path_depth: 2 # Set to 1 for 1-level, 2 for 2-level structure
```
**Example for 1-level structure:**
```yaml
dataset:
det_path: "/data1/dongying/Mono3d/G1M3/CNCAP_results/mono3d/evalset_roi0"
gt_path: "/mnt/mono3d/xdzhu_data/Mono3d/Testdata"
path_depth: 1 # Default
```
**Example for 2-level structure:**
```yaml
dataset:
det_path: "/data1/dongying/Mono3d/G1M3/CNCAP_results/mono3d"
gt_path: "/mnt/mono3d/xdzhu_data/Mono3d/Mono3d_4face_2m_g1m3/driving_png"
path_depth: 2
```
### Command-Line Arguments
You can also specify the path depth via command line:
```bash
# 1-level structure (default)
python eval_tools/core/eval.py \
--config eval_tools/configs/eval_config_mono3d.yaml
# 2-level structure
python eval_tools/core/eval.py \
--config eval_tools/configs/eval_config_mono3d.yaml \
--path-depth 2
# Or without config file
python eval_tools/core/eval.py \
--det-path /path/to/detections \
--gt-path /path/to/labels \
--path-depth 2 \
--output-dir results
```
## How It Works
### 1-Level Mode (`path_depth=1`)
1. Scans `det_root` for all subdirectories (cases)
2. For each case, looks for `txt_results/` subdirectory
3. Matches with corresponding `gt_root/case/labels/` directory
### 2-Level Mode (`path_depth=2`)
1. Scans `det_root` for all subdirectories (level1 directories)
2. For each level1 directory, scans for case subdirectories
3. For each case, looks for `txt_results/` subdirectory
4. Matches with corresponding `gt_root/level1/case/labels/` directory
**Important:** The level1 directory names must match between detection and ground truth paths.
## Model Comparison Script
The comparison script automatically inherits the `path_depth` setting from the config files:
```bash
bash eval_tools/model_comparison/compare_models_with_common_matches.sh
```
The script will:
1. Read `path_depth` from `eval_config_mono3d.yaml` for Model 1
2. Read `path_depth` from `eval_config_yolov5s.yaml` for Model 2
3. Evaluate both models with their respective path structures
4. Compare results using common matches
## Examples
### Example 1: Evaluating with 2-level structure
```bash
# Update your config file
cat > eval_tools/configs/eval_config_2level.yaml << EOF
dataset:
det_path: "/data/results/all_models"
gt_path: "/data/ground_truth/all_datasets"
path_depth: 2
image:
width: 1920
height: 1080
# ... other settings ...
EOF
# Run evaluation
python eval_tools/core/eval.py --config eval_tools/configs/eval_config_2level.yaml
```
### Example 2: Comparing models with different path structures
```yaml
# Model 1 config (1-level)
dataset:
det_path: "/data/model1/results"
gt_path: "/data/gt"
path_depth: 1
# Model 2 config (2-level)
dataset:
det_path: "/data/model2/results"
gt_path: "/data/gt_organized"
path_depth: 2
```
Both models can be compared even with different directory structures.
## Backward Compatibility
- If `path_depth` is not specified, it defaults to `1` (1-level structure)
- All existing config files and scripts continue to work without modification
- The system automatically detects and handles both structures
## Troubleshooting
### Issue: "GT case directory not found"
**Cause:** Level1 directory names don't match between detection and ground truth paths.
**Solution:** Ensure that the intermediate directory names are identical:
```
det_root/dataset_A/case1/ ← "dataset_A" must match
gt_root/dataset_A/case1/ ← "dataset_A" must match
```
### Issue: "No image pairs found"
**Cause:** Incorrect `path_depth` setting.
**Solution:**
- Check your actual directory structure
- Set `path_depth: 1` for `root/case/txt_results`
- Set `path_depth: 2` for `root/level1/case/txt_results`
### Issue: Cases are being skipped
**Cause:** Missing `txt_results/` or `labels/` subdirectories.
**Solution:** Verify that each case directory contains:
- Detection: `case/txt_results/*.txt`
- Ground truth: `case/labels/*.txt`
## Implementation Details
The changes are implemented in:
- `eval_tools/evaluator/evaluator.py`: Modified `load_data_from_paths()` method
- `eval_tools/core/eval.py`: Added `--path-depth` argument and config support
- `eval_tools/configs/*.yaml`: Added `path_depth` parameter
The implementation maintains full backward compatibility while adding support for 2-level structures.

194
eval_tools/docs/VEHICLE_3D_METRICS_BUG_ANALYSIS.md Executable file
View File

@@ -0,0 +1,194 @@
# 车辆 3D 指标异常分析与修复
**问题发现日期**：2026-03-09
**涉及文件**：`eval_tools/evaluator/metrics_3d.py`、`eval_tools/evaluator/evaluator.py`
---
## 一、问题现象
在 deeplearning vs deploy 模型对比评测（CNCAP 数据集，ROI1）中发现以下异常：
| 指标 | deeplearning | deploy | 相对差异 |
|---|---|---|---|
| **车辆纵向相对误差（Overall）** | 0.1209 | 0.0711 | -41.20% |
然而，将 overall 分解为各纵向分段后，两模型指标几乎相同（差异 < 1%）：
| 区间 | LongRel (dl) | LongRel (dep) | 差异 |
|---|---|---|---|
| 0-10m | 0.2883 | 0.2842 | -1.41% |
| 10-20m | 0.0328 | 0.0328 | -0.07% |
| 20-30m | 0.0408 | 0.0410 | +0.27% |
| … | … | … | … |
**典型特征**：overall 与各分段差异巨大，但各分段两模型差距极小。
---
## 二、问题根因：三个 Bug
### Bug 1（主因）：面中心 z 坐标用于相对误差计算和分段路由
**位置**：`metrics_3d.py::add_sample()` 和 `evaluator.py::_process_frame_3d()`
**问题**：对于车辆，`gt_center` 使用的是 GT 面中心坐标（front/back/left/right face）。在计算纵向相对误差和分段路由时直接用该 z 值：
```python
# 修复前
longitudinal_distance = gt_center[2] # 面中心 z（可能趋近 0 或为负）
gt_depth = max(abs(gt_center[2]), 1e-6) # 面中心 z 作为分母
longitudinal_relative_error = longitudinal_error / gt_depth
```
**后果**：
- 近距离侧面/后面标注的面中心 z 可能 ≤ 0（面中心在相机平面附近甚至后方）
- 当 `face_z ≈ 0` 时，`gt_depth = 1e-6`，`longitudinal_relative_error` 爆炸（可达数万）
- 当 `face_z ≤ 0` 时，`_get_longitudinal_distance_range()` 返回 `None`，样本**不进任何 `long_*` 分段**，但仍留在 `overall`
**量化影响**（修复前）：
| 模型 | overall 样本数 | long_* 总样本数 | 未分段数 | overall 均值 | long_* 加权均值 |
|---|---|---|---|---|---|
| deeplearning | 5744 | 5737 | 7 | 0.0711 | 0.0574 |
| deploy | 5755 | 5731 | **24** | **0.1207** | 0.0577 |
deploy 命中更多面中心 z 异常样本（24 vs 7），被误判为性能更差。
---
### Bug 2：evaluator.py 与 metrics_3d.py 参考点不一致
**位置**：`evaluator.py::_process_frame_3d()` 的 `save_detailed_matches` 代码块
**问题**：`detailed_3d_matches.json` 中存储的 `gt_center_3d` 和 `distance` 字段使用了整体中心而非面中心，与 `metrics_3d.py` 不一致。
**后果**：`compare_models_with_common_matches.sh` 整条流水线基于 `detailed_3d_matches.json`，修复 `metrics_3d.py` 对这条路径完全无效。
---
### Bug 3（次要）：面中心哨兵值 [-1.0, -1.0, -1.0] 未过滤
**位置**：`metrics_3d.py::_get_vehicle_face_center()` 和 `evaluator.py` 中相应逻辑
**问题背景**：GT 标注中，当某面不可见时（`is_visible_from_camera = 0`），该面的三维坐标被设为哨兵值 -1.0：
```
"3d_right": [-1.0, -1.0, -1.0, -1.0, -1.0, -1.0, 0.0, 0.0]
x3d y3d z3d alpha xc yc score is_visible=0
```
**代码只检查 `face_data is not None`，不检查可见性标志**，导致：
- `gt_center = [-1.0, -1.0, -1.0]` 被当成真实坐标
- `longitudinal_error = |det_z - (-1.0)| ≈ 8~18m`（虚假巨大误差）
- `lateral_error = |det_x - (-1.0)| ≈ 2~5m`（虚假巨大误差）
**现象**：修复 Bug 1 后，0-10m 分段出现新的异常——deeplearning 比 deploy **差 24%**（纵向误差），但该差异仅来自哨兵值命中数量不同（dl: 15个，deploy: 5个）。
---
## 三、修复方案
### 修复 Bug 1 + Bug 2：使用整体中心 z 进行分段路由和相对误差计算
**`metrics_3d.py`**（`add_sample()` 方法）：
```python
# 修复后：使用整体中心 z 作为分段路由和相对误差分母
gt_whole_z = gt['3d_info']['center'][2]
gt_depth = max(abs(gt_whole_z), 1e-6)
longitudinal_relative_error = longitudinal_error / gt_depth
longitudinal_distance = gt['3d_info']['center'][2] # 整体中心 z
```
**`evaluator.py`**（`_process_frame_3d()` 方法）：
```python
# 修复后
gt_whole_z = gt['3d_info']['center'][2]
gt_depth = max(abs(gt_whole_z), 1e-6)
longitudinal_relative_error = longitudinal_error / gt_depth
'distance': {
'longitudinal': float(gt_whole_z), # 用整体中心 z 做分段路由
'lateral': float(gt_center[0])
}
```
---
### 修复 Bug 3：过滤哨兵值面数据
**`metrics_3d.py`**（`_get_vehicle_face_center()` 方法）：
```python
face_data = gt_3d_info['faces'].get(normalized_face_type)
# 检查 is_visible_from_camera (face_data[7]) 和哨兵值
if face_data is None or (len(face_data) >= 8 and face_data[7] == 0) or face_data[2] <= 0:
return gt_3d_info['center'] # fallback 到整体中心
return face_data[:3]
```
**`evaluator.py`**（`_process_frame_3d()` 方法）：
```python
face_valid = (
face_data is not None and
face_data[2] > 0 and
not (len(face_data) >= 8 and face_data[7] == 0)
)
gt_center = face_data[:3] if face_valid else gt['3d_info']['center']
```
---
## 四、修复效果
### Overall 指标对比
| 版本 | deeplearning | deploy | 差异 | 说明 |
|---|---|---|---|---|
| 原始（有 Bug） | 0.1209 | 0.0711 | -41.20% | 假性差异 |
| 修复 Bug1+Bug2 | 0.0594 | 0.0535 | -9.91% | 改善但仍偏 |
| 修复全部 Bug | **0.0547** | **0.0521** | **-4.72%** | 合理差异 |
### 0-10m 分段指标对比
| 版本 | Long 差异 | Lat 差异 | 说明 |
|---|---|---|---|
| 修复 Bug1+Bug2 后 | -25.14% | -24.42% | 哨兵值污染 |
| 修复全部 Bug 后 | **-14.0%** | **-3.85%** | 合理（Lat 持平） |
---
## 五、设计建议
1. **参考点一致性原则**：`metrics_3d.py` 与 `evaluator.py` 生成的 `detailed_3d_matches.json` 必须使用相同的参考点逻辑，否则两条评测路径产生不同结果。
2. **分段路由 vs 误差计算解耦**：分段路由应始终使用整体目标中心 z（稳定、不受面可见性影响），误差计算可使用面中心（业务语义正确）。
3. **哨兵值防御**：任何使用 GT 面数据的地方，必须先检查 `is_visible_from_camera`（第 8 维）和 `face_z > 0`，防止哨兵值 `-1.0` 污染计算。
4. **`compare_models_with_common_matches.sh` 的数据流**：该脚本 **不经过** `metrics_3d.py`，而是完全基于 `detailed_3d_matches.json` 重新聚合。因此 `evaluator.py` 中写入 JSON 的字段计算逻辑必须与 `metrics_3d.py` 保持严格一致。
---
## 六、GT 面数据格式说明
```
face_data = [x3d, y3d, z3d, alpha, xc, yc, score, is_visible_from_camera]
索引: 0 1 2 3 4 5 6 7
is_visible_from_camera:
1 = 该面在相机视野中可见，(x3d, y3d, z3d) 为有效坐标
0 = 该面不可见，(x3d, y3d, z3d) 填充哨兵值 -1.0
```
GT 面数据来源参考 CLAUDE.md → "3D Label Format (47 dimensions per line)"：
- dim15~22: front face
- dim23~30: rear face
- dim31~38: left face
- dim39~46: right face
每组最后一维 `is_visible_from_camera` 即为可见性标志。

698
eval_tools/docs/det_format.json Executable file
View File

@@ -0,0 +1,698 @@
{
"0": {
"type": "0",
"type_name": "vehicle",
"score": "0.9326733946800232",
"roi_id": "0",
"box2d": [
"331.8140869140625",
"561.717529296875",
"586.11767578125",
"717.2656860351562"
],
"xyzlhwyaw": [
"-4.009787559509277",
"0.926640510559082",
"11.942784309387207",
"4.302463054656982",
"1.562669038772583",
"1.921964168548584",
"0.4575636684894562"
],
"face_cls": "front",
"cut_cls": "0",
"cut_cls_name": "nocut"
},
"1": {
"type": "0",
"type_name": "vehicle",
"score": "0.9156705737113953",
"roi_id": "0",
"box2d": [
"100.69953918457031",
"564.6636352539062",
"242.32601928710938",
"715.1654052734375"
],
"xyzlhwyaw": [
"-6.425538063049316",
"0.8240152597427368",
"7.582361698150635",
"4.374484062194824",
"1.5695128440856934",
"1.9310325384140015",
"0.7510586380958557"
],
"face_cls": "front",
"cut_cls": "0",
"cut_cls_name": "nocut"
},
"2": {
"type": "0",
"type_name": "vehicle",
"score": "0.9065446853637695",
"roi_id": "0",
"box2d": [
"472.00469970703125",
"549.619140625",
"716.2294311523438",
"703.78857421875"
],
"xyzlhwyaw": [
"-2.9637675285339355",
"0.8307619094848633",
"14.574830055236816",
"4.347611904144287",
"1.6718649864196777",
"1.915984869003296",
"0.5434975624084473"
],
"face_cls": "front",
"cut_cls": "0",
"cut_cls_name": "nocut"
},
"3": {
"type": "0",
"type_name": "vehicle",
"score": "0.9034286141395569",
"roi_id": "0",
"box2d": [
"24.04340934753418",
"543.9300537109375",
"103.02033233642578",
"706.6632690429688"
],
"xyzlhwyaw": [
"-10.928886413574219",
"0.8560043573379517",
"8.215371131896973",
"4.361935615539551",
"1.6075832843780518",
"1.9334548711776733",
"0.9796556830406189"
],
"face_cls": "tail",
"cut_cls": "2",
"cut_cls_name": "cutout"
},
"4": {
"type": "2",
"type_name": "bicycle",
"score": "0.8614475131034851",
"roi_id": "0",
"box2d": [
"1036.5008544921875",
"620.2924194335938",
"1273.9559326171875",
"938.4365234375"
],
"xyzlhwyaw": [
"0.6904441118240356",
"0.7800710797309875",
"5.036780834197998",
"1.619232416152954",
"1.1915533542633057",
"0.6803989410400391",
"-1.1483073234558105"
],
"face_cls": "whole",
"cut_cls": "-1",
"cut_cls_name": "none"
},
"5": {
"type": "2",
"type_name": "bicycle",
"score": "0.8564509153366089",
"roi_id": "0",
"box2d": [
"781.7294311523438",
"616.6049194335938",
"1012.9938354492188",
"873.3040161132812"
],
"xyzlhwyaw": [
"-0.3779735267162323",
"0.9046416282653809",
"6.767831325531006",
"1.599935531616211",
"1.189906120300293",
"0.6568350791931152",
"-0.9946095943450928"
],
"face_cls": "whole",
"cut_cls": "-1",
"cut_cls_name": "none"
},
"6": {
"type": "2",
"type_name": "bicycle",
"score": "0.844305694103241",
"roi_id": "0",
"box2d": [
"664.0404052734375",
"626.8478393554688",
"819.7224731445312",
"821.651123046875"
],
"xyzlhwyaw": [
"-1.293802261352539",
"0.9600279331207275",
"8.032365798950195",
"1.6238980293273926",
"1.1767773628234863",
"0.6766071319580078",
"-1.2385268211364746"
],
"face_cls": "whole",
"cut_cls": "-1",
"cut_cls_name": "none"
},
"7": {
"type": "0",
"type_name": "vehicle",
"score": "0.8426833748817444",
"roi_id": "0",
"box2d": [
"211.8482208251953",
"565.5682983398438",
"396.64324951171875",
"717.7545776367188"
],
"xyzlhwyaw": [
"-5.606781482696533",
"0.8764306902885437",
"9.388605117797852",
"4.418740749359131",
"1.546727180480957",
"1.9304075241088867",
"0.8216855525970459"
],
"face_cls": "front",
"cut_cls": "0",
"cut_cls_name": "nocut"
},
"8": {
"type": "4",
"type_name": "roadblock",
"score": "0.8416956067085266",
"roi_id": "0",
"box2d": [
"1598.6632080078125",
"656.9686279296875",
"1647.850341796875",
"769.2286987304688"
],
"xyzlhwyaw": [
"-1",
"-1",
"-1",
"-1",
"-1",
"-1",
"-1"
],
"face_cls": "none",
"cut_cls": "-1",
"cut_cls_name": "none"
},
"9": {
"type": "0",
"type_name": "vehicle",
"score": "0.8231446146965027",
"roi_id": "0",
"box2d": [
"1834.783203125",
"528.106689453125",
"1919.451904296875",
"648.326416015625"
],
"xyzlhwyaw": [
"11.375432968139648",
"0.6048312187194824",
"10.385001182556152",
"4.3299241065979",
"1.6334497928619385",
"1.9212439060211182",
"-2.5305209159851074"
],
"face_cls": "front",
"cut_cls": "1",
"cut_cls_name": "cutin"
},
"10": {
"type": "0",
"type_name": "vehicle",
"score": "0.8213036060333252",
"roi_id": "0",
"box2d": [
"1158.3846435546875",
"546.5782470703125",
"1567.0697021484375",
"746.7042846679688"
],
"xyzlhwyaw": [
"2.3088035583496094",
"0.7716936469078064",
"9.184979438781738",
"4.231507778167725",
"1.5341267585754395",
"1.8410688638687134",
"-2.5499801635742188"
],
"face_cls": "left",
"cut_cls": "0",
"cut_cls_name": "nocut"
},
"11": {
"type": "0",
"type_name": "vehicle",
"score": "0.7833787202835083",
"roi_id": "0",
"box2d": [
"1763.1807861328125",
"545.0386352539062",
"1840.17529296875",
"604.3870849609375"
],
"xyzlhwyaw": [
"22.13104820251465",
"0.8831890821456909",
"22.32408905029297",
"4.351836204528809",
"1.5954947471618652",
"1.9008938074111938",
"-2.7008376121520996"
],
"face_cls": "left",
"cut_cls": "0",
"cut_cls_name": "nocut"
},
"12": {
"type": "0",
"type_name": "vehicle",
"score": "0.7422913312911987",
"roi_id": "0",
"box2d": [
"1657.364501953125",
"542.6961669921875",
"1714.572265625",
"611.0717163085938"
],
"xyzlhwyaw": [
"14.675742149353027",
"0.7690245509147644",
"21.358781814575195",
"4.2856221199035645",
"1.6538622379302979",
"1.9027550220489502",
"1.6300535202026367"
],
"face_cls": "front",
"cut_cls": "0",
"cut_cls_name": "nocut"
},
"13": {
"type": "0",
"type_name": "vehicle",
"score": "0.7374464273452759",
"roi_id": "0",
"box2d": [
"1338.939697265625",
"475.69091796875",
"1645.552734375",
"641.1358032226562"
],
"xyzlhwyaw": [
"4.492400646209717",
"0.47527050971984863",
"12.608644485473633",
"4.7827959060668945",
"2.110551357269287",
"2.027017116546631",
"-2.5330119132995605"
],
"face_cls": "left",
"cut_cls": "0",
"cut_cls_name": "nocut"
},
"14": {
"type": "0",
"type_name": "vehicle",
"score": "0.7201020121574402",
"roi_id": "0",
"box2d": [
"1792.420166015625",
"539.8333740234375",
"1877.2738037109375",
"620.86767578125"
],
"xyzlhwyaw": [
"14.51260757446289",
"0.7203327417373657",
"15.318050384521484",
"4.332417964935303",
"1.5717623233795166",
"1.922214150428772",
"-2.566664934158325"
],
"face_cls": "front",
"cut_cls": "1",
"cut_cls_name": "cutin"
},
"15": {
"type": "2",
"type_name": "bicycle",
"score": "0.7104725241661072",
"roi_id": "0",
"box2d": [
"1308.8502197265625",
"642.7114868164062",
"1452.3756103515625",
"927.2647705078125"
],
"xyzlhwyaw": [
"1.6400929689407349",
"0.7745605111122131",
"4.959465980529785",
"1.5869669914245605",
"1.1547799110412598",
"0.6512892246246338",
"-0.8955580592155457"
],
"face_cls": "whole",
"cut_cls": "-1",
"cut_cls_name": "none"
},
"16": {
"type": "8",
"type_name": "plate",
"score": "0.6805570125579834",
"roi_id": "0",
"box2d": [
"1316.4764404296875",
"792.7472534179688",
"1388.9088134765625",
"833.673828125"
],
"xyzlhwyaw": [
"-1",
"-1",
"-1",
"-1",
"-1",
"-1",
"-1"
],
"face_cls": "none",
"cut_cls": "-1",
"cut_cls_name": "none"
},
"17": {
"type": "2",
"type_name": "bicycle",
"score": "0.6681439876556396",
"roi_id": "0",
"box2d": [
"1400.7972412109375",
"617.092529296875",
"1517.8599853515625",
"818.230712890625"
],
"xyzlhwyaw": [
"2.5161986351013184",
"0.8316869735717773",
"6.546628952026367",
"1.6171674728393555",
"1.1810991764068604",
"0.6666929721832275",
"-0.9673029184341431"
],
"face_cls": "whole",
"cut_cls": "-1",
"cut_cls_name": "none"
},
"18": {
"type": "2",
"type_name": "bicycle",
"score": "0.6465133428573608",
"roi_id": "0",
"box2d": [
"961.9541015625",
"608.6699829101562",
"1143.5264892578125",
"833.4479370117188"
],
"xyzlhwyaw": [
"0.39372718334198",
"0.8915371298789978",
"7.160281181335449",
"1.6071021556854248",
"1.1925380229949951",
"0.6709716320037842",
"-1.0681982040405273"
],
"face_cls": "whole",
"cut_cls": "-1",
"cut_cls_name": "none"
},
"19": {
"type": "9",
"type_name": "wheel",
"score": "0.6345217823982239",
"roi_id": "0",
"box2d": [
"1873.107666015625",
"599.4207763671875",
"1907.8341064453125",
"647.875"
],
"xyzlhwyaw": [
"-1",
"-1",
"-1",
"-1",
"-1",
"-1",
"-1"
],
"face_cls": "none",
"cut_cls": "-1",
"cut_cls_name": "none"
},
"20": {
"type": "0",
"type_name": "vehicle",
"score": "0.6081775426864624",
"roi_id": "0",
"box2d": [
"891.8013916015625",
"519.721923828125",
"1173.1517333984375",
"624.479248046875"
],
"xyzlhwyaw": [
"0.34501999616622925",
"0.6041234731674194",
"23.56036949157715",
"5.08701229095459",
"2.1216015815734863",
"2.116706371307373",
"0.39338308572769165"
],
"face_cls": "right",
"cut_cls": "0",
"cut_cls_name": "nocut"
},
"21": {
"type": "9",
"type_name": "wheel",
"score": "0.5973491668701172",
"roi_id": "0",
"box2d": [
"575.4360961914062",
"641.5838623046875",
"602.0896606445312",
"705.3988037109375"
],
"xyzlhwyaw": [
"-1",
"-1",
"-1",
"-1",
"-1",
"-1",
"-1"
],
"face_cls": "none",
"cut_cls": "-1",
"cut_cls_name": "none"
},
"22": {
"type": "2",
"type_name": "bicycle",
"score": "0.5623676776885986",
"roi_id": "0",
"box2d": [
"1163.057861328125",
"550.9451904296875",
"1555.3499755859375",
"754.7815551757812"
],
"xyzlhwyaw": [
"2.7768852710723877",
"0.8014246225357056",
"9.575440406799316",
"4.110759258270264",
"1.5350842475891113",
"1.747300148010254",
"-2.9602367877960205"
],
"face_cls": "whole",
"cut_cls": "-1",
"cut_cls_name": "none"
},
"23": {
"type": "0",
"type_name": "vehicle",
"score": "0.5153718590736389",
"roi_id": "0",
"box2d": [
"893.3780517578125",
"469.33447265625",
"1190.5335693359375",
"600.2640991210938"
],
"xyzlhwyaw": [
"0.46041613817214966",
"0.2556573748588562",
"24.425113677978516",
"5.909259796142578",
"2.6501197814941406",
"2.329179286956787",
"0.4991776645183563"
],
"face_cls": "right",
"cut_cls": "0",
"cut_cls_name": "nocut"
},
"24": {
"type": "4",
"type_name": "roadblock",
"score": "0.4548017382621765",
"roi_id": "0",
"box2d": [
"1379.612548828125",
"734.7178344726562",
"1431.492919921875",
"880.1078491210938"
],
"xyzlhwyaw": [
"-1",
"-1",
"-1",
"-1",
"-1",
"-1",
"-1"
],
"face_cls": "none",
"cut_cls": "-1",
"cut_cls_name": "none"
},
"25": {
"type": "9",
"type_name": "wheel",
"score": "0.4520576000213623",
"roi_id": "0",
"box2d": [
"473.79718017578125",
"549.5919189453125",
"717.8395385742188",
"704.925537109375"
],
"xyzlhwyaw": [
"-1",
"-1",
"-1",
"-1",
"-1",
"-1",
"-1"
],
"face_cls": "none",
"cut_cls": "-1",
"cut_cls_name": "none"
},
"26": {
"type": "0",
"type_name": "vehicle",
"score": "0.4148864448070526",
"roi_id": "0",
"box2d": [
"1341.7711181640625",
"535.1429443359375",
"1590.530517578125",
"630.9032592773438"
],
"xyzlhwyaw": [
"3.6830179691314697",
"0.7231490612030029",
"11.925402641296387",
"4.3222455978393555",
"1.6602001190185547",
"1.889768362045288",
"-2.6474227905273438"
],
"face_cls": "left",
"cut_cls": "0",
"cut_cls_name": "nocut"
},
"27": {
"type": "0",
"type_name": "vehicle",
"score": "0.3970497250556946",
"roi_id": "0",
"box2d": [
"526.6994018554688",
"503.987060546875",
"750.5567016601562",
"635.5084838867188"
],
"xyzlhwyaw": [
"-3.048304796218872",
"0.5863527655601501",
"17.065431594848633",
"4.724325656890869",
"2.1064600944519043",
"2.043461322784424",
"0.5458307862281799"
],
"face_cls": "front",
"cut_cls": "0",
"cut_cls_name": "nocut"
},
"28": {
"type": "9",
"type_name": "wheel",
"score": "0.3437325358390808",
"roi_id": "0",
"box2d": [
"417.23626708984375",
"658.1126708984375",
"444.47637939453125",
"715.48876953125"
],
"xyzlhwyaw": [
"-1",
"-1",
"-1",
"-1",
"-1",
"-1",
"-1"
],
"face_cls": "none",
"cut_cls": "-1",
"cut_cls_name": "none"
}
}

93
eval_tools/docs/eval_instruction.md Executable file
View File

@@ -0,0 +1,93 @@
- 真值说明
- 3D真值类别：{0: vehicle, 1: pedestrian, 2: bike, 3: rider}
- 车辆3D目标真值示例
- ```
label: 1,
x: 2, y: 3, w: 4, h: 5,
x3d_ori: 6, y3d_ori: 7, z3d_ori: 8,
13d: 9, h3d: 10, w3d: 11,
rot_y: 12,
xc_ori: 13, yc_ori: 14,
xc_ori_d: 15, yc_ori_d: 16,
alpha_ori: 17,
0: 18,
# the first face
x3d: 19, y3d: 20, z3d: 21, alpha: 22, xc: 23, yc: 24, score: 25, is occ: 26,
# the second face
x3d: 27, y3d: 28, z3d: 29, alpha: 30, xc: 31, yc: 32, score: 33, is_occ: 34,
# the third face
x3d: 35, y3d: 36, z3d: 37, alpha: 38, xc: 39, yc: 40, score: 41, is_occ: 42,
# the forth face
x3d: 43, y3d: 44, z3d: 45, alpha: 46, xc: 47, yc: 48, score: 49, is_occ: 50
```
- 说明：如上面所示，车辆目标的3D真值中共50个数值，其中，第一个数值为label（标签格式为数字），2-5是2D框信息（归一化后的中心点和宽高），6-8是中心点坐标，9-11是车辆3D尺寸信息，12为heading信息；19-50是四个面的3D信息，包含面的中心点坐标等，四个面的顺序为：前、后、左、右。
- 注意：有的车辆目标只有2D框信息，此时，真值为6个数值，最后一位为-1，具体格式为：
```
label:1, x: 2, y: 3, w: 4, h: 5, -1: 6
```
- 非车辆类别3D目标真值示例
- ```
label: 1,
x: 2, y: 3, w: 4, h: 5,
x3d_ori: 6, y3d_ori: 7, z3d_ori: 8,
13d: 9, h3d: 10, w3d: 11,
rot_y: 12,
xc_ori: 13, yc_ori: 14,
xc_ori_d: 15, yc_ori_d: 16,
alpha_ori: 17,
0: 18,
```
- 说明：如上面所示，非车辆类别目标的3D真值中共18个数值，其中，第一个数值为label（标签格式为数字），2-5是2D框信息（归一化后的中心点和宽高），6-8是中心点坐标，9-11是3D尺寸信息，12为heading信息；
- 注意：有的非车辆目标只有2D框信息，此时，真值为6个数值，最后一位为-1，具体格式为：
```
label:1, x: 2, y: 3, w: 4, h: 5, -1: 6
```
- 纯2D真值类别：{4: roadblock, 5: head, 6: tsr, 7: guideboard, 8: plate, 9: wheel, 10: tl_border, 11: tl_wick, 12: tl_num, 13: tricycle}
真值格式为：
```
label:1, x: 2, y: 3, w: 4, h: 5, -1: 6
```
- 检测结果说明
- 3D目标类别
- 车辆目标的检测结果格式为：
- ```
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
```
- 说明：如上面所示，车辆目标的检测结果中共15个数值，其中，第一个数值为label（格式为字符串），第二个为置信度，3-6为2D框信息（左上和右下角点的像素坐标），8-10为预测的最近面的中心点坐标，11-13为车辆的3D尺寸信息，14为heading信息，15为预测的最近面类别。
- 非车辆目标的检测结果格式为：
- ```
pedestrian 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 whole
```
- 说明：如上面所示，行人目标的检测结果中共15个数值，其中，第一个数值为label（格式为字符串），第二个为置信度，3-6为2D框信息（左上和右下角点的像素坐标），8-10为预测的3d box中心点坐标，11-13为3d box的3D尺寸信息，14为heading信息，15为填充位（非车辆类别都为whole）。
- 纯2D类别
输出格式：
plate 0.94246 532.12 203.26 558.73 214.86
评测内容：
2D: 每个类别的召回率，准确率和AP(iou=0.5)，以及总的召回率，准确率和mAP。
3D: 评测每个3D类别的横向测距指标、纵向测距指标和heading偏差。

2180
eval_tools/docs/gt_format.json Executable file
View File

File diff suppressed because it is too large Load Diff

13
eval_tools/docs/results_txt_format.md Executable file
View File

@@ -0,0 +1,13 @@
2D classes:
class_name confidence x1 y1 x2 y2
example:
tl_border 0.22863 988.54 498.59 997.36 506.38
wheel 0.92207 501.83 737.12 557.60 890.73
3D classes:
class_name confidence x1 y1 x2 y2 cam x3d_face y3d_face z3d_face l h w yaw face_type
example:
vehicle 0.96654 206.40 516.75 698.04 887.78 cam -2.65 0.62 3.79 4.60 1.56 1.98 -1.54 tail
pedestrian 0.12859 1103.98 549.13 1110.26 564.57 cam 9.41 1.55 110.09 0.89 1.67 0.68 -1.58 whole