zhao.zhu/yolov26_3d
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
yolov26_3d/eval_tools/docs/EXTRACT_BAD_HEADING_USAGE.md
zhao.zhu 04a5895b6b 单目3D初始代码
2026-06-24 09:35:46 +08:00

14 KiB
Executable File
Raw Permalink Blame History

Bad Heading Cases Extraction Tool 使用说明

工具概述

extract_bad_heading_cases.py 用于从评估结果中提取 heading 误差较大的案例，为后续可视化分析提供数据支持。

功能特性

  • ✅ 多条件筛选：支持误差阈值、类别、距离、置信度等多维度过滤
  • ✅ 反转错误检测：自动识别 ≈180° 的方向反转错误
  • ✅ 统计分析：输出详细的分类统计、误差分布、距离分布等
  • ✅ Top-K 选择：支持仅提取误差最大的 K 个案例
  • ✅ 结构化输出：生成包含元数据和统计信息的 JSON 文件

快速开始

基本用法

# 提取所有误差 > 1.5 rad 的案例
python eval_tools/extract_bad_heading_cases.py \
    --input eval_results_common_match_comparison/yolov5s-300w/20260203_210259/detailed_3d_matches.json \
    --threshold 1.5 \
    --output bad_heading_cases.json \
    --stats

运行测试脚本

# 给脚本添加执行权限
chmod +x eval_tools/test_extract_bad_cases.sh

# 运行多个测试用例
./eval_tools/test_extract_bad_cases.sh

命令行参数

必需参数

  • --input: 输入的 detailed_3d_matches.json 文件路径

可选参数

筛选参数

  • --threshold: Heading 误差阈值（弧度），默认 1.5 (≈ 85°)
  • --top-k: 仅提取误差最大的 K 个案例
  • --classes: 指定类别（可选多个），支持：
    • vehicle: 车辆
    • pedestrian: 行人
    • bicycle: 自行车
    • rider: 骑行者
  • --min-distance: 最小距离（米）
  • --max-distance: 最大距离（米）
  • --min-confidence: 最小置信度 (0-1)
  • --reversal-only: 仅提取反转错误（误差 > π - 0.1 ≈ 174°）

输出参数

  • --output: 输出 JSON 文件路径，默认：bad_heading_cases.json
  • --stats: 打印详细统计信息

使用示例

示例 1：提取所有 bad cases

python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 1.5 \
    --output all_bad_cases.json \
    --stats

输出统计示例：

Processing: 596602 matches...
Filtered: 5839 cases

=== Statistics ===
vehicle: 4012 cases (68.7% reversal)
pedestrian: 1523 cases (42.3% reversal)
bicycle: 304 cases (55.6% reversal)

Error distribution:
  Mean: 2.45 rad (140.4°)
  Median: 2.89 rad (165.6°)
  Std: 0.78 rad
  Range: [1.50, 3.14] rad

示例 2：提取 Top 50 最差案例

python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 1.5 \
    --top-k 50 \
    --output top50_worst.json \
    --stats

适用场景：

  • 聚焦最严重的问题案例
  • 快速定位典型错误模式
  • 限制可视化数量以提高效率

示例 3：仅提取反转错误

python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --reversal-only \
    --top-k 100 \
    --output reversal_errors.json \
    --stats

适用场景：

  • 专门分析 180° 方向反转问题
  • yolov5s-300w 模型的主要问题（68.7% bad cases 是反转错误）

示例 4：分析特定类别

# 仅分析车辆类别
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 1.5 \
    --classes vehicle \
    --min-confidence 0.5 \
    --top-k 50 \
    --output vehicle_bad_cases.json \
    --stats

# 分析多个类别
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --classes vehicle pedestrian \
    --output vehicle_pedestrian_cases.json \
    --stats

示例 5：距离筛选

# 提取中距离范围的 bad cases (30-80m)
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 1.5 \
    --min-distance 30 \
    --max-distance 80 \
    --output mid_distance_cases.json \
    --stats

# 提取近距离 bad cases (< 30m)
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 1.5 \
    --max-distance 30 \
    --output near_distance_cases.json \
    --stats

示例 6：高置信度案例

# 提取高置信度但方向错误的案例（模型问题而非检测问题）
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 1.5 \
    --min-confidence 0.7 \
    --top-k 50 \
    --output high_confidence_bad.json \
    --stats

