单目3D初始代码

eval_tools/analysis/README_2D_FP_FN.md

@@ -0,0 +1,129 @@
+# 2D FP/FN 分析工具
+
+本目录用于分析单模型 2D 检测中的误检（FP）和漏检（FN），帮助把总指标拆成更可操作的问题类型。
+
+## 文件
+
+- `analyze_2d_fp_fn.py`
+  读取检测结果和 GT，复用现有 `Evaluator` / `parser` / `matcher`，输出 2D FP/FN 分类分析报告。
+- `export_2d_fp_fn_badcases.py`
+  从 `analysis_report.json` 中筛选指定类别、错误类型、距离或置信度范围，导出 badcase 清单。
+
+## FP 分类
+
+- `duplicate`
+  同类 GT 其实已经被更高分框匹配走了，当前框属于重复检出。
+- `class_confusion`
+  框和其他类别 GT 有较高 IoU，说明更像分类混淆。
+- `localization`
+  和同类 GT 靠得比较近，但 IoU 没过主阈值，更像框偏了。
+- `background`
+  附近没有足够重叠的 GT，更像背景误检或漏标。
+
+## FN 分类
+
+- `class_confusion`
+  其他类别的激活框和该 GT 重叠较高。
+- `low_score`
+  同类框位置够准，但分数低于工作点阈值。
+- `localization`
+  同类高分框在附近，但 IoU 没过主阈值。
+- `low_score_localization`
+  同类低分框在附近，但又低分又偏框。
+- `missing`
+  附近没有合理同类框。
+
+## 运行分析
+
+推荐直接复用现有评测配置：
+
+```bash
+source /deeplearning_team/ydong/dongying/miniconda/etc/profile.d/conda.sh
+conda activate yolov5
+
+python eval_tools/analysis/analyze_2d_fp_fn.py \
+  --config eval_tools/configs/eval_config_mono3d-roi0.yaml \
+  --classes vehicle pedestrian bicycle rider \
+  --near-iou-threshold 0.1 \
+  --output-dir eval_tools/analysis/results/mono3d_fp_fn
+```
+
+也可以直接传路径：
+
+```bash
+python eval_tools/analysis/analyze_2d_fp_fn.py \
+  --det-path /path/to/dets \
+  --gt-path /path/to/gts \
+  --det-format json \
+  --gt-format json \
+  --img-width 1920 \
+  --img-height 1080 \
+  --iou-threshold 0.5 \
+  --conf-threshold 0.4
+```
+
+## 输出
+
+运行后会生成：
+
+- `analysis_report.json`
+  完整结构化结果，包含 summary、top frames、FP/FN example 明细。
+- `analysis_report.txt`
+  适合快速查看的文本摘要。
+
+JSON 中最常用的字段：
+
+- `summary.fp_by_type`
+- `summary.fn_by_type`
+- `summary.per_class`
+- `top_frames`
+- `false_positive_examples`
+- `false_negative_examples`
+
+## 导出 badcase 清单
+
+例如导出 `vehicle` 的高置信背景误检：
+
+```bash
+python eval_tools/analysis/export_2d_fp_fn_badcases.py \
+  --input eval_tools/analysis/results/mono3d_fp_fn/analysis_report.json \
+  --mode fp \
+  --classes vehicle \
+  --error-types background \
+  --min-confidence 0.5 \
+  --top-k 200 \
+  --dedup-frame
+```
+
+例如导出 `pedestrian` 的低分漏检：
+
+```bash
+python eval_tools/analysis/export_2d_fp_fn_badcases.py \
+  --input eval_tools/analysis/results/mono3d_fp_fn/analysis_report.json \
+  --mode fn \
+  --classes pedestrian \
+  --error-types low_score low_score_localization \
+  --top-k 200
+```
+
+导出结果包括：
+
+- `*_badcases.json`
+  过滤后的明细
+- `*_badcases.txt`
+  文本摘要
+- `*_badcases_case_frame_list.txt`
+  每行一个 `case<TAB>frame`，方便接可视化或人工排查
+
+## 推荐排查流程
+
+1. 先看 `summary.fp_by_type` / `summary.fn_by_type`，确认主要矛盾是误检、漏检、分类混淆还是定位偏差。
+2. 再看 `summary.per_class`，确认问题集中在哪些类别。
+3. 用 `export_2d_fp_fn_badcases.py` 筛出某个错误桶的 top case。
+4. 把导出的 `case/frame` 清单接到你们现有可视化脚本里做人工复核。
+
+## 注意
+
+- 当前分析严格复用了评测时的 ROI GT 过滤和 `Matcher2D` 规则，因此口径会尽量和正式评测保持一致。
+- `background` 不能完全等价于“真的背景误检”，也可能包含漏标样本，最好配合人工复查。
+- `duplicate` 往往与 NMS、同物体多框、训练标签分布有关。