ComfyUI-3D-Pack

让 ComfyUI 中的 3D 资源生成像生成图像/视频一样简单便捷！
这是一个功能强大的节点套件，使 ComfyUI 能够使用前沿算法（3DGS、NeRF 等）和模型（InstantMesh、CRM、TripoSR 等）处理 3D 输入（网格与 UV 纹理等）。

特性 — 安装 — 路线图 — 开发 — 提示 — 支持者

安装：

可以直接从 ComfyUI-Manager 安装🚀

或者，您也可以下载由 YanWenKun 制作的 Comfy3D-WinPortable

• 预编译版本适用于：
  • Windows 10/11
  • Python 3.12
  • CUDA 12.4
  • torch 2.5.1+cu124
• install.py 将根据您的运行环境自动下载并安装预编译版本；如果找不到对应的预编译版本，则会自动启动构建脚本。若自动构建对您不起作用，请参阅半自动构建指南。
• 如果在任何开放的 Comfy3D 工作流中缺少节点，可以尝试直接点击 ComfyUI-Manager 中的安装缺失自定义节点。
• 若缺少某些 Python 库，您可以查看我开发环境中的所有 Python 依赖项。
• 如果由于某种原因您的 Comfy3D 无法自动下载预训练模型，您可以随时手动下载并将它们放入 Checkpoints 目录下的正确文件夹中，但请务必不要覆盖现有的 .json 文件。
• Docker 安装请参考 DOCKER_INSTRUCTIONS.md。
• 注意：目前，为了使 InstantNGP 和 使用 NeRF 与 Marching_Cubes 将 3DGS 转换为网格 节点正常工作，您仍然需要安装 适用于 Windows 的 Visual Studio Build Tools 以及 为 Linux 安装 gcc g++，因为这两个节点使用了在运行时构建的 JIT torch cpp 扩展。不过，我计划替换这些节点。

手动安装方法

# 获取最新版 Comfy3D
cd 您的 ComfyUI 根目录\ComfyUI\custom_nodes\
git clone https://github.com/MrForExample/ComfyUI-3D-Pack.git
cd ComfyUI-3D-Pack

# 安装所有依赖项
您的 ComfyUI 根目录\python_embeded\python.exe -s -m pip install -r requirements.txt
您的 ComfyUI 根目录\python_embeded\python.exe install.py

特性：

• 使用场景请参阅 示例工作流。[最后更新：2025年6月5日]

  • 注意：您需要将 示例输入文件及文件夹 放置在 ComfyUI 根目录\ComfyUI\input 文件夹下，才能运行示例工作流。

• PartCrafter：wgsxm/PartCrafter

  • 双模型流程：
    • 单物体模式：
      • 单张图片 → 带有部件分割的 3D 网格
      • 输出：
        • 合并后的完整网格
        • 包含各个部件网格的 ZIP 压缩包
    • 场景模式：
      • 场景图片 → 多个 3D 部件网格
      • 输出：
        • 合并后的完整场景网格
        • 包含各个对象网格的 ZIP 压缩包
  • 模型权重：
    • PartCrafter（物体模式）
    • PartCrafter-Scene（场景模式）
  • 工作流：
    • 单物体
    • 场景

• Hunyuan3D_2.1：Tencent-Hunyuan/Hunyuan3D-2.1

  • 更新后的两阶段流程：
    • 单张图片 → 3D 网格（形状生成）
    • 3D 网格 + 参考图片 → 带 RGB 纹理的 3D 网格
  • 模型权重：https://huggingface.co/tencent/Hunyuan3D-2.1
  • 工作流：完整、形状生成、纹理生成

• MV-Adapter：huanngzh/MV-Adapter

  • 两种生成方式：
    • IG2MV：单张图片 + 3D 网格生成多视角图像
    • TG2MV：文本提示 + 3D 网格生成多视角图像
    • 纹理化：网格图像 + 3D 网格生成带纹理的网格
  • 模型权重：https://huggingface.co/huanngzh/mv-adapter
  • 工作流：IG2MV、T2MV、纹理化

• Stable3DGen: Stable-X/Stable3DGen

  • 两阶段模型流程：
    • Stable3DGen：单张图像生成3D网格
    • StableNormal：用于法线贴图生成的图像处理
  • 模型权重：
    • Stable3DGen：https://huggingface.co/Stable-X/trellis-normal-v0-1
    • StableNormal：https://huggingface.co/Stable-X/yoso-normal-v1-8-1
  • 工作流

