yolov26_3d/eval_tools/analysis/README_2D_FP_FN.md

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 附近没有合理同类框。

运行分析

推荐直接复用现有评测配置：

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

也可以直接传路径：

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 的高置信背景误检：

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 的低分漏检：

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、同物体多框、训练标签分布有关。