yolov26_3d/tools/scripts_for_gt/visualization/EXAMPLES.md

使用示例

本文档提供详细的使用示例，帮助快速上手真值可视化脚本。

示例1: 基础使用（原始图像可视化）

最简单的使用方式，不应用任何变换，直接可视化原始图像和标签。

数据准备

假设你的数据结构如下：

/data/
├── images/
│   └── frame_001.jpg       # 原始图像 (1920x1080)
├── labels/
│   └── frame_001.txt       # 标签文件
└── calib/
    └── L2_calib/
        └── camera4.json    # 相机标定

运行命令

python scripts_for_gt/visualize_single_frame.py \
    --image /data/images/frame_001.jpg \
    --label /data/labels/frame_001.txt \
    --output ./viz_output

输出结果

viz_output/
├── frame_001_2d_gt.jpg         # 2D边界框可视化
├── frame_001_3d_gt.jpg         # 3D投影可视化
├── frame_001_bev_gt.jpg        # BEV俯视图
└── frame_001_combined.jpg      # 组合可视化

说明

• 脚本会自动查找标定文件（../calib/L2_calib/camera4.json）
• 如果找不到标定文件，会跳过3D可视化，只生成2D可视化
• 不应用ROI变换，使用原始图像尺寸

---

示例2: ROI模式（与训练一致）

当你的模型使用ROI训练时，应该使用相同的ROI配置进行可视化，以确保标签与训练时一致。

配置参数

从你的数据集配置文件（如data/mono3d.yaml）中获取：

# data/mono3d.yaml
roi: [704, 352]              # ROI尺寸 [width, height]
virtual_fx: 500              # 虚拟焦距
ori_img_size: [1920, 1080]   # 原始图像尺寸 [width, height]

运行命令

python scripts_for_gt/visualize_single_frame.py \
    --image /data/images/frame_001.jpg \
    --label /data/labels/frame_001.txt \
    --output ./viz_output_roi \
    --roi 704 352 \
    --virtual-fx 500 \
    --ori-img-size 1920 1080

效果对比

模式	图像尺寸	深度归一化	用途
原始	1920x1080	否	查看原始数据
ROI	704x352	是	与训练一致

说明

• ROI会裁剪图像到指定区域（以消失点为中心）
• 深度值会根据virtual_fx进行归一化
• 标签的2D坐标和UV坐标会相应调整
• 这与训练时的数据处理完全一致

---

示例3: 批量处理

当需要可视化多帧图像时，使用批量脚本更高效。

数据结构

/data/seq_001/
├── images/
│   ├── frame_001.jpg
│   ├── frame_002.jpg
│   └── ...
├── labels/
│   ├── frame_001.txt
│   ├── frame_002.txt
│   └── ...
└── calib/
    └── L2_calib/
        └── camera4.json

运行命令

python scripts_for_gt/visualize_batch.py \
    --image-dir /data/seq_001/images \
    --label-dir /data/seq_001/labels \
    --output ./batch_viz \
    --roi 704 352 \
    --virtual-fx 500 \
    --max-samples 20

输出结构

batch_viz/
├── frame_001/
│   ├── frame_001_2d_gt.jpg
│   ├── frame_001_3d_gt.jpg
│   ├── frame_001_bev_gt.jpg
│   └── frame_001_combined.jpg
├── frame_002/
│   └── ...
└── ...

说明

• --max-samples: 限制处理数量，用于快速测试
• 脚本会自动匹配图像和标签文件（基于文件名）
• 处理失败的样本会被跳过并记录错误

---

示例4: 自动测试

最简单的方式，让脚本自动找到并可视化一个样本。

运行命令

python scripts_for_gt/test_visualization.py \
    --data data/mono3d.yaml \
    --output ./test_output

脚本行为

1. 从data/mono3d.yaml读取验证集路径
2. 在验证集中查找第一个有标签的样本
3. 自动查找对应的标定文件
4. 生成两组可视化：
   • test_output/no_roi/: 原始图像可视化
   • test_output/with_roi/: ROI变换可视化

说明

• 用于快速验证脚本功能
• 自动使用数据集配置中的参数
• 适合首次使用或调试

---

常见场景

场景1: 只想查看2D标签