• Hunyuan3D_V2：turbo、mini、fast、multiview

  • 单张图像生成3D网格
  • 多视角图像结合RGB纹理生成3D网格
  • 模型权重：https://huggingface.co/tencent/Hunyuan3D-2，https://huggingface.co/tencent/Hunyuan3D-2mini
  • 工作流

• TripoSG: VAST-AI-Research/TripoSG

  • 单张参考图或草图生成3D网格
  • 模型权重：https://huggingface.co/VAST-AI/TripoSG，https://huggingface.co/VAST-AI/TripoSG-scribble

• TRELLIS: microsoft/TRELLIS

  • 单张图像生成带有RGB纹理的3D网格
  • 模型权重：https://huggingface.co/jetx/TRELLIS-image-large

• Hunyuan3D_V2 tencent/Hunyuan3D-2

  • 两阶段流程：
    1. 单张图像仅生成3D网格形状
    2. 结合3D网格形状和一张参考图生成带有RGB纹理的3D网格
  • 模型权重：https://huggingface.co/tencent/Hunyuan3D-2/tree/main
  • 工作流

• Hunyuan3D_V1 tencent/Hunyuan3D-1

  • 两阶段流程：
    1. 单张图像生成多视角图像
    2. 多视角图像结合RGB纹理生成3D网格
  • 模型权重：https://huggingface.co/tencent/Hunyuan3D-1/tree/main

• StableFast3D: Stability-AI/stable-fast-3d

  • 单张图像生成带有RGB纹理的3D网格
  • 注意：在下载模型权重之前，您需要同意Stability AI的使用条款。如果您手动下载了模型权重，则需要将其放置在[Checkpoints/StableFast3D]目录下；否则，您可以将您的Hugging Face令牌添加到[Configs/system.conf]中。
  • 模型权重：https://huggingface.co/stabilityai/stable-fast-3d/tree/main

• CharacterGen: zjp-shadow/CharacterGen

  • 单张任意姿势的人物正面图像
  • 可与Unique3D工作流结合使用以获得更好的效果
  • 模型权重：https://huggingface.co/zjpshadow/CharacterGen/tree/main

• Unique3D: AiuniAI/Unique3D

  • 四阶段流程：
    1. 单张图像生成4张分辨率为256×256的多视角图像
    2. 将一致的多视角图像超分辨率至512×512，并进一步超分辨率至2048×2048
    3. 将多视角图像生成分辨率为512×512的法线贴图，并进一步超分辨率至2048×2048
    4. 将多视角图像和法线贴图结合生成带纹理的3D网格
  • 要使用全阶段Unique3D工作流，请下载以下模型：
    • sdv1.5-pruned-emaonly并将其放入您的ComfyUI根目录/ComfyUI/models/checkpoints
    • fine-tuned controlnet-tile并将其放入您的ComfyUI根目录/ComfyUI/models/controlnet
    • ip-adapter_sd15并将其放入您的ComfyUI根目录/ComfyUI/models/ipadapter
    • OpenCLIP-ViT-H-14，重命名为OpenCLIP-ViT-H-14.safetensors并将其放入您的ComfyUI根目录/ComfyUI/models/clip_vision
    • RealESRGAN_x4plus并将其放入您的ComfyUI根目录/ComfyUI/models/upscale_models
  • 模型权重：https://huggingface.co/spaces/Wuvin/Unique3D/tree/main/ckpt

• Era3D MVDiffusion Model: pengHTYX/Era3D

  • 单张图像生成6张分辨率为512×512的多视角图像及法线贴图
  • 注：运行此模型至少需要16GB显存
  • 模型权重：https://huggingface.co/pengHTYX/MacLab-Era3D-512-6view/tree/main

• InstantMesh重建模型: TencentARC/InstantMesh

  • 带有白色背景的稀疏多视角图像生成带有RGB纹理的3D网格
  • 可与任意MVDiffusion模型配合使用（可能与Zero123++效果最佳，但也适用于CRM MVDiffusion模型）
  • 模型权重：https://huggingface.co/TencentARC/InstantMesh/tree/main

• Zero123++: SUDO-AI-3D/zero123plus

  • 单张图像生成6张分辨率为320×320的视角图像

• 卷积重建模型：thu-ml/CRM

  • 三阶段流程：
    1. 单张图像转为6视角图像（前、后、左、右、上、下）
    2. 单张图像及6视角图像转为6个相同视角的CCM（规范坐标映射）
    3. 6视角图像及CCM转为3D网格
  • 注意：对于显存较低的电脑，如果无法将各阶段的三个模型全部加载到显存中，可以将这三个阶段拆分到不同的ComfyUI工作流中分别运行
  • 模型权重：https://huggingface.co/sudo-ai/zero123plus-v1.2

