# 距离区间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` - 测试脚本