# 条件过滤可视化使用指南

## 概述

`visualize_filtered_train.py` 是一个强大的数据分析工具，可以从训练集或验证集中筛选符合特定条件的样本进行可视化。

## 主要功能

1. **类别过滤** - 只查看特定类别的样本
2. **3D空间过滤** - 只查看特定3D空间范围内的目标
3. **批量处理** - 自动查找并可视化符合条件的样本
4. **摘要生成** - 自动生成包含所有样本信息的摘要文件

## 使用场景

### 场景1: 数据质量检查

**需求**: 检查两轮车标注质量，特别是近距离目标（0-50米）

```bash
python scripts_for_gt/visualize_filtered_train.py \
    --data data/mono3d.yaml \
    --target-class bicycle \
    --z-range 0 50 \
    --max-samples 30 \
    --output ./qa_bicycle_near
```

**输出**:
- 30个包含近距离两轮车的样本
- 每个样本生成4张可视化图（2D, 3D, BEV, Combined）
- `summary.txt` 文件包含所有样本的详细信息

### 场景2: 类别分布分析

**需求**: 分析训练集中行人的分布情况

```bash
python scripts_for_gt/visualize_filtered_train.py \
    --data data/mono3d.yaml \
    --target-class pedestrian \
    --max-samples 100 \
    --output ./analysis_pedestrian
```

这会找到前100个包含行人的样本，通过可视化可以：
- 查看行人在不同位置、距离的标注质量
- 检查遮挡情况
- 分析姿态多样性

### 场景3: 特定区域分析

**需求**: 分析车辆在车道中心区域（左右±3米）的标注

```bash
python scripts_for_gt/visualize_filtered_train.py \
    --data data/mono3d.yaml \
    --target-class vehicle \
    --x-range -3 3 \
    --z-range 5 100 \
    --max-samples 50 \
    --output ./analysis_vehicle_center_lane
```

### 场景4: 边界情况分析

**需求**: 查看距离较远的目标（50-100米）

```bash
python scripts_for_gt/visualize_filtered_train.py \
    --data data/mono3d.yaml \
    --z-range 50 100 \
    --max-samples 40 \
    --output ./analysis_far_distance
```

### 场景5: 横向位置分析

**需求**: 分析左侧（负X）和右侧（正X）目标的分布

```bash
# 左侧目标
python scripts_for_gt/visualize_filtered_train.py \
    --data data/mono3d.yaml \
    --x-range -20 -5 \
    --max-samples 30 \
    --output ./analysis_left_side

# 右侧目标
python scripts_for_gt/visualize_filtered_train.py \
    --data data/mono3d.yaml \
    --x-range 5 20 \
    --max-samples 30 \
    --output ./analysis_right_side
```

## 参数详解

### 基本参数

- `--data`: 数据集配置文件路径
  - 默认: `data/mono3d.yaml`
  - 从配置文件中读取train/val路径

- `--output`: 输出目录
  - 默认: `./filtered_train_viz`
  - 会在此目录下为每个样本创建子目录

- `--split`: 数据集划分
  - 可选: `train` 或 `val`
  - 默认: `train`

### 过滤参数

#### 类别过滤

- `--target-class`: 目标类别名称
  - 可选值:
    * `vehicle` - 车辆（小汽车等）
    * `pedestrian` - 行人
    * `bicycle` - 两轮车
    * `rider` - 骑手
    * `motorcycle` - 摩托车
    * `tricycle` - 三轮车
  - 默认: `None`（不过滤类别）

#### 空间范围过滤

基于相机坐标系：

```
        Y (下)
        |
        |
        |_____ X (右)
       /
      Z (前)
```

- `--x-range MIN MAX`: X坐标范围（左右方向）
  - 单位: 米
  - 示例: `--x-range -10 10` (左右各10米)
  - X < 0: 左侧
  - X > 0: 右侧

- `--y-range MIN MAX`: Y坐标范围（上下方向）
  - 单位: 米
  - 示例: `--y-range -2 1`
  - Y < 0: 相机上方
  - Y > 0: 相机下方
  - 注意: 通常目标在地面，Y值接近0

- `--z-range MIN MAX`: Z坐标范围（前后方向/深度）
  - 单位: 米
  - 示例: `--z-range 0 50` (前方0到50米)
  - Z值: 距离相机的深度

#### 其他过滤参数

- `--min-targets`: 最少目标数量
  - 默认: 1
  - 示例: `--min-targets 2` (至少包含2个符合条件的目标)

- `--max-samples`: 最大可视化样本数
  - 默认: 20
  - 用于限制输出数量

### 可视化选项

- `--use-roi`: 使用ROI变换
  - 如果设置此标志，会应用训练时的ROI变换
  - 从数据集配置中读取roi、virtual_fx等参数

## 输出结构

```
output_dir/
├── summary.txt                    # 摘要文件
├── sample_001/
│   ├── sample_001_2d_gt.jpg      # 2D可视化
│   ├── sample_001_3d_gt.jpg      # 3D可视化
│   ├── sample_001_bev_gt.jpg     # BEV可视化
│   └── sample_001_combined.jpg   # 组合可视化
├── sample_002/
│   └── ...
└── ...
```

### 摘要文件内容

