# DIST-OCC

**Repository Path**: xupeng-fu/DIST-OCC

## Basic Information

- **Project Name**: DIST-OCC
- **Description**: 自蒸馏3D Occupancy，训练测试可视化已完成。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-20
- **Last Updated**: 2025-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GSDOCCDISS: 纯卷积自蒸馏OCC

<img src="assets/0103_compressed.gif">
<img src="assets/0916_compressed.gif">

<details>
<summary>结果说明</summary>

**为什么两段 GIF 的可视化效果比较粗糙？**  
- 本示例模型使用的是 *mini* 训练集上快速验证的轻量级权重，仅供演示流程。  
- 与完整 **trainval** 数据集训练得到的权重相比，*mini* 权重在语义分割和占用预测上都存在明显精度损失，因此展示出的 mIoU 和外观质量都要低不少。  

</details>



## 项目简介

GSDOCCDISS是基于GSDOCC的占用预测方法。项目支持端到端的训练、推理和可视化，适用于OCC3D。

<!-- - 论文：[FB-BEV](https://arxiv.org/abs/2308.02236) | [FB-OCC](https://arxiv.org/abs/2307.01492)
- 视频介绍：[YouTube](https://youtu.be/KEn8oklzyvo?si=zydZjIwoTzTd-bsO) -->

## 环境安装

建议使用 Conda 创建独立环境，参考 `create_env.bash`：

```bash
# 初始化 conda
conda create --name gsdocc python=3.8 -y
conda activate gsdocc

# 安装 PyTorch（CUDA 11.3）
pip install torch==1.11.0+cu113 torchvision==0.12.0+cu113 torchaudio==0.11.0 --extra-index-url https://download.pytorch.org/whl/cu113

# 安装 OpenMMLab 相关依赖
pip install -U openmim
pip install mmcv-full==1.5.3 -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.11.0/index.html
pip install mmdet==2.25.1
pip install mmsegmentation==0.25.0
pip install mmengine

# 其他依赖
pip install numpy==1.23.4 yapf==0.40.1 setuptools==59.5.0 ninja einops open3d==0.16.0

# 安装本地包
pip install -v -e .
```

## 数据准备

- 原始数据集目录参考GSDOCC。
- tools/create_data_bevdet.py生成pkl，第48行默认VERSION= 'v1.0-mini'。
- tools/generate_depth_multi.py生成多帧depth，第50行默认version='v1.0-mini'

## 训练与测试

配置文件：

```
occupancy_configs/gsd_occ/gsdoccdiss_r50_256x704_16f_8x4_24.py
```

基本训练命令：

```bash
# 单机多卡训练
bash tools/dist_train.sh occupancy_configs/gsd_occ/gsdoccdiss_r50_256x704_16f_8x4_24.py
```
剩余训练时长会先变少再变多再变少，属于正常现象

评测命令：

```bash
bash tools/dist_test.sh occupancy_configs/gsd_occ/gsdoccdiss_r50_256x704_16f_8x4_24.py work_dirs/gsdoccdiss_r50_256x704_16f_8x4_24e.py/latest.pth 8
```

## 可视化说明

本项目支持3D Occupancy可视化，采用三步流程：测试生成结果 → 可视化单帧 → 生成GIF动图。

### 可视化流程

#### 第一步：测试生成结果
```bash
# 运行测试脚本生成pkl文件
python tools/test.py \
    cfg \
    path_of_ckpt \
    --out path_of_vis.pkl
```

#### 第二步：可视化单帧
```bash
# 可视化指定场景的单帧图片
python tools/analysis_tools/vis_frame.py \
    path_of_vis.pkl \
    cfg \
    --save-path where_picture_will_be_save \
    --scene-idx 0916 \
    --num-workers 4 \
    --render-cameras all
```

#### 第三步：生成GIF动图
```bash
# 基于单帧图片生成GIF动图
python tools/analysis_tools/generate_gifs.py \
    --scene-dir vis/scenes/scene-0916
```

### 参数说明

#### 测试脚本参数
| 参数 | 说明 | 示例值 |
|------|------|--------|
| 配置文件 | 模型配置文件路径 | `occupancy_configs/gsd_occ/gsdoccdiss_r50_256x704_16f_8x4_24.py` |
| 权重文件 | 训练好的模型权重 | `work_dirs/gsdoccdiss_r50_256x704_16f_8x4_24/latest.pth` |
| `--out` | 输出pkl文件路径 | `vis/vis.pkl` |

#### 可视化脚本参数
| 参数 | 说明 | 示例值 |
|------|------|--------|
| pkl文件 | 第一步生成的pkl文件 | `vis/vis.pkl` |
| 配置文件 | 模型配置文件路径 | `occupancy_configs/gsd_occ/gsdoccdiss_r50_256x704_16f_8x4_24.py` |
| `--save-path` | 单帧图片保存路径 | `vis/scenes` |
| `--scene-idx` | 要可视化的场景索引 | `0916` |
| `--num-workers` | 并行工作进程数 | `4` |
| `--render-cameras` | 渲染的相机视角 | `all` |

#### GIF生成脚本参数
| 参数 | 说明 | 示例值 |
|------|------|--------|
| `--scene-dir` | 单帧图片所在目录 | `vis/scenes/scene-0916` |

### 输出文件结构

```
vis/
├── vis.pkl                    # 第一步：测试结果pkl文件
├── scenes/
│   └── scene-0916/           # 第二步：单帧图片目录
│       ├── 0.png
│       ├── 1.png
│       ├── ...
│       └── scene-0916.gif    # 第三步：生成的GIF动图
```

### 使用VSCode调试

项目提供了VSCode调试配置，可以在`.vscode/launch.json`中找到：

1. **1.test**：运行测试生成结果
2. **2.vis_frame**：可视化单帧图片
3. **3.generate_gifs**：生成GIF动图

### 注意事项

1. **文件路径**：确保所有路径正确，建议使用绝对路径
2. **场景索引**：`--scene-idx`参数指定要可视化的具体场景
3. **内存使用**：可视化大量场景时注意内存使用情况
4. **并行处理**：通过`--num-workers`参数控制并行度
5. **相机视角**：`--render-cameras all`渲染所有相机视角

### 效果展示

您可以在README顶部看到可视化效果的GIF动图示例，展示了模型在3D占用预测上的表现。

## 修改

<img src="assets/3.png" width="50%">

- **GSDOCCDISS（gsdoccdiss.py）**：
  
  基于GSDOCC框架，采用自蒸馏训练策略。

- **DecoupleOccHeadDISS（decouple_occ_headdiss.py）**：

  采用Flashocc提出的C2H和卷积替代MLP的C2H进行BEV→Voxel。

## 预训练模型

算力有限，加急训练中


<!-- ## 预训练模型

可在 [Model Zoo](https://github.com/NVlabs/FB-BEV) 或项目主页下载预训练权重。

| Backbone | Method | Config | 权重下载 |
| :---: | :---: | :---: | :---: |
| R50 | FB-OCC | [config](occupancy_configs/gsd_occ/gsdoccdiss_r50_256x704_16f_8x4_24.py) | [model](https://github.com/zhiqi-li/storage/releases/download/v1.0/fbocc-r50-cbgs_depth_16f_16x4_20e.pth) | -->

## Todo

- 对FlashOCC的C2H理解有偏差，导致lift BEV的效果不足，需要简化HEAD。
- 占用HEAD输入了前向投影得到的体素，但是蒸馏效果不好，需要改进体素蒸馏，而不是简单的Voxel-BEV蒸馏。
- TRT。
- 可视化class由stcocc迁移而来，class没对齐，需要根据FB-OCC的class修改。

## 许可协议

- 代码：Nvidia Source Code License-NC，详见 [LICENSE](https://github.com/NVlabs/FB-BEV/blob/main/LICENSE)
- 预训练模型：CC-BY-NC-SA-4.0

如需商业授权，请访问 [NVIDIA Research Licensing](https://www.nvidia.com/en-us/research/inquiries/)

<!-- ## 引用

如果本项目对您的研究有帮助，请引用：

```
@inproceedings{li2023fbbev,
  title={{FB-BEV}: {BEV} Representation from Forward-Backward View Transformations},
  author={Li, Zhiqi and Yu, Zhiding and Wang, Wenhai and Anandkumar, Anima and Lu, Tong and Alvarez, Jose M},
  booktitle={IEEE/CVF International Conference on Computer Vision (ICCV)},
  year={2023}
}
```

```
@article{li2023fbocc,
  title={{FB-OCC}: {3D} Occupancy Prediction based on Forward-Backward View Transformation},
  author={Li, Zhiqi and Yu, Zhiding and Austin, David and Fang, Mingsheng and Lan, Shiyi and Kautz, Jan and Alvarez, Jose M},
  journal={arXiv:2307.01492},
  year={2023}
}
``` -->

## 致谢

感谢以下优秀开源项目的支持：

- [BEVFormer](https://github.com/fundamentalvision/BEVFormer)
- [BEVDet](https://github.com/HuangJunJie2017/BEVDet)
- [Occ3D](https://github.com/Tsinghua-MARS-Lab/Occ3D)
- [OpenOccupancy](https://github.com/JeffWang987/OpenOccupancy)
- [SoloFusion](https://github.com/Divadi/SOLOFusion)
- [GSDOCC](https://github.com/harrylin-hyl/GSD-OCC)