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