nano_WaveGen/utils/README_visualize.md

# WaveGen 训练可视化工具

独立的训练结果可视化工具，自动检索 `core_space` 目录并通过 Viser 进行 3D 可视化。

## 🚀 快速开始

### 1. 基本使用

在 `nano_WaveGen` 目录下运行：

```bash
cd code/WaveGen/nano_WaveGen
python utils/visualize_training.py
```

### 2. 指定 core_space 目录

```bash
python utils/visualize_training.py --core-space ../WaveGen_Augustus_v1/core_space
```

### 3. 指定端口

```bash
python utils/visualize_training.py --port 8888
```

### 4. 禁用自动打开浏览器

```bash
python utils/visualize_training.py --no-browser
```

## 📋 功能特性

### ✅ 自动端口分配
- 默认尝试使用 8080 端口
- 如果端口被占用，自动尝试下一个端口 (8081, 8082, ...)
- 最多尝试 10 个端口
- 自动在浏览器中打开正确的URL

### ✅ 自动扫描训练输出
- 自动检测 `core_space/` 下的所有训练输出目录
- 格式: `YYYYMMDD_HHMMSS_stepN_text2wave`
- 统计每个输出的样本数量

### 🎨 3D 可视化
- **超二次曲面渲染**: 生成的预测结果（蓝色）和 Ground Truth（红色）
- **点云显示**: 从深度图重建的原始点云
- **相机可视化**: GT 相机位置和朝向
- **坐标系显示**: 世界坐标系参考

### 🎮 交互控制
- **训练输出选择**: 下拉菜单选择不同的训练输出
- **样本选择**: 滑块选择样本索引
- **帧控制**: 滑块切换帧，播放/暂停动画
- **颜色和透明度**: 实时调整渲染参数
- **网格分辨率**: 调整超二次曲面的网格质量

### ⚡ 性能优化
- **对象池机制**: 复用 mesh 对象，减少内存分配
- **惰性加载**: 按需加载帧数据
- **缓存策略**: 预加载相邻帧数据

## 🎛️ GUI 控制说明

### 训练输出面板
- **选择训练输出**: 选择要查看的训练输出
- **样本索引**: 选择样本（0 到 N-1）
- **加载样本**: 点击加载选中的样本

### 帧控制面板
- **当前帧**: 滑块切换帧（0-23）
- **▶ 播放**: 开始自动播放动画
- **⏸ 暂停**: 暂停动画播放
- **播放FPS**: 设置播放帧率（1-30）

### 生成结果面板
- **显示生成的超二次曲面**: 开关预测结果显示
- **生成结果透明度**: 调整蓝色 mesh 的透明度
- **生成结果颜色**: 自定义预测结果颜色（默认蓝色）

### Ground Truth 面板
- **显示GT超二次曲面**: 开关 GT 显示
- **GT透明度**: 调整红色 mesh 的透明度
- **GT颜色**: 自定义 GT 颜色（默认红色）

### 点云显示面板
- **显示点云**: 开关点云显示
- **点大小**: 调整点云渲染大小（0.001-0.02）

### 渲染设置面板
- **网格分辨率**: 调整超二次曲面的网格精度（10-50）
- **显示坐标系**: 开关世界坐标系显示

### 相机控制面板
- **重置视角**: 恢复默认观察视角
- **匹配GT相机**: 将视角设置为 GT 相机视角

## 📦 数据格式支持

### 支持的文件结构

```
core_space/
├── 20251204_212328_step5_text2wave/
│   ├── sample_0/
│   │   ├── predictions.npz          # 模型预测结果
│   │   ├── targets.npz              # Ground Truth
│   │   ├── info.txt                 # 样本信息
│   │   └── original_data/           # 原始数据
│   │       ├── Full_Sample_Data_for_Learning_Target.npz
│   │       ├── depth/
│   │       │   └── depth_merge.npz  # 或 frame_*.npy
│   │       ├── rgb/
│   │       │   └── frame_*.png
│   │       ├── segmentation/
│   │       ├── metadata.json
│   │       └── camera_trajectory.npz
│   ├── sample_1/
│   └── ...
└── 20251128_124329_step5_text2wave/
    └── ...
```

### predictions.npz 格式

```python
frames = [
    {
        'objects': [max_objects, 15],  # 每个对象15个参数
        'world': [8],                   # 世界参数
        'physics': [max_objects, 3]     # 物理属性（可选）
    },
    ...  # 24帧
]

# objects 参数 [15]:
# [0]: exists          存在标志 (0/1)
# [1:3]: shape         ε1, ε2
# [3:6]: scale         a, b, c
# [6:9]: translation   x, y, z
# [9:12]: rotation     rx, ry, rz (欧拉角)
# [12:15]: velocity    vx, vy, vz
```

### targets.npz 格式

```python
objects = [num_frames, max_objects, 16]  # 16参数（多了inlier_ratio）
world = [num_frames, 11]                 # 11参数（包含scene_center）
physics = [max_objects, 3]               # 物理属性（可选）
```

## 🔧 依赖项

### Python 包
- `viser` - 3D 可视化服务器
- `numpy` - 数值计算
- `scipy` - 旋转矩阵计算
- `opencv-python` - 图像处理
- `pillow` - 图像加载

### 本地模块
- `depth_to_pointcloud.py` - 深度图转点云工具

### 安装依赖

```bash
pip install viser numpy scipy opencv-python pillow
```

## 🎯 使用场景

### 1. 检查训练质量
对比蓝色（预测）和红色（GT）mesh 的重合程度

### 2. 调试模型
实时查看每一帧的生成结果

### 3. 制作演示
通过播放功能展示训练效果

### 4. 数据分析
结合点云查看模型对原始数据的拟合质量

## 🐛 常见问题

### Q: 找不到训练输出？
A: 确保 `core_space` 目录存在且包含 `*_text2wave` 格式的文件夹。

### Q: 无法显示点云？
A: 检查 `original_data/depth/` 目录是否存在深度文件。

### Q: Mesh 显示不正确？
A: 尝试调整"网格分辨率"或检查 superquadric 参数是否正确。

### Q: 端口被占用？
A: 脚本会自动检测并使用下一个可用端口（8080→8081→8082...），无需手动干预。也可以用 `--port` 参数指定起始端口。

### Q: 浏览器没有自动打开？
A: 检查系统的默认浏览器设置。或者使用 `--no-browser` 参数禁用自动打开，然后手动访问终端显示的URL。

### Q: 页面一直显示空白？
A: 尝试刷新浏览器（Ctrl+Shift+R）或切换到 Chrome/Firefox 浏览器。

## 📝 开发说明

### 添加新功能

1. 在 `TrainingVisualizer` 类中添加方法
2. 在 `setup_gui()` 中添加 GUI 控件
3. 在对应的回调函数中实现逻辑

### 性能优化

- 使用对象池避免重复创建 mesh
- 预加载相邻帧数据
- 调整网格分辨率平衡质量和性能

## 📄 许可

与 WaveGen 项目保持一致