单目3D初始代码

eval_tools/docs/DISTANCE_RANGES_GUIDE.md

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