yolov26_3d/评测设计.md

# `analyze_val_two_roi_badcases.py` 评测设计说明

本文描述当前脚本 `tools/pdcl_inference/analyze_val_two_roi_badcases.py` 的真实输出内容、评测口径和统计方式。相关实现还涉及：

- `tools/pdcl_inference/two_roi_inference.py`
- `ultralytics/utils/plotting_3d.py`
- `ultralytics/utils/metrics.py`
- `ultralytics/utils/metrics_3d.py`

## 1. 脚本定位

这个脚本不是训练期 validator 的简单包装，而是一个离线分析工具。它的目标是：

- 对 `val/train/test` split 做逐样本推理
- 生成 per-ROI 的 2D/3D 指标汇总
- 输出按类别、距离、框尺寸、可见面 bucket 分解后的统计
- 导出坏例 CSV
- 生成坏例可视化与 HTML 报告
- 可选生成数据画像 `portrait`

默认会分析两个 ROI：

- `roi0`
- `roi1`

## 2. 主流程

每个 ROI 的主流程如下：

1. 读取 split 列表，得到每个样本的 `label_path`。
2. 根据 label 推导 image/calib 路径。
3. 构造 ROI 图像和 ROI 标定。
4. 跑模型，拿到：
   - 2D 检测结果
   - `preds_3d`
   - `preds_edge`
   - `anchors`
   - `strides`
5. 同一张图会走两套预测用途：
   - 一套低阈值预测，用于 2D AP/PR/F1 曲线搜索
   - 一套正式阈值预测，用于 3D 匹配、坏例导出和报告
6. 对 GT 与 Pred 做贪心匹配。
7. 基于匹配结果生成 object-level record。
8. 把 record 聚合进 overall / class / breakdown / interval 等 bucket。
9. 结束后统一写出 CSV、JSON、Markdown、HTML 和可视化。

## 3. 匹配规则

## 3.1 主匹配规则

用于 3D 指标、坏例和 2D thresholded 指标的主匹配规则是：

- 条件：`IoU >= 0.5`
- 要求：类别一致
- 策略：按 IoU 从高到低贪心匹配，保证一对一

对应函数：

- `greedy_match_indices(...)`

## 3.2 2D AP 的 TP 计算

用于 `mAP50` 和 `mAP50-95` 的 TP 计算是标准 COCO 风格：

- IoU 阈值：`0.50:0.95`，步长 `0.05`
- 每个阈值单独做一次贪心匹配
- 然后调用 `ap_per_class(...)`

对应函数：

- `compute_2d_tp_matrix(...)`
- `summarize_2d_ap_store(...)`

## 3.3 focused confusion 的匹配

focused confusion matrix 用的是“任意类别 IoU 匹配”：

- 先只按 `IoU >= 0.5` 做 greedy match
- 再把“预测类别 vs GT 类别”记到 confusion matrix

这么做的目的不是算检测 AP，而是专门看“已经局部对上目标之后的分类混淆”。

对应函数：

- `update_subset_confusion_matrix(...)`

## 4. 2D 指标设计

## 4.1 AP / mAP

脚本会先以很低阈值收集候选框：

- `threshold_search_conf = min(bundle.spec.conf, 0.001)`

然后计算：

- `map50_2d`
- `map50_95_2d`
- 每类的 `map50/map50_95`
- PR/F1 曲线

同时还会从 mean F1 curve 里挑一个推荐阈值：

- `recommended_confidence_2d`

其定义是：

- 对所有类别的 F1 曲线取均值
- 先做 `smooth(..., 0.1)`
- 取最大值对应的 confidence

## 4.2 thresholded 2D 指标

在 `recommended_confidence_2d` 下，脚本会再算一套 thresholded 2D 指标：

- `gt_total`
- `pred_total`
- `matched_2d`
- `precision_2d = matched_2d / pred_total`
- `recall_2d = matched_2d / gt_total`
- `f1_2d`
- `false_negatives_2d = gt_total - matched_2d`
- `false_positives_2d = pred_total - matched_2d`

这些会出现在：

- overall summary
- `class_metrics.csv`
- `summary.json`

## 4.3 2D 分类准确率

脚本还会统计“已经匹配上的检测对里，类别判对了多少”：

- `classification_summary_2d`
- `focused_classification_summary_2d`

