yolov26_3d/eval_tools/docs/DISTANCE_RANGES_GUIDE.md

距离区间3D评测功能说明

功能描述

新增了按距离区间统计3D检测误差的功能，可以分析模型在不同距离范围内的性能表现。

配置方法

在配置文件 eval_config.yaml 中的 metrics_3d 部分添加 distance_ranges：

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. 使用配置文件

python eval_tools/eval.py \
    --config eval_tools/configs/eval_config.yaml \
    --roi 0 120 1920 1080 \
    --roi-input-size 704 352

2. 快速测试

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 - 测试脚本