• TripoSR：VAST-AI-Research/TripoSR | ComfyUI-Flowty-TripoSR

  • 生成NeRF表示，并使用Marching Cubes将其转换为3D网格
  • 模型权重：https://huggingface.co/stabilityai/TripoSR/tree/main
  • tripoSR层叠扩散工作流由@Consumption提供

• Wonder3D：xxlong0/Wonder3D

  • 从单张图像生成空间一致的6视角图像及法线贴图
  • 模型权重：https://huggingface.co/flamehaze1115/wonder3d-v1.0/tree/main

  

• 大型多视角高斯模型：3DTopia/LGM

  • 在RTX3080显卡上，可在不到30秒内实现单张图像到3D高斯的转换，随后还可将3D高斯转换为网格
  • 模型权重：https://huggingface.co/ashawkey/LGM/tree/main

• 三平面高斯变换器：VAST-AI-Research/TriplaneGaussian

  • 在RTX3080显卡上，可在不到10秒内实现单张图像到3D高斯的转换，随后也可将3D高斯转换为网格
  • 模型权重：https://huggingface.co/VAST-AI/TriplaneGaussian/tree/main

• 预览3DGS和3D网格：在ComfyUI内部进行3D可视化：

  • 使用gsplat.js和three.js分别用于3DGS和3D网格的可视化
  • 可自定义背景，基于JS库：mdbassit/Coloris

• 堆栈轨道相机位姿：自动生成所有范围的相机位姿组合

  • 可用于对StableZero123（需先下载检查点）进行条件控制，在一个提示词中包含全范围的相机位姿

  • 也可用于生成轨道相机位姿，并直接输入到其他3D处理节点（如GaussianSplatting和BakeTextureToMesh）

  • 示例用法：

    

    
    

  • 坐标系统：

    • 方位角：在俯视图中，从角度0开始以-90度为步长旋转360度，得到(0, -90, -180/180, 90, 0)，此时相机顺时针旋转，反之亦然。
    • 仰角：相机水平向前时为0度，指向地面则为负角度，反之亦然。

• FlexiCubes：nv-tlabs/FlexiCubes

  • 输入多视角深度图及掩码（可选法线贴图）
  • 导出为3D网格
  • 使用指南：
    • voxel_grids_resolution：决定网格分辨率/质量
    • depth_min_distance 和 depth_max_distance：物体与相机之间的距离，渲染中距离相机比depth_min_distance（depth_max_distance）更近（更远）的部分将以纯白色（黑色）RGB值1, 1, 1（0, 0, 0）渲染
    • mask_loss_weight：控制重建后的3D网格轮廓
    • depth_loss_weight：控制重建后的3D网格形状，该损失还会影响表面的细节变形，因此结果取决于深度图的质量
    • normal_loss_weight：可选。用于细化表面的细节变形
    • sdf_regularizer_weight：有助于去除未受应用目标监督区域中的浮动体，例如仅使用图像监督时的内部面
    • remove_floaters_weight：若在平坦区域观察到伪影，可适当增加此权重
    • cube_stabilizer_weight：在优化单个形状时影响不大，但在某些情况下有助于稳定训练

• 即时NGP：nerfacc

  • 输入多视角图像
  • 使用Marching Cubes导出为3D网格

• 3D高斯泼溅

  • 改进的微分高斯光栅化
  • 更好的基于紧凑性的致密化方法来自Gsgen，
  • 支持从给定的3D网格初始化高斯点（可选）
  • 支持小批量优化
  • 输入多视角图像
  • 导出为标准的3DGS .ply格式

• 高斯泼溅轨道渲染器

  • 根据给定的3DGS文件和由堆栈轨道相机位姿节点生成的相机位姿，将3DGS渲染为图像序列或视频

• 网格轨道渲染器

  • 根据给定的网格文件和由堆栈轨道相机位姿节点生成的相机位姿，将3D网格渲染为图像序列或视频

• 多视角图像拟合网格

  • 使用Nvdiffrast将多视角图像烘焙到给定3D网格的UV纹理中，支持：
  • 导出为.obj、.ply、.glb

• 保存与加载3D文件

  • .obj、.ply、.glb用于3D网格
  • .ply用于3DGS

