ComfyUI Extension: ComfyUI-gaussian_preview

Authored by yichengup

Created

Updated

7 stars

Preview and record 3D Gaussian splatting models with interactive 3D rendering and video export. (Description by CC)

Custom Nodes (0)

    README

    ComfyUI Gaussian Preview

    ComfyUI 自定义节点，用于预览和录制 3D 高斯点云（Gaussian Splatting）模型。

    可高分辨率录制视频

    注意：此节点是从 ComfyUI-GeometryPack 中提取的预览功能，经过优化并增加了视频录制功能。主要用于预览各种来源生成的高斯 3D 模型，包括但不限于 ComfyUI-Sharp 等工具生成的高斯点云。

    功能特性

    • 🎨 交互式 3D 预览：使用 gsplat.js 在浏览器中实时渲染高斯点云
    • 🎥 视频录制：支持录制预览窗口为 MP4 视频（最高 4096px 宽度）- 新增功能
    • 📐 相机参数支持：自动根据 extrinsics 和 intrinsics 设置初始视角
    • 🎛️ 可调预览尺寸：支持自定义预览窗口宽度（256-4096px），影响录制分辨率
    • 🔄 动态缩放：支持实时调整高斯点云的显示比例
    • 📸 重置视角：一键重置到初始相机视角
    • ⚡ 优化性能：移除了不必要的功能，专注于预览和录制体验

    安装

    1. 将本仓库克隆到 ComfyUI 的 custom_nodes 目录：
    cd ComfyUI/custom_nodes
git clone https://github.com/your-username/ComfyUI-gaussian_preview.git

    1. 此节点支持任何生成 PLY 格式高斯点云的工具，包括：

    2. 重启 ComfyUI

    使用方法

    基本使用

    1. 使用任何支持的工具生成 PLY 格式的高斯点云文件：
      • ComfyUI-Sharp 的 SHARP Predict 节点
      • ComfyUI-GeometryPack 的相关节点
      • 其他生成高斯点云的工具
    2. 将 PLY 文件路径连接到 Preview Gaussian 节点的 ply_path 输入
    3. （可选）连接 extrinsics 和 intrinsics 参数以设置正确的初始视角
    4. 执行节点，预览窗口将显示 3D 高斯点云

    节点参数

    必需参数

    • ply_path (STRING): 高斯点云 PLY 文件的路径

    可选参数

    • extrinsics (EXTRINSICS): 4x4 相机外参矩阵，用于设置初始视角
    • intrinsics (INTRINSICS): 3x3 相机内参矩阵，用于设置视场角（FOV）
    • preview_width (INT): 预览窗口宽度（像素），默认 512
      • 范围：256-4096
      • 步长：64
      • 注意：此参数直接影响视频录制的分辨率

    控制功能

    预览窗口底部提供以下控制：

    • Scale: 调整高斯点云的显示比例（0.01-100）
    • Reset View: 重置相机到初始视角
    • Max (s): 设置最大录制时长（秒），默认 30 秒
    • Start Record: 开始录制视频（MP4 格式）

    视频录制

    1. 调整预览窗口到满意的视角
    2. 设置最大录制时长（Max (s)）
    3. 点击 "Start Record" 开始录制
    4. 录制完成后，视频会自动保存到 ComfyUI 输出目录
    5. 视频路径会通过节点的 video_path 输出端口返回

    录制分辨率说明：

    • 录制分辨率 = 预览窗口的实际显示尺寸
    • 预览窗口宽度由 preview_width 参数控制
    • 高度根据图像宽高比自动计算
    • 建议设置：512px（默认）、768px、1024px、1920px 等

    与高斯点云生成工具集成

    此节点设计用于与多种高斯点云生成工具配合使用：

    与 ComfyUI-Sharp 集成

    [Load Image] → [SHARP Predict] → [Preview Gaussian]
                                    ↓
                              [video_path 输出]

    与 ComfyUI-GeometryPack 集成

    [相关几何节点] → [高斯点云生成] → [Preview Gaussian]
                                      ↓
                                [video_path 输出]

    完整工作流示例

    1. 使用 Load Image with EXIF 或 Load Image 加载图像
    2. 使用支持的工具生成高斯点云（PLY 文件）：
      • SHARP Predict 节点（ComfyUI-Sharp）
      • ComfyUI-GeometryPack 中的相关节点
      • 其他高斯点云生成工具
    3. 将 PLY 文件路径和相机参数连接到 Preview Gaussian 节点
    4. 在预览窗口中查看和调整视角
    5. 录制视频并获取输出路径

    技术细节

    • 渲染引擎：gsplat.js（WebGL 加速）
    • 视频格式：MP4 (H.264)
    • 录制帧率：30 FPS
    • 视频比特率：5 Mbps
    • 支持浏览器：Chrome、Firefox、Edge、Safari

    依赖项

    注意事项

    1. 浏览器兼容性：视频录制功能需要浏览器支持 MediaRecorder API
    2. 性能：较大的预览窗口（>1920px）可能会影响渲染性能
    3. 内存：录制长时间视频会消耗较多内存
    4. 相机参数：提供正确的 intrinsics 和 extrinsics 可以获得更好的初始视角

    许可证

    GPL-3.0-or-later

    项目历史

    此项目是从 ComfyUI-GeometryPack 中提取的预览功能，经过以下优化：

    • 移除了不必要的功能，专注于预览体验
    • 新增视频录制功能
    • 优化了用户界面和交互体验
    • 提升了性能和稳定性

    致谢

    关于我 | About me

    Bilibili：我的B站主页 QQ号：3260561522 wechat微信: DLONG189one