输出格式

JSON 结构

{
  "metadata": {
    "source": "detailed_3d_matches.json",
    "threshold": 1.5,
    "total_processed": 596602,
    "total_extracted": 5839,
    "filters": {
      "classes": ["vehicle", "pedestrian"],
      "min_distance": 30,
      "max_distance": 80,
      "min_confidence": 0.5,
      "reversal_only": false,
      "top_k": 100
    },
    "extraction_time": "2026-02-04T10:30:15"
  },
  
  "statistics": {
    "vehicle": {
      "count": 4012,
      "reversal_count": 3266,
      "reversal_percentage": 81.4,
      "avg_error": 2.85,
      "avg_error_deg": 163.3,
      "error_distribution": {
        "min": 1.50,
        "max": 3.14,
        "mean": 2.85,
        "median": 3.02,
        "std": 0.45
      },
      "distance_distribution": {
        "min": 5.2,
        "max": 98.7,
        "mean": 45.3,
        "median": 42.1
      },
      "confidence_distribution": {
        "min": 0.25,
        "max": 0.98,
        "mean": 0.67
      }
    },
    "pedestrian": {
      "count": 1523,
      "reversal_count": 644,
      "reversal_percentage": 42.3,
      "avg_error": 2.34,
      "avg_error_deg": 134.1,
      ...
    }
  },
  
  "cases": [
    {
      "case_id": "019b18ef-ca2b-7e97-8ca5-d4b1d7eefdbb_roi0",
      "frame_id": "019b18f3-8d8e-70bb-8b4e-cef51fbb7089.jpg",
      "class": "vehicle",
      
      "heading_error": 3.1389,
      "heading_error_deg": 179.87,
      "gt_rotation": -0.0145,
      "det_rotation": 3.1244,
      "is_reversal": true,
      
      "distance": 45.23,
      "confidence": 0.8567,
      "iou": 0.7234,
      
      "gt_center": [42.5, -3.2, 1.5],
      "det_center": [42.8, -3.4, 1.6],
      
      "gt_dimensions": [4.5, 1.8, 1.6],
      "det_dimensions": [4.3, 1.7, 1.5],
      
      "gt_bbox_2d": [120, 340, 245, 480],
      "det_bbox_2d": [118, 338, 243, 478],
      
      "lateral_error": 0.22,
      "longitudinal_error": 0.31
    },
    ...
  ]
}

字段说明

metadata 元数据

  • source: 输入文件路径
  • threshold: 使用的误差阈值
  • total_processed: 处理的总匹配数
  • total_extracted: 提取的案例数
  • filters: 应用的筛选条件
  • extraction_time: 提取时间

statistics 统计信息

  • count: 该类别的案例数量
  • reversal_count: 反转错误数量
  • reversal_percentage: 反转错误比例
  • avg_error: 平均误差（弧度/度）
  • error_distribution: 误差分布统计
  • distance_distribution: 距离分布统计
  • confidence_distribution: 置信度分布统计

cases 案例详情

  • case_id, frame_id: 案例和帧 ID
  • class: 目标类别
  • heading_error: Heading 误差（弧度）
  • heading_error_deg: Heading 误差（度）
  • gt_rotation, det_rotation: 真值和检测的旋转角度
  • is_reversal: 是否为反转错误
  • distance: 目标距离（米）
  • confidence: 检测置信度
  • iou: 2D IoU
  • gt_center, det_center: 3D 中心坐标
  • gt_dimensions, det_dimensions: 3D 尺寸
  • gt_bbox_2d, det_bbox_2d: 2D 边界框
  • lateral_error, longitudinal_error: 横向和纵向误差

数据分析工作流

1. 初步探索

# 查看所有 bad cases 的统计信息
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 1.5 \
    --output all_cases.json \
    --stats

2. 聚焦问题

# 基于统计结果，聚焦特定问题（如反转错误）
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --reversal-only \
    --classes vehicle \
    --top-k 100 \
    --output vehicle_reversal.json \
    --stats

3. 可视化分析

# 使用提取的案例进行可视化（Tool 2）
python eval_tools/visualize_heading_errors.py \
    --input vehicle_reversal.json \
    --gt-dir path/to/labels \
    --img-dir path/to/images \
    --calib-dir path/to/calib \
    --output runs/heading_viz