• 切换 3DGS 和 3D 网格的坐标轴

  • 由于不同的算法可能使用不同的坐标系，因此能够重新映射坐标轴对于在不同节点之间传递生成的结果至关重要。

• 可自定义的系统配置文件

  • 自定义客户端 IP 地址
  • 添加你的 Hugging Face 用户令牌

路线图：

• 集成 CharacterGen

• 改进 3DGS/Nerf 到 Mesh 的转换算法：

  • 寻找更好的方法将 3DGS 或点云转换为网格（也许可以重建法线贴图？）

• 增加并改进一些最佳的 MVS 算法（例如 2DGS 等）

• 增加从原始多视角图像中估计相机位姿的功能

开发

如何贡献

1. 分支该项目
2. 进行改进/添加新功能
3. 向 dev 分支 提交拉取请求

项目结构

• nodes.py:

包含所有 Comfy3D 节点的接口代码（即你在 ComfyUI 中实际可以看到并使用的节点），你可以在这里添加新的节点

• Gen_3D_Modules:

一个包含所有生成模型/系统的代码的文件夹（例如多视角扩散模型、3D 重建模型）。新的 3D 生成模块应在此处添加

• MVs_Algorithms:

一个包含所有多视图立体算法的代码的文件夹，即那些接收多视角图像并将其转换为 3D 表示（例如高斯分布、MLP 或网格）的算法（如 Gaussian Splatting、NeRF 和 FlexiCubes）。新的 MVS 算法应在此处添加

• web:

一个包含所有与浏览器 UI 相关的文件和代码（html、js、css）的文件夹（例如 HTML 布局、样式以及预览 3D 网格和高斯分布的核心逻辑）。新的 Web UI 应在此处添加

• webserver:

一个包含与浏览器通信代码的文件夹，即处理 Web 客户端请求的代码（例如，在特定 URL 路由请求时向客户端发送 3D 网格）。新的 Web 服务器相关功能应在此处添加

• Configs:

一个包含不同模块的不同配置文件的文件夹，新的配置应在此处添加，如果单个模块有多个配置，则使用子文件夹（例如 Unique3D、CRM）

• Checkpoints:

一个包含所有预训练模型以及 diffusers 所需的部分模型架构配置文件的文件夹。如果新的检查点可以通过 Load_Diffusers Pipeline 节点自动下载，则应将其添加到此文件夹中

• install.py:

主安装脚本，会根据你的运行环境自动下载并安装 Pre-builds。如果找不到相应的 Pre-builds，则会自动启动 build script，该脚本由 ComfyUI-Manager 在使用 pip 安装完 requirements.txt 中列出的依赖项后调用。
如果你尝试添加的新模块需要一些无法简单添加到 requirements.txt 和 build_config.remote_packages 中的额外软件包，则可以通过修改此脚本进行添加。

• _Pre_Builds:

一个包含构建所有所需依赖项的文件和代码的文件夹。如果你想预先构建一些额外的依赖项，请查看 _Pre_Builds/README.md 获取更多信息。

小贴士

• OpenGL（Three.js、Blender）的世界和相机坐标系：

      世界            相机        
    
      +y              上方  目标                                              
      |                |  /                                           
      |                | /                                           
      |______+x        |/______右侧                                      
      /                /         
     /                /          
    /                /           
  +z               正面           
  
  z 轴指向你，并且是从屏幕内指向外的
  仰角：在 (-90, 90) 之间，从 +y 到 +x 是 (-90, 0)
  方位角：在 (-180, 180) 之间，从 +z 到 +x 是 (0, 90)
  

• 如果遇到 OpenGL 错误（例如 [F glutil.cpp:338] eglInitialize() failed），则在相应节点上将 force_cuda_rasterize 设置为 true
• 如果安装后，你的 ComfyUI 在启动或运行时卡住，可以按照以下链接中的说明解决问题：在 GPU 上评估神经元模型时代码无限期挂起
• 修复 "nvcc fatal : 使用 'C:/Program Files (x86)/Microsoft Visual Studio/.../vcvars64.bat' 无法设置 Microsoft Visual Studio 的环境"

支持者

• MrNeRF

ComfyUI-3D-Pack 快速上手指南

ComfyUI-3D-Pack 是一个强大的节点套件，旨在让 ComfyUI 像生成图像和视频一样便捷地生成 3D 资产。它支持处理网格（Mesh）、UV 纹理等 3D 输入，并集成了 InstantMesh、CRM、TripoSR、Hunyuan3D 等前沿算法与模型。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Windows 10/11 或 Linux
• Python: 推荐 Python 3.12
• CUDA: 推荐 CUDA 12.4 (对应 torch 2.5.1+cu124)
• 显卡显存:
  • 基础模型运行建议至少 8GB VRAM。
  • 部分高级模型（如 Era3D）需要 16GB 或更高显存。