核心口径是 confusion matrix 的主对角占比：

- `overall_accuracy = trace(matched_matrix) / sum(matched_matrix)`

每类还会有：

- `cls_eval_pairs_2d`
- `cls_correct_2d`
- `cls_acc_2d`

## 4.4 focused confusion 子集

脚本还会单独做一个“近距离、无遮挡、低难度”的 focused confusion：

- GT 条件：
  - `difficulty == 0`
  - `|lateral| < 5m`
  - `|longitudinal| < 30m` 对 `roi0`
  - `|longitudinal| < 80m` 对 `roi1`
- Pred 条件：
  - 用预测 3D 中心估计空间位置
  - 满足相同的空间范围约束

这一部分主要用于看容易样本的分类混淆情况。

## 5. 3D object-level record 设计

每个 GT-Pred 匹配对，脚本都会尝试构造一个 record。record 是后续所有 3D 聚合统计的基础。

### 5.1 基本字段

包含但不限于：

- 样本标识：`sample_index`, `roi`, `frame_name`
- GT/Pred 索引：`gt_index`, `pred_index`
- 类别：`cls_id`, `cls_name`
- 2D 匹配：`confidence`, `match_iou`
- 3D 属性：
  - `gt_x_m / pred_x_m`
  - `gt_y_m / pred_y_m`
  - `gt_z_m / pred_z_m`
  - `gt_depth_m / pred_depth_m`
  - `gt_yaw_deg / pred_yaw_deg`
  - `x_abs_m / y_abs_m / z_abs_m`
  - `center_error_m`
  - `yaw_abs_deg`

### 5.2 yaw 误差定义

当前脚本的 yaw 误差不是普通 `|pred - gt|`，而是 **pi 周期误差**：

- 先做 `[-pi, pi)` wrap
- 再取 `min(diff, |pi - diff|)`

含义是：

- 180 度前后翻转不被当成大错
- 更接近“朝向轴”误差，而不是“严格方向”误差

对应函数：

- `angle_abs_deg(...)`

这点非常重要，读报告时必须按这个口径理解所有 yaw 指标。

### 5.3 position_eligible

不是所有 matched_3d 都会进入位置误差统计。当前实现里：

- `position_eligible = (cls in complete_3d_classes) or (not cut_object)`

也就是说：

- 完整 3D 类，总是参与位置误差
- face-3D 类如果是 cut object，则不参与位置误差

因此：

- `matched_3d` 是形状/yaw层面的 3D 成功样本数
- `matched_pos` 才是位置误差真正参与统计的样本数

### 5.4 position_error_basis

位置误差并不总是用 box center 计算。

当前实现优先级是：

1. 对 face_3d 类，如果 GT 和 Pred 都能解析到同一个可见 face，则使用该 `face_center`
2. 否则退回 `box_center`

因此 record 中会有：

- `position_error_basis = face_center` 或 `box_center`

这会影响：

- `x_abs_m`
- `y_abs_m`
- `z_abs_m`
- `center_error_m`

### 5.5 yaw compare 相关字段

脚本会同时保存三类 yaw：

1. `pred_yaw`
   - 来自 41 维 whole 头的直接 yaw 回归
2. `pred_edge_visible_yaw`
   - 来自 edge 几何重建
   - 只有 `edge_confident=True` 时才记为有效
3. `pred_edge_bucket_visible_yaw`
   - 记录当前 edge 选择器给出的 yaw
   - 即使它不满足“正式 edge 有效条件”，也会保留，用于 bucket 诊断

同时会记录：

- `direct_visible_yaw_abs_deg`
- `edge_visible_yaw_abs_deg`
- `direct_minus_edge_visible_yaw_abs_deg`

### 5.6 yaw_compare_eligible

只有满足下列条件，样本才被认为“允许进入 yaw compare 范围”：

- `|gt_x_m| < yaw_compare_max_lateral_dist_m`

默认 lateral limit 很大，来自：

- `DEFAULT_YAW_COMPARE_MAX_LATERAL_DIST_M = 30m`

但真正进入 `yaw_compare_count` 的条件更严格，还需要：

- direct yaw 有效
- edge yaw 有效

也就是：

- `yaw_compare_eligible` 只是“允许参与”
- `yaw_compare_count` 才是“真的成对比较了 direct vs edge”

## 6. bucket 聚合指标

