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

8.9 KiB
Executable File
Raw Blame History

真值可视化工具集

📚 文档索引

本目录提供了完整的真值可视化工具和详细文档，帮助理解从数据加载到可视化的完整流程。

核心脚本

  1. visualize_single_frame.py - 单帧可视化脚本 ⭐

    • 读取单帧图像和标签
    • 支持2D、3D、BEV可视化
    • 支持ROI变换和深度归一化
    • 推荐用于详细分析单个样本

  2. visualize_batch.py - 批量可视化脚本

    • 批量处理多帧图像
    • 自动匹配图像和标签
    • 支持限制处理数量
    • 推荐用于快速浏览数据集

  3. visualize_filtered_train.py - 条件过滤可视化脚本 🔥

    • 从训练集/验证集筛选特定条件的样本
    • 支持类别过滤（如：只看两轮车）
    • 支持3D空间范围过滤（如：左右10米、纵向50米）
    • 自动生成摘要文件
    • 推荐用于数据分析和质量检查

  4. test_visualization.py - 快速测试脚本

    • 自动从验证集查找样本
    • 测试不同配置的可视化效果
    • 推荐用于首次使用或调试

文档说明

  1. README.md - 总体说明 📖

    • 真值读取到可视化的完整流程概述
    • 标签格式说明（47维数组结构）
    • ROI变换和深度归一化原理
    • 不同类别的处理策略
    • 使用方法和参数说明

  2. FLOW_ANALYSIS.md - 详细流程分析 🔍

    • 数据加载流程（标签、图像、标定）
    • ROI变换的详细步骤
    • 深度归一化的数学原理
    • 2D/3D可视化的实现细节
    • 坐标系统和变换关系
    • 调试技巧和优化建议

  3. EXAMPLES.md - 使用示例 💡

    • 基础使用示例（原始图像）
    • ROI模式示例（与训练一致）
    • 批量处理示例
    • 自动测试示例
    • 常见场景和故障排查
    • 参数速查表

  4. FILTER_GUIDE.md - 条件过滤指南 🎯

    • 条件过滤可视化的详细使用方法
    • 类别过滤和空间范围过滤
    • 多种使用场景（数据质量检查、类别分布分析等）
    • 参数详解和坐标系说明
    • 高级用法和性能优化
    • 常见问题和实用技巧

🚀 快速开始

方式1: 最简单（自动测试）

# 自动查找样本并可视化
python scripts_for_gt/test_visualization.py --data data/mono3d.yaml --output ./test_viz

方式2: 单帧可视化（原始图像）

# 基础使用：不使用ROI，直接可视化原始图像
python scripts_for_gt/visualize_single_frame.py \
    --image /path/to/image.jpg \
    --label /path/to/label.txt \
    --output ./viz_output

方式3: 单帧可视化（ROI模式，与训练一致）

# 使用ROI变换和深度归一化（与训练时一致）
python scripts_for_gt/visualize_single_frame.py \
    --image /path/to/image.jpg \
    --label /path/to/label.txt \
    --output ./viz_output_roi \
    --roi 704 352 \
    --virtual-fx 500 \
    --ori-img-size 1920 1080

方式4: 批量处理

# 批量可视化多帧
python scripts_for_gt/visualize_batch.py \
    --image-dir /path/to/images \
    --label-dir /path/to/labels \
    --output ./batch_viz \
    --roi 704 352 \
    --virtual-fx 500 \
    --max-samples 20

📊 输出结果

每个样本会生成4个可视化文件：

文件 内容 用途
*_2d_gt.jpg 2D边界框 查看目标检测标注
*_3d_gt.jpg 3D框投影 查看3D标注质量
*_bev_gt.jpg 鸟瞰图 查看空间位置关系
*_combined.jpg 组合视图 一眼看到所有信息

🔑 关键概念

标签格式（47维数组）

[0]:     class                    # 类别ID
[1-4]:   x, y, w, h              # 2D边界框（归一化）
[5]:     score                   # 置信度
[6-8]:   x3d, y3d, z3d          # 3D中心（相机坐标系）
[9-11]:  length, height, width   # 3D尺寸
[12]:    rot_y                   # 偏航角
[13-14]: center_u, center_v      # 3D中心投影（归一化）
[15]:    alpha                   # 观测角
[16-23]: front_face              # 前面信息
[24-31]: rear_face               # 后面信息
[32-39]: left_face               # 左面信息
[40-47]: right_face              # 右面信息

ROI变换

  1. 计算ROI区域（以消失点为中心）
  2. 裁剪图像到ROI区域
  3. 调整2D边界框和UV坐标到ROI空间
  4. 根据virtual_fx缩放深度值