• 编译工具 (重要):
  • Windows: 必须安装 Visual Studio Build Tools (包含 C++ 生成工具)，否则 InstantNGP 和 3DGS 转 Mesh 等涉及即时编译 (JIT) 的节点将无法工作。
  • Linux: 必须安装 gcc 和 g++。

2. 安装步骤

方法一：通过 ComfyUI Manager 安装（推荐）

这是最简便的方式，适合大多数用户。

1. 启动 ComfyUI，点击右侧菜单中的 Manager 按钮。
2. 选择 Install Custom Nodes。
3. 搜索 ComfyUI-3D-Pack。
4. 点击 Install 进行安装。
5. 安装完成后，重启 ComfyUI。
   • 注：首次运行时，插件会自动检测环境并尝试下载预构建包或编译缺失依赖。

方法二：手动安装

如果您无法使用 Manager 或需要特定配置，请按以下步骤操作：

1. 进入 ComfyUI 的自定义节点目录：

   cd Your_ComfyUI_Root_Directory/ComfyUI/custom_nodes/
   

2. 克隆仓库：

   git clone https://github.com/MrForExample/ComfyUI-3D-Pack.git
   cd ComfyUI-3D-Pack
   

3. 安装依赖并运行初始化脚本（请根据实际 Python 路径调整命令）：

   # 安装 requirements.txt 中的依赖
   Your_ComfyUI_Root_Directory/python_embeded/python.exe -s -m pip install -r requirements.txt
   
   # 运行安装脚本（自动下载预构建包或编译）
   Your_ComfyUI_Root_Directory/python_embeded/python.exe install.py
   

   如果是标准 Python 环境，请将 python_embeded/python.exe 替换为 python 或 python3。

4. 模型下载提示：

   • 插件通常会自动下载模型到 Checkpoints 目录。
   • 若自动下载失败，可手动从 HuggingFace 下载模型权重，放入对应的 Checkpoints 子文件夹中。注意：不要覆盖现有的 .json 配置文件。
   • 对于 StableFast3D 模型，需先同意 Stability-AI 的使用条款，或在 Configs/system.conf 中配置您的 HuggingFace Token。

3. 基本使用

安装完成后，您可以通过加载官方示例工作流快速开始。

步骤 1：准备示例素材

在运行示例工作流前，必须将示例输入文件复制到 ComfyUI 的输入目录：

1. 找到插件目录下的 example_workflows/_Example_Inputs_Files/ 文件夹。
2. 将其中的所有内容复制到您 ComfyUI 根目录下的 ComfyUI/input/ 文件夹中。

步骤 2：加载工作流

1. 启动 ComfyUI。
2. 点击菜单 Load，导航至插件目录下的 example_workflows/。
3. 选择一个适合您需求的工作流文件（例如 .json 格式）。

常用模型与工作流推荐

• 单图生成 3D (通用):

  • Hunyuan3D_2.1: 腾讯混元最新模型，支持“形状生成” + “纹理生成”两阶段流程，效果出色。
    • 工作流路径：example_workflows/Hunyuan3D_2_1/Hunyuan2.1-Full.json
  • TripoSG: 支持从单张参考图或草图生成 3D 网格。
  • TRELLIS: 微软出品，单图生成带 RGB 纹理的高质量 3D 网格。

• 角色生成专用:

  • CharacterGen: 专为角色设计，支持任意姿势的单视图生成。可结合 Unique3D 工作流获得更好效果。
    • 工作流路径：example_workflows/CharacterGen/CharacterGen_to_Unique3D.json

• 多视图与场景:

  • PartCrafter: 支持单物体部件分割或整个场景的多物体生成。
  • MV-Adapter: 支持从单图+网格或文本+网格生成多视图图像及纹理。

运行生成

1. 加载工作流后，检查左侧输入节点（如 Load Image），确认图片路径正确。
2. 点击右侧 Queue Prompt 按钮开始生成。
3. 生成的 3D 模型（.obj, .glb 等）通常会输出到 ComfyUI/output/ 目录，或在预览节点中直接查看。

提示：首次运行某些模型时可能需要较长时间下载权重或编译组件，请耐心等待。如遇节点缺失报错，请在 ComfyUI Manager 中点击 "Install Missing Custom Nodes" 自动补全依赖。