4. 生成报告

# 生成分析报告（Tool 4）
python eval_tools/generate_heading_report.py \
    --input vehicle_reversal.json \
    --viz-dir runs/heading_viz \
    --output heading_analysis_report.html

典型分析场景

场景 1：定位反转错误根因

目标：理解为什么 yolov5s-300w 有 68.7% 的反转错误

# Step 1: 提取反转错误
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --reversal-only \
    --top-k 200 \
    --output reversal_errors.json \
    --stats

# Step 2: 按类别分析
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --reversal-only \
    --classes vehicle \
    --output vehicle_reversal.json \
    --stats

# Step 3: 按距离分析
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --reversal-only \
    --min-distance 30 \
    --max-distance 60 \
    --output mid_dist_reversal.json \
    --stats

场景 2：分析高置信度错误

目标：找出模型"很确信但预测错误"的案例

python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 2.0 \
    --min-confidence 0.8 \
    --top-k 50 \
    --output high_conf_bad.json \
    --stats

场景 3：类别间差异分析

目标：对比不同类别的 heading 预测问题

# 车辆
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --classes vehicle \
    --top-k 100 \
    --output vehicle_analysis.json \
    --stats

# 行人
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --classes pedestrian \
    --top-k 100 \
    --output pedestrian_analysis.json \
    --stats

场景 4：距离敏感性分析

目标：分析 heading 误差与距离的关系

# 近距离 (< 30m)
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --max-distance 30 \
    --output near_cases.json \
    --stats

# 中距离 (30-60m)
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --min-distance 30 \
    --max-distance 60 \
    --output mid_cases.json \
    --stats

# 远距离 (> 60m)
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --min-distance 60 \
    --output far_cases.json \
    --stats

常见问题

Q1: 如何选择合适的阈值？

A: 根据评估指标选择：

  • 1.0 rad (57°): 严格标准，仅提取严重错误
  • 1.5 rad (86°): 推荐标准，平衡数量和质量
  • 2.0 rad (115°): 宽松标准，包含更多一般错误

Q2: 提取的案例太多怎么办？

A: 使用 --top-k 限制数量，或添加更多筛选条件：

python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 1.5 \
    --top-k 100 \
    --min-confidence 0.5 \
    --min-distance 20 \
    --max-distance 80

Q3: 如何只看反转错误？

A: 使用 --reversal-only 参数：

python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --reversal-only \
    --top-k 100

Q4: 如何验证提取的案例是否正确？

A: 使用 --stats 查看统计信息，并检查输出 JSON 的前几个案例：

python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --top-k 5 \
    --stats

# 然后查看输出文件
python -m json.tool bad_heading_cases.json | head -n 100

性能优化

大数据集处理

对于非常大的数据集（如 596K+ 匹配），可以：

  1. 先筛选再提取：
# 先用严格条件提取少量案例
python eval_tools/extract_bad_heading_cases.py \
    --input detailed_3d_matches.json \
    --threshold 2.5 \
    --top-k 50
  1. 分批处理：
# 按类别分批
for class in vehicle pedestrian bicycle rider; do
    python eval_tools/extract_bad_heading_cases.py \
        --input detailed_3d_matches.json \
        --classes $class \
        --top-k 100 \
        --output ${class}_bad_cases.json
done

下一步

提取完案例后，可以使用：

  1. 可视化工具 (Tool 2): visualize_heading_errors.py

    • 生成 BEV、图像投影、角度分析图

  2. 交互式查看器 (Tool 3): heading_error_viewer.py

    • Web 界面浏览案例

  3. 报告生成器 (Tool 4): generate_heading_report.py

    • 生成 HTML/Markdown 分析报告

相关文档

技术支持

如果遇到问题，请检查：

  1. 输入文件路径是否正确
  2. JSON 格式是否符合预期（包含 case_id → frames → classes → matches 结构）
  3. 筛选条件是否过于严格（导致无结果）
  4. Python 环境是否安装必要的库（numpy）
# 检查输入文件结构
python -c "import json; data = json.load(open('detailed_3d_matches.json')); print(f'Cases: {len(data)}, First case: {list(data.keys())[0]}')"
Reference in New Issue View Git Blame Copy Permalink