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    # 相机标定
```

### 运行命令

```bash
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`）中获取：

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

### 运行命令

```bash
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
```

### 运行命令

```bash
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: 自动测试

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

### 运行命令

```bash
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标签

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

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

```bash
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）：

```bash
# 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: "无法读取图像"

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

**解决**:
```bash
# 检查文件是否存在
ls -lh /path/to/image.jpg

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

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

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

**解决**:
```bash
# 手动指定标定文件
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）
- 面可见性标记无效

**解决**:
```bash
# 检查标签内容
cat label.txt

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

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

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

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

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

---

## 进阶使用

### 自定义类别名称

修改脚本中的`names`字典：

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

### 调整可视化参数

修改脚本中的`scale_factor`参数：

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

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

### 导出3D参数

在脚本中添加导出逻辑：

```python
# 在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}")
```