python scripts_for_gt/visualize_single_frame.py \
    --image image.jpg \
    --label label.txt \
    --output ./2d_only
# 不提供标定文件，自动跳过3D可视化

场景2: 指定标定文件路径

python scripts_for_gt/visualize_single_frame.py \
    --image image.jpg \
    --label label.txt \
    --calib /custom/path/camera4.json \
    --output ./custom_viz

场景3: 不同数据集配置

如果你有多个数据集配置（如roi0和roi1）：

# ROI 0 配置
python scripts_for_gt/visualize_single_frame.py \
    --image image.jpg \
    --label label.txt \
    --output ./viz_roi0 \
    --roi 704 352 \
    --virtual-fx 500

# ROI 1 配置  
python scripts_for_gt/visualize_single_frame.py \
    --image image.jpg \
    --label label.txt \
    --output ./viz_roi1 \
    --roi 800 400 \
    --virtual-fx 600

---

输出说明

2D可视化 (*_2d_gt.jpg)

• 显示2D边界框
• 不同类别使用不同颜色
• 显示类别名称
• 左上角标注"2D GT"

3D可视化 (*_3d_gt.jpg)

• 显示3D框投影到2D的效果
• 12条边（前面红色，后面绿色，连接边蓝色）
• 车辆类标记最佳可见面的中心点
• 左上角标注"3D GT"

BEV可视化 (*_bev_gt.jpg)

• 俯视图视角
• 显示物体在地面的投影
• 绿色表示真值（GT）
• 箭头指示物体朝向

组合可视化 (*_combined.jpg)

• 水平排列：2D | 3D | BEV
• 一眼看到所有信息
• 适合对比和分析

---

参数速查表

参数	必需	默认值	说明
--image	是	-	图像文件路径
--label	是	-	标签文件路径
--output	否	./gt_visualization	输出目录
--calib	否	自动推断	标定文件路径
--roi	否	None	ROI尺寸 (宽 高)
--virtual-fx	否	None	虚拟焦距
--ori-img-size	否	自动检测	原始图像尺寸 (宽 高)

批量脚本额外参数：

参数	必需	默认值	说明
--image-dir	是	-	图像目录
--label-dir	是	-	标签目录
--max-samples	否	None	最大处理数量

---

故障排查

问题1: "无法读取图像"

原因: 图像路径错误或文件不存在

解决:

# 检查文件是否存在
ls -lh /path/to/image.jpg

# 使用绝对路径
python scripts_for_gt/visualize_single_frame.py \
    --image $(pwd)/image.jpg \
    --label $(pwd)/label.txt

问题2: "未找到标定文件"

原因: 标定文件路径不符合默认规则

解决:

# 手动指定标定文件
python scripts_for_gt/visualize_single_frame.py \
    --image image.jpg \
    --label label.txt \
    --calib /correct/path/to/camera4.json

问题3: "没有成功解码的3D框"

原因:

• 标签格式不完整（只有2D信息）
• 深度值无效（z <= 0或NaN）
• 面可见性标记无效

解决:

# 检查标签内容
cat label.txt

# 如果只有2D标签，这是正常的，会跳过3D可视化

问题4: "ROI后标签数量为0"

原因: ROI区域没有包含任何目标

解决:

# 先不使用ROI查看原始标签
python scripts_for_gt/visualize_single_frame.py \
    --image image.jpg \
    --label label.txt \
    --output ./check

# 调整ROI参数或选择其他样本

---

进阶使用

自定义类别名称

修改脚本中的names字典：

names = {
    0: "Car",
    1: "Person", 
    2: "Bike",
    3: "Rider",
    13: "Tricycle",
}

调整可视化参数

修改脚本中的scale_factor参数：

# 更高分辨率输出
img_2d = plot_2d_boxes(..., scale_factor=3)

# 更小文件大小
img_2d = plot_2d_boxes(..., scale_factor=1)

导出3D参数

在脚本中添加导出逻辑：

# 在decoded循环中
if decoded and decoded.get('object_3d'):
    x, y, z, l, h, w, rot_y, _ = decoded['object_3d']
    print(f"Object: x={x:.2f}, y={y:.2f}, z={z:.2f}, dims=[{l:.2f},{h:.2f},{w:.2f}], rot_y={rot_y:.2f}")