所有 overall/class/breakdown/lateral-bin 等汇总，最终都通过 `summarize_metric_bucket(...)` 生成。

## 6.1 计数项

- `gt_total`
- `pred_total`
- `matched_2d`
- `matched_3d`
- `matched_pos`
- `yaw_compare_eligible_count`
- `yaw_compare_count`
- `length_compare_count`

## 6.2 2D 派生项

- `precision_2d = matched_2d / pred_total`
- `recall_2d = matched_2d / gt_total`
- `f1_2d`

## 6.3 3D 主指标

- `mean_confidence`
- `mean_match_iou`
- `yaw_mae_deg`
- `yaw_p90_deg`
- `x_abs_mae_m`
- `y_abs_mae_m`
- `z_abs_mae_m`
- `center_error_mae_m`

## 6.4 direct vs edge 对比指标

- `direct_regression_yaw_mae_deg`
- `direct_regression_yaw_p90_deg`
- `edge_based_yaw_mae_deg`
- `edge_based_yaw_p90_deg`
- `mean_direct_minus_edge_yaw_deg`
- `median_direct_minus_edge_yaw_deg`
- `yaw_compare_edge_better_count/rate`
- `yaw_compare_direct_better_count/rate`
- `yaw_compare_tie_count/rate`

脚本的判优规则是：

- `edge_err + eps < direct_err` 记为 edge better
- `direct_err + eps < edge_err` 记为 direct better
- 否则 tie

## 6.5 长度对比指标

当前还统计了 direct box 与 edge box 的车长误差对比：

- `direct_regression_length_mae_m`
- `side_edge_length_mae_m`
- `mean_direct_minus_side_edge_length_m`
- `length_compare_edge_better_count/rate`
- `length_compare_direct_better_count/rate`
- `length_compare_tie_count/rate`

## 6.6 超阈值坏例占比

- `yaw_bad_rate = yaw_bad_count / matched_3d`
- `horizontal_bad_rate = x_bad_count / matched_pos`
- `vertical_bad_rate = z_bad_count / matched_pos`

默认阈值：

- yaw：`5 deg`
- horizontal：`0.5 m`
- vertical：`0.5 m`

## 6.7 当前实现的命名注意事项

这里有一个很容易误解的点：

- `vertical_*` 相关统计，当前实现实际上是基于 `z_abs_m` 做的，也就是纵向/深度误差
- 不是基于 `y_abs_m`

具体来说：

- `bad_cases_vertical.csv` 的导出条件是 `z_abs_m > vertical_bad_threshold_m`
- `vertical_abs_mae_m` 实际对应 `mean(z_abs_m)`
- `class_vertical_depth_5m.csv` 也是按 `position_gt_z_m` 分桶

另外：

- `y_abs_m` 会被记录
- 但 `y_bad_count` 当前实现没有真正累加，因此 `y_bad_rate` 基本恒为 `0` 或无实际含义

所以看报告时，建议把：

- `horizontal` 理解为 `x`
- `vertical` 理解为 `z/depth`

## 7. breakdown 与分桶统计

## 7.1 breakdowns.json

脚本会输出 `breakdowns.json`，当前有 5 类 breakdown：

1. `cut_status`
   - `cut`
   - `non_cut`
   - `n/a`
2. `face_visibility`
   - `front_rear_only`
   - `side only`
   - `two-face`
3. `distance_bin`
   - `<20m`
   - `20-40m`
   - `40-60m`
   - `>=60m`
4. `bbox_diag_bin`
   - `<32px`
   - `32-64px`
   - `64-128px`
   - `>=128px`
5. `class_group`
   - `face_3d`
   - `complete_3d`
   - `2d_only`

## 7.2 interval CSV

脚本还会输出几类按区间统计的 CSV：

### `class_horizontal_lateral_5m.csv`

- 横轴：GT 的 `position_gt_x_m`
- 分桶：`[-30m, 30m)` 内 5m 一桶
- 指标：`x_abs_m`
- 额外输出：
  - mean
  - median
  - p90
  - max
  - `rate_gt_0p5`

### `class_vertical_depth_5m.csv`

- 横轴：GT 的 `position_gt_z_m`
- 分桶：5m 一桶
- 指标：`z_abs_m`

### `class_yaw_depth_10m.csv`