深度归一化

# 训练时
z_normalized = z_original * (virtual_fx / fx_original)

# 可视化时（恢复）
z_original = z_normalized * depth_scale
# 其中 depth_scale = fx_original / virtual_fx

为什么只缩放Z？

  • 投影公式: u = fx * X/Z + cx
  • 同时缩放fx和Z可以保持投影不变
  • X和Y从UV和Z恢复，无需单独缩放

不同类别的处理策略

类别 策略 原因
车辆(0, 13) 基于最佳可见面 可能被部分遮挡
行人(1, 2, 3) 基于完整3D框 尺寸小，完整框更准确

🔧 常见问题

Q1: 为什么需要ROI变换？

A: ROI变换有两个目的：

  1. 聚焦感兴趣区域: 去除天空等无关区域
  2. 统一焦距: 通过virtual_fx统一不同相机的焦距，提高泛化能力

Q2: 什么时候使用ROI模式？

A:

  • 查看原始数据: 不使用ROI（了解数据本身）
  • 与训练一致: 使用ROI（验证训练数据处理）
  • 调试模型: 使用ROI（与模型输入一致）

Q3: 标定文件必需吗？

A:

  • 2D可视化: 不需要
  • 3D可视化: 需要（用于3D到2D的投影）

Q4: 如何验证可视化是否正确？

A: 检查以下几点：

  1. 2D框是否对齐目标
  2. 3D框投影是否合理（不应该明显错位）
  3. BEV中的位置是否符合直觉（距离、朝向）
  4. 不同面的颜色是否正确（前红后绿）

📖 推荐阅读顺序

  1. 新手: README.md → EXAMPLES.md → 运行test_visualization.py
  2. 数据分析: FILTER_GUIDE.md → 运行visualize_filtered_train.py
  3. 开发: FLOW_ANALYSIS.md → 阅读脚本代码 → 自定义功能
  4. 调试: EXAMPLES.md故障排查 → FLOW_ANALYSIS.md调试技巧

🎯 常用命令速查

# 快速测试
python scripts_for_gt/test_visualization.py

# 原始图像可视化
python scripts_for_gt/visualize_single_frame.py --image img.jpg --label label.txt --output out

# ROI模式（与训练一致）
python scripts_for_gt/visualize_single_frame.py --image img.jpg --label label.txt \
    --roi 704 352 --virtual-fx 500 --output out

# 批量处理（前10个样本）
python scripts_for_gt/visualize_batch.py --image-dir imgs/ --label-dir labels/ \
    --output batch_out --max-samples 10

# 批量+ROI
python scripts_for_gt/visualize_batch.py --image-dir imgs/ --label-dir labels/ \
    --roi 704 352 --virtual-fx 500 --output batch_out

# 条件过滤：可视化包含两轮车的样本（左右10米、纵向50米范围）
python scripts_for_gt/visualize_filtered_train.py --data data/mono3d.yaml \
    --target-class bicycle --x-range -10 10 --z-range 0 50 --max-samples 20

# 条件过滤：可视化包含行人的样本
python scripts_for_gt/visualize_filtered_train.py --data data/mono3d.yaml \
    --target-class pedestrian --max-samples 50

# 条件过滤：从验证集筛选
python scripts_for_gt/visualize_filtered_train.py --data data/mono3d.yaml \
    --split val --target-class vehicle --z-range 10 30 --max-samples 20

📞 需要帮助？

  1. 查看 EXAMPLES.md 的故障排查章节
  2. 查看 FLOW_ANALYSIS.md 的调试技巧章节
  3. 检查标签文件格式是否正确
  4. 检查标定文件是否存在且格式正确

🔄 与模型代码的对应关系

功能 脚本位置 模型代码位置
标签加载 load_label_file() utils/dataloaders3d.py:load_label()
ROI变换 apply_roi_transform() utils/dataloaders3d.py:post_process_labels_to_roi()
深度归一化 scale_z3d() utils/dataloaders3d.py:_scale_z3d()
3D解码（GT） - utils/plots.py:decode_and_reconstruct_3d_box_from_target()
3D解码（预测） - utils/plots.py:decode_and_reconstruct_3d_box()
2D可视化 plot_2d_boxes() test_val_visualize.py:plot_2d_boxes_to_image()
3D可视化 - utils/plots.py:plot_3d_boxes_from_decoded_targets()

📝 版本历史

  • v1.0 (2026-02-07): 初始版本
    • 单帧可视化脚本
    • 批量可视化脚本
    • 自动测试脚本
    • 完整文档（README, FLOW_ANALYSIS, EXAMPLES）

🎓 相关资源

Reference in New Issue View Git Blame Copy Permalink