ComfyUI-DreamScene360：将 2.5D 全景图瞬间转化为可漫游的 3D 高斯世界

在 3D 内容创作工作流中，360° 全景图（等距柱状投影） 是一种极易获取的资产（可通过 AI 生成、360 相机拍摄或游戏引擎渲染获得）。然而，全景图本质上是 2.5D 的——它只有一个视点，物体背后是空的，无法支持真正的 6-DoF（六自由度）漫游。

ComfyUI-DreamScene360 是一个专为 ComfyUI 设计的自定义节点，封装了 DreamScene360 的核心算法，能够直接将一张 360° 全景图 + 深度图 转化为 全局一致、填补了空洞的 3D 高斯泼溅 (3DGS) 点云。

GitHub：https://github.com/jfirma1/ComfyUI-DreamScene360

无需复杂的文本提示工程，无需调用昂贵的 API，只需输入图像，即可输出标准的 .ply 文件，无缝接入下游的 3D 渲染、编辑或视频生成节点。

ComfyUI-DreamScene360：将 2.5D 全景图瞬间转化为可漫游的 3D 高斯世界

核心魔法：从“平面球”到“立体世界”

该节点不仅仅是简单的深度反投影，它复现了 DreamScene360 论文中的完整重建管线，解决了单视角全景图的固有缺陷：

🔄 切平面投影 (Cube Projection)：将球形全景图重投影为多个重叠的透视裁剪区域，模拟多视角输入。
📏 单目深度估计：在每个裁剪区域上运行强大的 omnidata_dpt_depth_v2 模型，提取高精度深度。
🧩 全局深度对齐：利用泊松融合 (Poisson Fusion) 将所有局部深度图拼接成连贯的全景深度场，消除接缝。
🧠 MLP 神经优化：通过小型神经网络平滑跨接缝的深度不连续性，修复几何瑕疵。
☁️ 点云重投影：将对齐后的深度反投影到 3D 世界空间，生成初始点云。
✨ 高斯溅射训练：以点云为初始化，针对原始全景图进行 3DGS 优化，自动“脑补”并填充被遮挡的空洞区域，生成真正的 volumetric 3D 场景。

节点详解

1. DreamScene360 Pano to Pointcloud (主节点)

这是核心处理单元，负责执行完整的重建流程。

参数	默认值	描述与建议
scene_name	`my_scene`	缓存键。相同名称会复用已生成的 `.ply` 文件，跳过耗时训练。
iterations	`3000`	高斯溅射训练步数。建议: 先用 3000 步预览，最终输出用 9000 步。
opacity_threshold	`0.05`	过滤掉透明度低于此值的噪点高斯，净化点云。
max_points	`500000`	输出点云的最大点数限制，用于控制显存占用。
upscale	`false`	若设为 `true`，处理前将全景图放大 2 倍，显著提升几何细节（需更多显存）。
skip_if_exists	`true`	强烈推荐开启。若该 `scene_name` 已训练过，直接加载缓存，秒级响应。

输入:

panorama: 360° 等距柱状投影图像 (推荐分辨率 4096x2048+)。
depth_map: 匹配的深度图 (灰度图)。若不提供，节点内部可尝试生成，但提供高质量深度图效果更佳。

输出:

pointcloud: 包含 points, colors, ply_path 的字典，可直接连接至 3D 查看器或编辑器。
panorama_passthrough: 原始全景图直通。
depth_passthrough: 原始深度图直通。

2. Load Gaussian PLY (工具节点)

功能: 直接加载任何现有的 .ply 文件（无论是本节点之前生成的，还是外部工具创建的）。
用途: 允许你将训练好的 3D 资产持久化，并在不同工作流中重复使用，无需重新训练。

性能与速度

得益于 3DGS 的高效性，即使在消费级显卡上，生成速度也令人印象深刻：

GPU 型号	3,000 次迭代 (预览)	9,000 次迭代 (成品)
NVIDIA A100	~3 分钟	~8 分钟
RTX 4090	~4 分钟	~12 分钟
RTX 3090	~6 分钟	~18 分钟
RTX 4080/4070	~5-7 分钟	~15-20 分钟

提示: 开启 skip_if_exists=true 后，第二次运行仅需 <1 秒 即可加载结果。

安装指南

方式 A：自动安装 (推荐)

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/YOUR_USERNAME/ComfyUI-DreamScene360.git
cd ComfyUI-DreamScene360
python install.py

脚本会自动克隆引擎、安装依赖、构建 CUDA 扩展并下载必要的检查点。

方式 B：手动安装 (进阶)

若自动脚本失败，可手动执行以下步骤：

克隆仓库:

git clone --recursive https://github.com/ShijieZhou-UCLA/DreamScene360.git dreamscene360_engine

安装系统依赖 (Ubuntu/Debian):

sudo apt-get install -y libglm-dev libglew-dev libassimp-dev libboost-all-dev libgtk-3-dev libopencv-dev libglfw3-dev libavdevice-dev libeigen3-dev

安装 Python 包:

pip install plyfile open3d trimesh scipy einops timm opencv-python scikit-image omegaconf

构建 CUDA 扩展:

pip install dreamscene360_engine/submodules/diff-gaussian-rasterization-depth
pip install dreamscene360_engine/submodules/simple-knn
pip install git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch

下载检查点:
- 下载 omnidata_dpt_depth_v2.ckpt (从 DreamScene360 官方 Dropbox 链接)。
- 放置路径：ComfyUI-DreamScene360/dreamscene360_engine/pre_checkpoints/omnidata_dpt_depth_v2.ckpt

最佳实践工作流

生成/获取全景图: 使用 SDXL/Midjourney 生成 360° 全景图，或用 360 相机拍摄。
估算深度: 使用 ComfyUI 中的 ZoeDepth 或 MiDaS 节点生成对应的深度图（确保也是等距柱状投影格式）。
运行转换: 连接至 DreamScene360 Pano to Pointcloud 节点。
- 设置 scene_name = "cyberpunk_city"。
- 设置 iterations = 3000 进行快速测试。
预览与迭代: 连接 3D 查看器节点，确认几何结构无误。
最终输出: 将 iterations 改为 9000，upscale = true (若显存允许)，再次运行以获得最高质量。
下游应用: 将输出的 .ply 用于：
- 视频生成: 结合 SVD 或 Gen-2 制作运镜视频。
- VR 体验: 导出至 Unity/Unreal 引擎。
- 二次编辑: 使用 3D 编辑工具移除物体或添加新元素。

⚠️ 注意事项与故障排除

显存不足 (OOM):
- 解决方案：设置 upscale = false，降低 max_points 至 200,000，或减少 iterations。
- 确保关闭其他占用显存的应用。
几何接缝明显:
- 通常是因为输入的深度图质量不佳。尝试使用更高分辨率的深度估计模型，或确保全景图与深度图严格对齐。
CUDA 编译错误:
- 确保已安装完整的 CUDA Toolkit (nvcc --version 应可用)。
- 安装 libglm-dev (sudo apt-get install libglm-dev) 常能解决光栅化器编译问题。
缓存管理:
- 生成的 .ply 文件保存在 ComfyUI-DreamScene360/output/{scene_name}/。定期清理不需要的场景以释放磁盘空间。