- 横轴：GT 的 `gt_depth_m`
- 分桶：10m 一桶
- 指标：`yaw_abs_deg`

### `class_yaw_horizontal_5m.csv`

- 横轴：GT 的 `gt_x_m`
- 分桶：`[-30m, 30m)` 内 5m 一桶
- 指标：`yaw_abs_deg`

### `yaw_compare_signed_lateral_5m.csv`

这是专门给 direct vs edge yaw 对比用的：

- 横轴：GT 的 `gt_x_m`
- 范围：`[-yaw_compare_max_lateral_dist_m, yaw_compare_max_lateral_dist_m)`
- 分桶：5m
- 额外还有一个纵向过滤条件：
  - `0 <= gt_z_m < 50m`

桶内不是简单均值列表，而是整套 `summarize_metric_bucket(...)` 输出。

### `yaw_compare_signed_lateral_5m_by_face_visibility.csv`

与上面类似，但再按 `face_visibility_bucket` 细分：

- `front_rear_only`
- `side only`
- `two-face`

## 7.3 large vehicle 专项统计

脚本对大车类单独做了一个 two-face yaw 对比视角：

- 类别集合：`5, 6, 7`
- 即：
  - bus
  - truck/tanker/large_truck/construction_vehicle
  - special_vehicle

输出在：

- `summary.json` 的 `large_vehicle_compare`

## 8. 坏例导出规则

## 8.1 CSV 全量导出

脚本会把所有超阈值样本写入 CSV：

- `bad_cases_yaw.csv`
  - 条件：`yaw_abs_deg >= yaw_bad_threshold_deg`
- `bad_cases_horizontal.csv`
  - 条件：`position_eligible and x_abs_m > horizontal_bad_threshold_m`
- `bad_cases_vertical.csv`
  - 条件：`position_eligible and z_abs_m > vertical_bad_threshold_m`
- `bad_cases_2d_false_negative.csv`
- `bad_cases_2d_false_positive.csv`

## 8.2 可视化导出

可视化不是把所有坏例都画出来，而是做 reservoir sampling：

- overall top-k
- per-class top-k
- per-error-bin top-k

其中按误差区间导出时：

- yaw：`1 deg` 一桶
- horizontal/vertical：`0.5 m` 一桶
- 每桶先保留最多 `error_bin_badcases`
- 再按 frame 聚合，最终每桶最多导出 `error_bin_samples_per_bin` 张图

## 9. 输出文件组织

## 9.1 每个 ROI 目录

每个 ROI 目录下会有：

- `summary.json`
- `summary.md`
- `summary_zh.md`
- `class_metrics.csv`
- `breakdowns.json`
- `class_horizontal_lateral_5m.csv`
- `class_vertical_depth_5m.csv`
- `class_yaw_depth_10m.csv`
- `class_yaw_horizontal_5m.csv`
- `yaw_compare_signed_lateral_5m.csv`
- `yaw_compare_signed_lateral_5m_by_face_visibility.csv`
- `bad_cases_yaw.csv`
- `bad_cases_horizontal.csv`
- `bad_cases_vertical.csv`
- `bad_cases_2d_false_negative.csv`
- `bad_cases_2d_false_positive.csv`
- `confusion_matrix_normalized.png`
- `2d_confidence_curves/*.png`
- `visuals/...`

## 9.2 总输出目录

总输出目录会汇总所有 ROI，写出：

- `summary.json`
- `summary.md`
- `summary_zh.md`
- `report.html`

如果启用了 data portrait，还会额外有：

- `<split>_portrait/summary.json`
- portrait 相关 CSV

## 10. 一句话总结

`analyze_val_two_roi_badcases.py` 当前实现的核心是：

- 用 `IoU>=0.5 + 类别一致` 的贪心匹配构造 object-level 记录
- 以 record 为中心，统一聚合 2D、3D、direct-vs-edge、分桶和坏例统计
- 2D AP 与 thresholded 2D 指标分开算
- yaw 误差采用 pi 周期口径
- 报告里名为 `vertical` 的主统计，当前实际上对应 `z/depth` 误差

如果后续要和训练期 validator 对齐，最值得先确认的就是：

- yaw 误差口径是否仍然保持 pi 周期
- `vertical` 是否继续表示 `z`
- `position_eligible` 是否继续排除 cut 的 face-3D 样本