`summary.txt` 包含：
1. 过滤条件
2. 统计信息（总样本数、成功/失败数）
3. 每个样本的详细信息：
   - 文件名
   - 符合条件的目标数量
   - 每个目标的类别和3D位置

示例：
```
过滤可视化摘要
==================================================

过滤条件:
  目标类别: bicycle
  X范围: [-10.0, 10.0] 米
  Z范围: [0.0, 50.0] 米
  最少目标数: 1
  数据集: train

可视化结果:
  总样本数: 20
  成功: 20
  失败: 0

样本列表:
--------------------------------------------------
1. frame_001234.jpg
   符合条件的目标数: 2
   - bicycle: (-3.45, 0.12, 15.67)m
   - bicycle: (5.23, -0.08, 22.34)m

2. frame_005678.jpg
   符合条件的目标数: 1
   - bicycle: (1.23, 0.05, 8.90)m
...
```

## 高级用法

### 组合多个条件

```bash
# 查看近距离（0-20米）、车道中心（左右±5米）的行人
python scripts_for_gt/visualize_filtered_train.py \
    --data data/mono3d.yaml \
    --target-class pedestrian \
    --x-range -5 5 \
    --z-range 0 20 \
    --min-targets 1 \
    --max-samples 50 \
    --output ./pedestrian_near_center
```

### 从验证集筛选

```bash
# 从验证集而非训练集筛选
python scripts_for_gt/visualize_filtered_train.py \
    --data data/mono3d.yaml \
    --split val \
    --target-class vehicle \
    --z-range 30 80 \
    --max-samples 30 \
    --output ./val_vehicle_medium_distance
```

### 使用ROI变换

```bash
# 使用ROI变换进行可视化（与训练时一致）
python scripts_for_gt/visualize_filtered_train.py \
    --data data/mono3d.yaml \
    --target-class bicycle \
    --x-range -10 10 \
    --z-range 0 50 \
    --use-roi \
    --max-samples 20 \
    --output ./bicycle_with_roi
```

## 工作流程

脚本的工作流程如下：

```
1. 读取数据集配置 (data/mono3d.yaml)
   ↓
2. 获取train/val图像列表
   ↓
3. 遍历每个图像
   ├─ 读取对应的标签文件
   ├─ 解析标签（47维数组）
   ├─ 检查类别过滤条件
   ├─ 检查3D空间范围条件
   └─ 如果符合条件，添加到候选列表
   ↓
4. 对候选样本进行可视化
   ├─ 调用 visualize_single_frame()
   ├─ 生成 2D/3D/BEV/Combined 图像
   └─ 保存到对应子目录
   ↓
5. 生成摘要文件 (summary.txt)
```

## 性能优化

### 快速预览

如果只想快速查看几个样本：
```bash
python scripts_for_gt/visualize_filtered_train.py \
    --data data/mono3d.yaml \
    --target-class bicycle \
    --max-samples 5  # 只查看5个样本
```

### 限制搜索范围

脚本会遍历整个数据集直到找到足够的样本。如果数据集很大，可以：
1. 使用更宽松的过滤条件
2. 减少 `--max-samples` 数量

### 进度显示

脚本会每100个图像显示一次进度：
```
  进度: 100/5000, 已找到 5 个符合条件的样本
  进度: 200/5000, 已找到 12 个符合条件的样本
  ...
```

## 常见问题

### Q1: 为什么找不到符合条件的样本？

**可能原因**:
1. 过滤条件太严格（空间范围太小）
2. 数据集中该类别样本较少
3. 标签文件缺少3D信息

**解决方法**:
- 放宽空间范围
- 不设置空间范围，只过滤类别
- 检查标签文件格式

### Q2: 如何确定合适的空间范围？

**建议**:
1. 先不设置范围，可视化一些样本
2. 观察目标的典型位置
3. 根据观察结果设置范围

常见参考范围：
- 近距离: `--z-range 0 20`
- 中距离: `--z-range 20 50`
- 远距离: `--z-range 50 100`
- 车道中心: `--x-range -5 5`
- 侧边: `--x-range -20 -5` 或 `--x-range 5 20`

### Q3: 可以同时过滤多个类别吗？

目前不支持多类别过滤。如需查看多个类别，请分别运行：
```bash
python scripts_for_gt/visualize_filtered_train.py --target-class bicycle ...
python scripts_for_gt/visualize_filtered_train.py --target-class motorcycle ...
```

### Q4: 摘要文件在哪里？

摘要文件位于输出目录下：`{output_dir}/summary.txt`

## 实用技巧

1. **数据探索**: 先不设置过滤条件，随机可视化一些样本了解数据分布
2. **质量检查**: 使用空间范围过滤，系统地检查不同区域的标注质量
3. **类别平衡**: 分别统计各类别的样本数量，评估数据集平衡性
4. **边界情况**: 重点检查远距离、侧边等边界情况的标注质量

## 与其他脚本的对比

| 脚本 | 用途 | 输入 | 过滤能力 |
|------|------|------|---------|
| visualize_single_frame.py | 单帧可视化 | 单个图像+标签 | 无 |
| visualize_batch.py | 批量可视化 | 图像目录 | 无 |
| **visualize_filtered_train.py** | **条件过滤可视化** | **数据集配置** | **类别+空间** |
| test_visualization.py | 快速测试 | 数据集配置 | 无（自动找第一个） |
