StableGen：在Blender中实现AI驱动的3D生成与贴图✨

从图像和提示词创建3D资产，随后进行贴图与优化——全程在Blender内完成。

StableGen是一款开源的Blender插件，将生成式AI引入您的3D工作流。通过TRELLIS.2，您可以生成由单张图像或文本提示词驱动的完整贴图3D网格；然后利用SDXL、FLUX.1-dev或Qwen Image Edit，并借助灵活的ComfyUI后端，对这些模型或任何现有模型进行贴图与优化。

---

目录

• 🌟 核心功能
• 🚀 展示图库
• 🛠️ 工作原理
• 💻 系统要求
• ⚙️ 安装
• 🚀 快速入门指南
  • 为现有模型贴图
  • 使用TRELLIS.2生成3D模型
• 📖 使用说明与参数概述
• 📁 输出目录结构
• 🤔 故障排除
• 🤝 贡献
• 📜 许可证
• 🙏 致谢
• 💡 计划中的功能列表
• 📧 联系方式

---

🌟 核心功能

StableGen 将 AI 驱动的 3D 生成与贴图功能直接融入 Blender：

• 🧊 TRELLIS.2：图像与提示词转 3D：
  • 使用微软的 TRELLIS.2（40亿参数模型），根据单张参考图像或文本提示生成完全贴图的 3D 网格。
  • 多种分辨率模式： 512、1024、1024 Cascade（推荐）以及 1536 Cascade，以获得最高级别的几何细节。
  • 灵活的贴图流程： 可使用 TRELLIS.2 原生的 PBR 贴图，也可自动将生成的网格用 SDXL、FLUX.1-dev 或 Qwen Image Edit 进行贴图，以获得更高质量的扩散贴图。
  • 预览图库： 生成多个不同种子的候选图像，在确定最终 3D 生成之前挑选最佳方案。
  • 智能网格处理： 自动修复网格损坏，支持可配置的简化/重拓扑、导入缩放以及工作室灯光设置。
  • 低显存优化：磁盘交换、可配置的注意力后端。
  • 由 ComfyUI-TRELLIS2 提供支持（可通过 installer.py 安装）。
• 🌍 场景级多网格贴图：
  • 不再局限于一次只贴一张网格！StableGen 专为从您定义的摄像机视角同时为场景中的所有网格对象应用贴图而设计。您也可以选择仅贴图选定的对象。
  • 在一次生成过程中即可实现整个环境或资产集合的一致外观。
  • 非常适合概念艺术创作、复杂场景的外观开发以及批量贴图资产库。
• 🎨 多视角一致性：
  • 顺序模式： 按照每个网格的视角逐个生成贴图，利用修复填充和可见性遮罩技术，确保复杂表面上的高度一致性。
  • 网格模式： 同时处理所有网格的多个视角，以加快预览速度。包含可选的细化步骤。
  • 精巧的加权混合算法确保各视角之间的平滑过渡。
• 📷 高级摄像机布局：
  • 7 种布局策略： 轨道环形、扇形弧线、半球形、PCA 轴向、法线加权 K-means、贪婪遮挡覆盖率，以及交互式可见性加权布局。
  • 每台摄像机的最佳长宽比——每台摄像机都会根据网格轮廓计算出专属分辨率，避免因信箱格式浪费像素。
  • 无限数量的摄像机——不再受 8 台摄像机的限制。
  • 摄像机生成顺序——通过拖放排序列表，结合 6 种预设策略来控制顺序模式下的处理顺序。
  • 支持摄像机克隆、镜像以及浮动视口提示标签。
• 🎯 局部编辑模式：
  • 将摄像机对准特定区域进行修改——新贴图会基于角度和晕影效果与原有贴图无缝融合。
  • 分别控制角度渐变和轮廓边缘的羽化效果，实现精准融合。
  • 兼容所有架构（SDXL、Flux、Qwen Image Edit）。
• 📐 借助 ControlNet 实现精确的几何控制：
  • 同时使用多个 ControlNet 单元（深度、Canny、法线），确保生成的贴图忠实于您的模型几何形状。
  • 可精细调整每个 ControlNet 单元的强度及生效起止步数。
  • 支持自定义 ControlNet 模型映射。
• 🖌️ 借助 IPAdapter 实现强大的风格引导：
  • 使用外部参考图像，通过 IPAdapter 引导贴图的风格、氛围和内容。
  • 在多视角生成模式中，即使不使用参考图像，IPAdapter 也能提升一致性。
  • 可控制 IPAdapter 的强度、权重类型及生效步数。
• ⚙️ 灵活的 ComfyUI 后端：
  • 可连接您现有的 ComfyUI 安装，让您在实验性的 FLUX.1-dev 支持之外，继续使用偏好的 SDXL 检查点、自定义 LoRA 以及全新的 Qwen Image Edit 工作流。
  • 将繁重的计算任务卸载到 ComfyUI 服务器上，使 Blender 保持较高的响应速度。
• ✨ 高级修复填充与细化：
  • 细化模式（Img2Img）： 利用图像到图像处理方式，重新塑造风格、增强细节或将细节添加到现有贴图上（无论是 StableGen 生成的还是其他来源）。
  • 局部编辑模式： 选择性地修改特定区域，同时保留其余部分，并提供独立的角度和晕影羽化控制。
  • UV 修复模式： 根据周围贴图上下文，智能填补模型 UV 图上未贴图的区域。
  • 颜色匹配： 在混合前，使用多种算法（MKL、Reinhard、直方图、MVGD）将每个生成视角的颜色与当前贴图进行匹配。
• 🛠️ 集成式工作流程工具：
  • 摄像机设置： 快速添加并排列多台摄像机，提供 7 种布局策略、每台摄像机的专属长宽比、交互式遮挡预览以及可定制的生成顺序。
  • 视图专属提示词： 为每个摄像机视角分配独特的文本提示，以实现针对性的细节控制。
  • 贴图烘焙： 将复杂的程序化 StableGen 材质转换为标准的 UV 图像贴图。“为细化而展平”选项允许您烘焙后继续编辑。
  • 调试工具： 无需运行 AI 生成，即可可视化投影覆盖范围、UV 对齐情况和权重混合效果。
  • HDRI 设置、修改器应用、曲线转换、GIF/MP4 导出与重投影。
• 📋 预设系统：
  • 通过内置预设快速上手常见场景（如“默认”、“角色”、“快速草稿”）。
  • 保存并管理您自己的自定义参数配置，以实现可重复的工作流程。

---

🚀 展示图库

看看 StableGen 能做什么！

_{提示：刷新页面可同步所有 GIF 动画。}

---

展示 1：文本转 3D（SDXL）

完全由文本提示生成的资产，使用基于 SDXL 的贴图处理的 TRELLIS.2 流程。

龙	巫师	小屋
望远镜	机器人	赛博忍者

使用的提示词

1. 龙： "奇幻龙"
2. 巫师： "巫师角色，精致刺绣的紫金长袍，尖顶帽，镶嵌发光水晶的木制法杖，系有小袋的皮带，奇幻角色概念艺术，4k"
3. 小屋： "房子，小房子，温馨舒适，木质，小屋"
4. 望远镜： "古董黄铜望远镜，表面有因使用而留下的暗淡包浆与光亮痕迹，皮革包裹的手柄，可伸缩的镜筒，桃花心木三脚架，产品摄影，4k"
5. 机器人： "巨型机器人，机甲，赛博朋克风格，科幻，白色机身，细节丰富，带有霓虹灯点缀"
6. 赛博忍者： "全身角色，中立姿势，赛博忍者，未来刺客，哑光黑色碳纤维隐形战衣，六边形编织图案，无面头盔，红色荧光面罩缝隙，金属银色肩甲，赛博朋克美学，高对比度材质，虚幻引擎5渲染"

展示 2：文本转 3D（Qwen）

通过 TRELLIS.2 结合 Qwen 图像编辑贴图技术实现的文本转 3D——非常适合风格化物体和清晰细腻的细节。

桶	宝箱	箱子
方尖碑	机器人	树桩

使用的提示词

1. 桶： "一个粗犷、风格化的木桶，由厚重、超大号的铁箍紧紧束缚。木头上刻有深邃而夸张的手工凹槽"
2. 宝箱： "一个细节极其丰富的木制宝箱，被沉重的深色铁链束缚着。箱子微微打开，露出里面堆积如山的金色金币。木头陈旧且开裂，铁链上还布满了橙色锈斑。"
3. 箱子： "一个黄色的工业级危险品运输箱。侧面印有一块醒目的警告标签，用粗黑体字写着‘危险：生物危害’。箱子正面装有一个数字密码锁，左侧则绑着两个红色氧气罐。"
4. 方尖碑： "一座古老、巨大的石质方尖碑，表面布满了发着绿光的符文雕刻。灰色的石质因年久失修而深深开裂，上面还覆盖着厚厚的绿色绒毛状苔藓。"
5. 机器人： "巨型机器人，机甲，赛博朋克风格，科幻，白色机身，细节繁复，点缀着霓虹灯光"
6. 树桩： "一棵充满神秘感的古老扭曲树桩，根系盘根错节地裸露在外。树桩顶部簇生着半透明、泛着蓝光的生物发光蘑菇，以及纤细柔美的蕨类叶片。奇幻RPG场景资源，手绘纹理风格融合写实效果，细节极为丰富。"

展示 3：PBR 对比

PBR 材质贴图（粗糙度、金属度、法线）可以通过 Marigold 分解生成。每对图片展示了同一物体在无 PBR 材质和有 PBR 材质情况下的对比效果。

房子	房子 (PBR)	巫师	巫师 (PBR)
宝箱	宝箱 (PBR)	方尖碑	方尖碑 (PBR)
月球栖息地	月球栖息地 (PBR)	拾荒者	拾荒者 (PBR)
萨满	萨满 (PBR)	赛博朋克女战士	赛博朋克女战士 (PBR)
木箱	木箱 (PBR)	树桩	树桩 (PBR)

使用的提示词

1. 房子（Qwen）： "房子，小房子，舒适，木质，小屋"
2. 巫师（SDXL）： "巫师角色，复杂刺绣的紫色和金色长袍，尖顶帽，带有发光水晶的木制法杖，系着小袋的皮带，奇幻角色概念艺术，4k"
3. 宝箱（Qwen）： "一个细节极其丰富的木制宝箱，用厚重的深色铁条加固。箱子微微打开，露出里面堆叠的发光金币。木材陈旧且开裂，铁条上布满了橙色锈斑。"
4. 方尖碑（Qwen）： "一座古老的单体石制方尖碑，表面布满发光的绿色符文雕刻。灰色的石质因年久失修而深深开裂，还覆盖着厚厚的绿色绒毛状苔藓。"
5. 月球栖息地（SDXL）： "未来感十足的月球栖息地模块，圆顶圆柱形底座建筑，洁白如新的复合材料面板，高光泽反射，包裹着金箔的管道，圆形金属气闸门，外侧泛着蓝光的探照灯，科幻基地建筑，干净的 PBR 质地，硬表面建模，8k"
6. 拾荒者（SDXL）： "全身角色，A 字站姿，后末日时代的拾荒者，油渍斑驳的橄榄绿军装夹克，破烂的衣服，生锈的街牌护甲，脏兮兮的皮带，划痕累累的焊接面罩，荒原生存者，垃圾风质感，严重风化，辐射风格的角色资产"
7. 萨满（SDXL）： "全身角色，A 字站姿，部落萨满，粗布棕色羊毛，厚重白色兽皮，雕刻的白色骨质面具，闪耀着紫色光芒的魔法符文，赤裸的双臂，奇幻 RPG 角色职业，有机质感，高度细节化的位移贴图，ZBrush 雕塑风格"
8. 赛博朋克女战士（Qwen）： "一位站立于中立姿势的未来感十足的赛博朋克女佣兵。她的左臂由黑色金属和蓝色发光电线构成的机械假肢，身穿合成材料制成的战术夹克，衣领处点缀着发光的 LED 灯带，脚踏未来感十足的运动鞋。"
9. 木箱（Qwen）： "一个黄色的工业级危险品运输箱。侧面有一块醒目的警告标签，用粗黑字写着‘危险：生物危害’。箱子正面装有数字密码锁，左侧绑着两个红色氧气罐。"
10. 树桩（Qwen）： "一棵神秘而古老的扭曲树桩，根部裸露并盘旋交错。树桩顶端长出一簇半透明、发出蓝光的生物荧光蘑菇，以及纤细的蕨类叶片。奇幻 RPG 资产，手绘纹理风格与写实相结合，细节极为丰富。"

展示 4：PBR 画廊

一组启用了 PBR 材质的资产，展示了在不同光照条件下逼真的表面反应。

金锅	星盘	树桩
兔子	木箱	方尖碑（Qwen）

使用的提示词

1. 金锅： "金锅"
2. 星盘： "一个细节极其丰富的古董蒸汽朋克星盘，静置于粗糙的木制台座之上。星盘由闪亮的黄铜环、暗淡的铜质齿轮以及中央的多面玻璃水晶组成。影棚灯光，写实风格，8k 分辨率，精密的机械细节，独立于纯色背景之上。"
3. 树桩： "一棵神秘而古老的扭曲树桩，根部裸露并盘旋交错。树桩顶端长出一簇半透明、发出蓝光的生物荧光蘑菇，以及纤细的蕨类叶片。奇幻 RPG 资产，手绘纹理风格与写实相结合，细节极为丰富。"
4. 兔子： "一只白兔"
5. 木箱： "一个黄色的工业级危险品运输箱。侧面有一块醒目的警告标签，上面用粗黑字写着‘危险：生物危害’。箱子正面装有数字密码锁，左侧绑着两个红色氧气罐。"
6. 方尖碑（Qwen）： "一座古老的单体石制方尖碑，表面布满发光的绿色符文雕刻。灰色的石质因年久失修而深深开裂，还覆盖着厚厚的绿色绒毛状苔藓。"

---

展示 5：头部风格化（仅贴图）

使用提示词和 IPAdapter 图像参考的风格指导，为现有模型添加贴图。

3D 模型来源：“Brown” by ucupumar - 可在以下链接获取：BlendSwap (Blend #15262)

未贴图模型	生成结果	生成结果	生成结果（使用参考图像）
基础未贴图模型	红发	赛博朋克	艺术风格

使用的提示词

1. 红发：“anime girl head, red hair”
2. 赛博朋克：“girl head, brown hair, cyberpunk style, realistic”
3. 艺术风格：“anime girl head, artistic style”（风格由下方所示的 IPAdapter 参考图像引导）

参考：文森特·梵高《星夜》（用于引导“艺术风格”变体）

展示 6：汽车贴图（仅贴图）

使用不同的提示词为汽车模型添加贴图，以实现多种视觉风格。

3D 模型来源：“Pontiac GTO 67” by thecali - 可在以下链接获取：BlendSwap (Blend #13575)

未贴图模型	生成结果	生成结果	生成结果
基础未贴图模型	绿色	蒸汽朋克	隐形黑色

使用的提示词

1. 绿色：“green car”
2. 蒸汽朋克：“steampunk style car”
3. 隐形黑色：“stealth black car”

展示 7：场景贴图（仅贴图）

为由多个网格对象组成的复杂场景添加贴图。

3D 模型来源：“Subway Station Entrance” by argonius - 可在以下链接获取：BlendSwap (Blend #19305)

未贴图场景	生成结果	生成结果	生成结果
基础未贴图场景	地铁站	奇幻宫殿	赛博朋克

使用的提示词

1. 地铁站：“subway station”
2. 奇幻宫殿：“an overgrown fantasy palace interior, gold elements”
3. 赛博朋克：“subway station, cyberpunk style, neon lit”

---

🛠️ 工作原理（简要介绍）

StableGen 是一个直观的 Blender 插件界面，负责与 ComfyUI 后端进行通信。

1. 在 StableGen 面板中设置场景和参数。
2. StableGen 准备必要的数据（例如来自摄像机视图的 ControlNet 输入）。
3. 构建工作流程并将其发送到您的 ComfyUI 服务器。
4. ComfyUI 使用您选择的扩散模型处理请求。
5. 生成的图像会返回到 Blender。
6. StableGen 使用复杂的投影和混合技术，将这些图像作为贴图应用到您的模型上。

---

💻 系统要求

• Blender：版本 4.2–4.5（OSL 投影）或 Blender 5.1+（通过原生 Raycast 节点实现 GPU 加速投影）。不支持 Blender 5.0（因为 OSL 存在问题且原生 Raycast 尚未可用）。
• 操作系统：Windows 10/11、Linux 或 macOS（Apple Silicon）。
• GPU：建议使用带有 CUDA 的 NVIDIA 显卡来运行 ComfyUI。更多详细信息请参阅 ComfyUI 的 GitHub 页面：https://github.com/comfyanonymous/ComfyUI。
  • 至少需要 8 GB 显存才能以可接受的速度运行 SDXL；运行 FLUX.1-dev 或 Qwen-Image-Edit 流程时则需 16 GB 或以上显存。
• ComfyUI：已安装并正常运行的 ComfyUI。StableGen 将其用作后端。
• Python：版本 3.x（通常随 Blender 自带，但 installer.py 脚本需要 Python 3）。
• Git：installer.py 脚本需要 Git。
• 磁盘空间：ComfyUI、AI 模型（10 GB 至 50 GB 以上）以及生成的贴图都需要大量可用空间。

---

⚙️ 安装步骤

安装 StableGen 包括安装 ComfyUI，然后使用我们的安装脚本将 StableGen 的依赖项安装到 ComfyUI 中，最后在 Blender 中安装 StableGen 插件。

请按照以下分步说明安装 StableGen。

如果您更喜欢观看视频，Polynox 提供了一个简洁的安装与基本使用教程：
StableGen 安装及基本使用视频教程

第一步：安装 ComfyUI（如果尚未安装）

StableGen 依赖于一个正常工作的 ComfyUI 安装作为其后端。这可以在另一台机器上完成，如果需要的话。

如果您希望使用另一台机器作为后端，请在该机器上执行步骤 1 和 2。

• 如果您尚未安装 ComfyUI，请遵循 官方 ComfyUI 安装指南：https://github.com/comfyanonymous/ComfyUI#installing。
  • 请将 ComfyUI 安装在一个专用目录中，我们将其称为 <YourComfyUIDirectory>。
  • 在继续下一步之前，请确保 ComfyUI 能够正常运行并工作正常。

步骤 2：安装依赖项（自定义节点与 AI 模型）——自动化方式（推荐）

installer.py 脚本（位于本仓库中）可自动下载并将所需的 ComfyUI 自定义节点和核心 AI 模型放置到您的 <YourComfyUIDirectory> 目录中。

安装脚本的先决条件：

• Python 3。
• 已安装 Git，并且 Git 可在系统的 PATH 中访问。
• 您的 ComfyUI 安装路径（<YourComfyUIDirectory>）。
• 脚本所需的 Python 包：requests 和 tqdm。请通过 pip 安装：

  pip install requests tqdm
  

运行安装程序：

1. 下载/找到安装程序： 从本 GitHub 仓库获取 installer.py。
2. 执行脚本：
   • 打开您系统的终端或命令提示符。
   • 导航到包含 installer.py 的目录。
   • 运行脚本：

     python installer.py <YourComfyUIDirectory>
     

     将 <YourComfyUIDirectory> 替换为实际路径。如果省略，脚本会提示您输入。
3. 按照屏幕上的指示操作：
   • 脚本将显示一个安装包菜单。选择符合您需求的功能选项。
   • 脚本会下载文件并将其放置到 <YourComfyUIDirectory> 的正确子目录中。

安装包概览：

序号	包名	功能描述	大小
1	Minimal Core	基础 SDXL 纹理化（需自行提供检查点 + ControlNets）	~7.3 GB
2	Core + Preset Essentials	所有内置预设即插即用	~9.8 GB
3	推荐 全套 SDXL 设置	SDXL 纹理化 + PBR 分解（不含检查点）	~19.3 GB
4	Complete SDXL + RealVisXL	第 3 项的所有功能，外加一个即用检查点	~26.3 GB
5	Qwen Core	Qwen Image Edit 纹理架构	~20.3 GB
6	Qwen + Lightning LoRAs	Qwen 配合额外的 Lightning LoRAs	~22.6 GB
7	Qwen Nunchaku	Qwen 使用 Int4 量化 Nunchaku 模型（降低显存占用）	~33.0 GB
8	TRELLIS.2	图像/文本转 3D 网格生成（首次使用时约 5 GB 安装 + 约 15.4 GB 模型）	~20.4 GB
9	Marigold IID	PBR 分解节点（首次使用时自动下载模型）	~0.01 GB
10	StableDelight	无镜面反射的 PBR 反照率（包含模型下载）	~3.3 GB
11	FLUX.2 Klein (实验性)	Klein 纹理架构（需约 13 GB 显存）	~12.4 GB

常见配置：

• 完整 3D 资产生成（SDXL）： 选项 3 + 8（或选项 4 + 8，含检查点）
• 完整 3D 资产生成（Qwen）： 选项 6 + 8
• 仅纹理化（SDXL）： 选项 3（或 4）
• 仅纹理化（Qwen）： 选项 5（或 6/7）
• 为任何设置添加 PBR： 选项 9 + 10（已包含在选项 3 和 4 中）

注意： TRELLIS.2 和 Marigold IID 会在首次使用时通过 HuggingFace 自动下载额外模型。上述大小已包含这些首次使用的下载内容。首次运行可能需要更长时间。

4. 重启 ComfyUI： 如果 ComfyUI 正在运行，请重启以加载新的自定义节点。

（如需手动安装依赖项，包括 FLUX.1-dev 和 Qwen Image Edit 的配置，请参阅 docs/MANUAL_INSTALLATION.md。）

步骤 3：安装 StableGen Blender 插件

1. 访问本仓库的 发布页面。
2. 下载最新的 StableGen.zip 文件。
3. 在 Blender 中，前往 编辑 > 首选项 > 插件 > 安装...。
4. 浏览并选择下载的 StableGen.zip 文件。
5. 启用“StableGen”插件（搜索“StableGen”并勾选）。

步骤 4：在 Blender 中配置 StableGen 插件

1. 在 Blender 中，前往 编辑 > 首选项 > 插件。
2. 找到“StableGen”，展开其设置。
3. 设置以下路径：
   • 输出目录： 选择一个文件夹，用于保存 StableGen 生成的图像。
   • 服务器地址： 确保此地址与您的 ComfyUI 服务器匹配（默认为 127.0.0.1:8188）。
   • 如果使用自定义命名的 ControlNet 模型，请检查 ControlNet 映射。
4. 如果尚未启用，请在 Blender 中启用在线访问。从 Blender 的顶部栏选择 编辑 -> 首选项，然后导航到 系统 -> 网络，勾选 启用在线访问。尽管 StableGen 不需要互联网连接，但此举是为了遵守 Blender 插件的相关规定，因为插件仍会在本地进行网络调用。

---

🚀 快速入门指南

为现有模型添加纹理

以下是使用 StableGen 生成第一张纹理的方法：

1. 启动 ComfyUI 服务器： 确保其已在后台运行。
2. 打开 Blender 并准备场景：
   • 准备好一个网格对象（例如默认的立方体）。
   • 确保 StableGen 插件已启用并正确配置（参见步骤 4）。
3. 访问 StableGen 面板： 在 3D 视口按下 N 键，进入“StableGen”选项卡。
4. 添加相机（建议用于多视角）：
   • 选择您的对象。
   • 在 StableGen 面板中，点击“添加相机”。选择“对象”作为中心类型。如有需要可交互调整，然后确认。
5. 设置基本参数：
   • 提示词： 输入描述（例如“长满苔藓的古老石墙”）。
   • 架构： 根据您设置的工作流程，选择扩散家族（SDXL、Flux 1 或 Qwen Image Edit）。
   • 检查点： 选择适合所选架构的检查点或 GGUF 文件（例如 sdxl_base_1.0 或 Qwen-Image-Edit-2509-Q3_K_M.gguf）。
   • 预设： 选择一个预设并应用。默认 或 角色 是不错的起点。
6. 开始生成！ 点击主“生成”按钮。
7. 观察结果： 查看面板和 ComfyUI 控制台中的进度。您的对象应会更新为新纹理！输出文件将保存在您指定的“输出目录”中。
   • 默认情况下，生成的纹理仅在渲染视图着色模式下可见（Cycles 渲染引擎）。

使用 TRELLIS.2 生成 3D 模型

按照以下步骤，您可以使用 TRELLIS.2 流水线根据文本提示或参考图像生成带有完整纹理的 3D 网格：

1. 先决条件： 确保已安装 TRELLIS.2 的依赖项（参见安装 - 第 2 步），并且您的硬件满足系统要求。
2. 选择预设： 选择并应用带有 (MESH + TEXTURE) 标签的预设之一：
   • SDXL - 最适合创意驱动的提示工作流。
   • Qwen Image Edit - 非常适合风格化生成、可读文本和特定细节。尤其适用于从图像到 3D 模型的工作流。
   • 将鼠标悬停在 Blender 中的任何预设上，即可查看其详细功能说明。
   • 或者，如果您只需要生成的网格而不需要自动纹理，则可以使用 TRELLIS.2 (MESH ONLY) 预设。
3. 选择输入模式： 将 Generate from 字段设置为 Prompt 以进行文本到 3D 的转换，或设置为 Image 以使用参考图像。
4. 提供输入： 输入描述性提示或加载参考图像。
5. (可选) 启用 PBR： 在 高级参数 → 输出与材质设置 下开启 PBR 生成，以生成基于物理的材质贴图（粗糙度、金属度、法线）。
6. 生成： 单击主 Generate 按钮，等待处理完成。
7. (可选) 优化结果： 调整每个摄像机的提示并重新生成特定视角，或者切换到 Local Edit 模式（有相应预设可用）进行针对性调整。

导出至游戏引擎：

8. 烘焙纹理： 您很可能需要切换 UV 展开方式（在 Bake Textures 操作器中）——大多数情况下，Smart UV Project 模式效果良好。
9. 导出： 使用内置的 Export for Game Engine 导出工具，或从 Blender 手动导出。

---

📖 使用与参数概览

StableGen 提供了一个全面的界面，用于 AI 驱动的 3D 资产生成和纹理处理，从网格创建到最终的 PBR 导出。以下是 StableGen 面板中主要部分和工具的概述：

主要操作与场景设置

这些是主要的操作按钮和初始设置工具，通常位于 StableGen 面板的顶部附近：

• 生成/取消生成（主按钮）： 根据当前模式，开始 3D 网格生成（TRELLIS.2 流水线）或现有网格对象的纹理生成。处理过程中，按钮会变为“取消生成”。生成期间，此按钮下方会显示总体、阶段和每步进度条。
• Bake Textures： 将动态的多投影材质转换为每个对象的一张标准 UV 映射图像纹理。如果启用了 PBR 分解，还会烘焙 PBR 贴图（反照率、粗糙度、金属度、法线、高度、环境光遮蔽、自发光）。默认使用 Smart UV Project 展开方式。这是导出到游戏引擎所必需的步骤。
• Add Cameras： 使用 7 种放置策略之一设置多个视点——从简单的轨道环到基于几何感知、针对遮挡优化且具有各摄像机不同宽高比的放置方式。使用交互式预览微调位置，然后再确认。
• Collect Camera Prompts： 循环遍历场景中的所有摄像机，允许您为每个视点输入特定的描述性文本提示（例如，“正面视图”、“面部特写”）。如果在 Viewpoint Blending Settings 中启用了 Use camera prompts，则这些每个摄像机的提示将与主提示结合使用。

预设管理

• 该系统位于 UI 的显眼位置，允许您：
  • 选择预设： 从按 4 大架构分组的 30 多个内置预设中选择（SDXL/FLUX.1、Qwen Image Edit、FLUX.2 Klein、TRELLIS.2 Pipeline），或选择 Custom 以使用当前设置。
  • 预设差异预览： 当您将鼠标悬停或选择某个预设时，StableGen 会显示哪些参数与您当前设置不同，以及它们将被更改为哪些值。
  • 应用预设： 如果您修改了某个默认预设，此按钮会将其恢复为原始值。
  • 保存预设/删除预设： 将当前配置保存为命名预设，或删除自定义预设。ControlNet 和 LoRA 包含切换开关，可让您选择要保存的内容。

主要参数

这些是您定义生成过程的主要控制选项：

• Prompt： 您希望生成的纹理（或 3D 资产）的主要文本描述。
• Checkpoint： 选择基础 SDXL 检查点（适用于 SDXL/FLUX 架构）。
• Architecture： 在 SDXL、Flux 1、Qwen Image Edit 和 FLUX.2 Klein（实验性）模型架构之间进行选择。对于 3D 网格生成，请使用 TRELLIS.2 流水线预设。
• Generation Mode： 定义纹理生成的核心策略：
  • Generate Separately：每个视点独立生成。
  • Generate Sequentially：视点逐个生成，利用前一视点的修复来保持一致性。
  • Generate Using Grid：将所有视点组合成一个网格，进行一次生成，并可选进行细化步骤。
  • Refine/Restyle Texture (Img2Img)：将当前纹理作为输入，进行图像到图像的处理。
  • Local Edit：通过将摄像机对准特定区域来有选择地修改，新纹理会以羽化边缘的方式与原有纹理融合。
  • UV Inpaint Missing Areas：通过 inpainting 填充 UV 图上未纹理化的区域。
• Target Objects： 选择是为所有可见的网格对象还是仅选定的对象添加纹理。

高级参数（可折叠部分）

点击每个标题旁边的箭头以展开并访问详细设置：

• 核心生成设置： 控制扩散的基本参数，如种子、步数、CFG、负面提示词、采样器、调度器和Clip跳过。
• LoRA管理： 添加并配置LoRA（低秩适应），以获得额外的风格或内容指导。您可以为每个LoRA设置模型强度和CLIP强度。
• 视点混合设置： 管理来自不同摄像视角的纹理如何组合，包括特定于摄像机的提示词、丢弃角度、混合权重指数、摄像机生成顺序以及生成后的指数重置。
• 输出与材质设置： 定义回退颜色、材质属性（BSDF）、自动分辨率缩放，以及在生成过程中烘焙纹理的选项，这使得能够使用超过8个视角进行生成。
• 图像引导（IPAdapter与ControlNet）： 配置IPAdapter以使用外部图像进行风格迁移，并设置多个ControlNet单元（深度、Canny等），以实现精确的结构控制。
• 修复选项： 细化顺序和UV修复模式下的遮罩与混合（例如，差异扩散、遮罩模糊/扩展）。
• 生成模式特有参数： 仅适用于所选生成模式的参数，例如网格模式的细化选项，或顺序/分离/细化模式下的IPAdapter一致性设置。
• PBR分解： 在贴图完成后启用PBR材质提取。可以切换各个贴图类型（反照率、粗糙度、金属度、法线、高度、环境光遮蔽、自发光），选择反照率来源，并配置平铺超分辨率。仅当服务器上存在所需的Marigold/StableDelight节点时才会显示。
• TRELLIS.2设置： 配置3D网格生成——分辨率模式、简化、重新网格化、导入比例、着色模式、纹理模式（原生/SDXL/FLUX/Qwen/Klein）、预览图库种子数量，以及用于贴图的摄像机放置策略。

集成工作流工具（底部区域）

一系列实用工具，进一步支持您的工作流程：

• 场景队列： 将多个资产加入队列，进行无人值守的批量处理。可添加带有提示词和标签的项目，重新排序，在失败时重试。支持贴图和TRELLIS.2流程，并可在每个项目后选择性地自动导出GIF。
• 切换材质： 对于具有多个材质槽位的选定对象，可快速将特定索引处的材质设为当前激活材质。
• 添加HDRI光源： 提示您选择一个HDRI图像文件，并将其设置为世界光照，为您的场景提供逼真的照明效果。
• 应用所有修改器： 遍历场景中的所有网格物体，应用其修改器堆栈，并将几何体实例转换为实际网格数据。有助于为贴图准备模型。
• 将曲线转换为网格： 将任何选定的曲线对象转换为网格对象，这是StableGen对其进行贴图前的必要步骤。
• 导出环绕动画GIF/MP4： 创建活动对象的动画GIF和MP4，摄像机围绕该对象旋转。可配置持续时间、帧率、分辨率、渲染引擎（Workbench/Eevee/Cycles）以及HDRI环境模式。
• 重投影图像： 使用最新的视点混合设置重新应用之前生成的纹理。允许在不完全重新生成的情况下调整纹理混合。
• 镜像重投影： 沿某一轴镜像上次投影的摄像机和图像，然后重新投影。对于对称对象非常有用。

请尝试这些设置和工具，以实现丰富多样的效果和控制！请记住，最佳参数会因模型、主题和期望的艺术风格而有很大差异。

---

📁 输出目录结构

StableGen会根据您插件偏好中指定的输出目录来组织生成的文件。每次生成都会创建一个新的带时间戳的文件夹，帮助您跟踪不同的迭代版本。每个会话（修订版）的结构如下：

• <输出目录>/
  • <场景名称>/ (基于您的.blend文件名，或未保存场景的名称）
    • <YYYY-MM-DDTHH-MM-SS>/ (生成开始的时间戳——这是主要的修订目录）
      • generated/ (各摄像机/视角生成的主要输出纹理，尚未应用或烘焙）
      • controlnet/ (中间的ControlNet输入图像）
        • depth/ (深度通道渲染）
        • canny/ (使用Canny边缘检测器处理后的渲染）
        • normal/ (法线通道渲染）
      • baked/ (使用独立的烘焙纹理工具烘焙到UV贴图上的纹理，以及使用导出至游戏引擎工具导出的.glb文件）
      • generated_baked/ (如果启用了“生成时烘焙纹理”，则在此过程中烘焙的纹理）
      • inpaint/ (与修复过程相关的文件，例如针对顺序模式的文件）
        • render/ (用作修复上下文的先前状态渲染）
        • visibility/ (修复过程中使用的可见性遮罩）
      • uv_inpaint/ (专属于UV修复模式的文件）
        • uv_visibility/ (为UV修复生成的UV上的可见性遮罩）
      • misc/ (其他临时或杂项文件，例如用于Canny边缘检测输入的渲染）
      • .gif / .mp4 (如果使用了导出GIF/MP4工具，则这些文件会直接保存到带时间戳的修订目录中）
      • prompt.json (最后生成的用于ComfyUI的工作流）

---

🤔 故障排除

遇到问题？以下是一些常见的解决方法。请务必同时检查 Blender 系统控制台（窗口 > 切换系统控制台）和 ComfyUI 服务器控制台，以查看错误信息。

• StableGen 面板未显示： 确保插件已安装，并在 Blender 的偏好设置中启用。
• “无法生成…” 在生成按钮上： 检查插件偏好设置：输出目录 和 服务器地址 必须正确设置。同时，服务器必须可访问。
• 与 ComfyUI 连接问题：
  • 确保您的 ComfyUI 服务器正在运行。
  • 核实 StableGen 偏好设置中的 服务器地址。
  • 检查防火墙设置。
• 模型未找到（ComfyUI 控制台报错）：
  • 运行 installer.py 脚本。
  • 手动确保模型位于 <YourComfyUIDirectory>/models/ 的正确子文件夹中（例如：checkpoints/、controlnet/、loras/、ipadapter/、clip_vision/、clip/、vae/、unet/）。
  • 添加新模型或自定义节点后，请重启 ComfyUI。
• GPU 内存不足 (OOM)：
  • 如果未启用，请在 高级参数 > 输出与材质设置 中启用 自动缩放分辨率。
  • 烘焙时尝试降低烘焙分辨率。
  • 关闭其他占用 GPU 资源的应用程序。
• 生成完成后纹理不可见：
  • 切换到渲染视口着色模式（右上角第四个“球体”图标）。
• 纹理不受光照设置影响：
  • 在 高级参数 > 输出与材质设置 中启用 应用 BSDF，然后重新生成。
• 纹理质量差/出现伪影：
  • 尝试使用提供的预设。
  • 调整提示词和负面提示词。
  • 尝试不同的生成模式。通常，带有 IPAdapter 的 顺序 模式在一致性方面表现较好。
  • 确保相机覆盖范围足够，并适当设置 丢弃超角度。
  • 微调 ControlNet 强度。强度过低可能会忽略几何形状；强度过高则可能导致结果过于平坦。
  • 对于 顺序 模式，检查 inpainting 和可见性遮罩设置。
• 所有可见网格都被贴图： 默认情况下，StableGen 会为所有可见的网格对象贴图。您可以将 目标对象 设置为 选中，以便仅对选定对象进行贴图。

---

🤝 贡献

我们欢迎各种形式的贡献！无论是 bug 报告、功能建议、代码贡献，还是新的预设，请随时提交 issue 或 pull request。

---

📜 许可证

StableGen 采用 GNU 通用公共许可证 v3.0 发布。详情请参阅 LICENSE 文件。

第三方许可证：TRELLIS.2 图像转 3D

注意： 本节仅适用于 TRELLIS.2 图像转 3D 功能。StableGen 的标准贴图流程（SDXL、FLUX.1-dev、Qwen Image Edit）不使用下列任何库，因此不受这些许可限制的影响。

TRELLIS.2 功能依赖于多个第三方组件，每个组件都有其自身的许可证。用户应了解这些许可证，尤其是 TRELLIS.2 贴图输出流程中使用的某些 NVIDIA 库的非商业限制。

组件	许可证	是否允许商业使用？
TRELLIS.2（微软）	MIT	✅ 是
TRELLIS.2-4B 模型权重	MIT	✅ 是
ComfyUI-TRELLIS2	MIT	✅ 是
DINOv3（Meta，图像条件处理）	DINOv3 许可证	✅ 是
BiRefNet（背景去除）	MIT	✅ 是
FlexGEMM（稀疏卷积）	MIT	✅ 是
CuMesh（网格操作）	MIT	✅ 是
O-Voxel（体素处理，TRELLIS.2 的一部分）	MIT	✅ 是
nvdiffrast（NVIDIA）	NVIDIA 源代码许可证	❌ 仅限非商业用途
nvdiffrec（NVIDIA）	NVIDIA 源代码许可证	❌ 仅限非商业用途

重要提示： NVIDIA 的两个库（nvdiffrast 和 nvdiffrec）仅在将 TRELLIS.2 的 贴图模式 设置为 “原生（TRELLIS.2）” 时才会被使用——具体用于 UV 光栅化和 PBR 贴图烘焙。它们的许可证限制使用仅限于“研究或评估目的，不得用于任何直接或间接的经济利益”（第 3.3 条）。只有 NVIDIA 及其关联公司才能在商业环境中使用这些库。

其他所有 TRELLIS.2 模式均不涉及许可限制：

• 仅形状模式（“无”） - 不使用 nvdiffrast/nvdiffrec。其余管道组件均采用宽松许可（MIT/Apache 2.0 + DINOv3 许可证）。
• 基于投影的贴图模式（“SDXL”、“Qwen Image Edit”等） - 不使用 nvdiffrast/nvdiffrec。所选扩散模型的许可条款照常适用（例如，FLUX.1-dev 有其独立于 TRELLIS.2 流程的许可条款）。

如果您需要在商业环境中使用“原生（TRELLIS.2）”贴图模式，请考虑联系 NVIDIA，咨询关于 nvdiffrast/nvdiffrec 的商业许可事宜。

---

🙏 致谢

StableGen 基于众多个人和社区的卓越工作而构建。我们由衷地感谢以下各方：

• 学术渊源： 本插件最初是奥德雷·萨卡拉在布拉格捷克理工大学（信息技术学院）完成的学士论文，导师为拉德克·里希特工程师、博士。
  • 论文全文可在：https://dspace.cvut.cz/handle/10467/123567 查阅
• 核心技术与社区：
  • ComfyAnonymous 开发的 ComfyUI（GitHub），提供了强大且灵活的后端支持。
  • PozzettiAndrea 开发的 ComfyUI-TRELLIS2（GitHub），实现了 TRELLIS.2 与 ComfyUI 的集成。
  • Blender 基金会及其社区，提供了令人惊叹的开源 3D 创作套件。
• 受以下 Blender 插件启发：
  • 卡森·卡特里等人开发的 Dream Textures（GitHub）
  • 弗雷德里克·哈塞克开发的 Diffused Texture Addon（GitHub）
• 开创性研究： 我们深深感激那些推动 StableGen 核心技术发展的研究人员。以下列出了一些在扩散模型、AI 驱动控制以及 3D 纹理生成领域具有基础性和影响力的成果（附 arXiv 预印本链接）：
  • 扩散模型：
    • Ho 等人（2020），去噪扩散概率模型 - 2006.11239
    • Rombach 等人（2022），潜在扩散模型（Stable Diffusion）- 2112.10752
  • AI 控制机制：
    • Zhang 等人（2023），ControlNet - 2302.05543
    • Ye 等人（2023），IP-Adapter - 2308.06721
  • 关键的 3D 纹理合成论文：
    • Chen 等人（2023），Text2Tex - 2303.11396
    • Richardson 等人（2023），TEXTure - 2302.01721
    • Zeng 等人（2023），Paint3D - 2312.13913
    • Le 等人（2024），EucliDreamer - 2311.15573
    • Ceylan 等人（2024），MatAtlas - 2404.02899
  • 其他有影响力的工作：
    • Siddiqui 等人（2022），Texturify - 2204.02411
    • Bokhovkin 等人（2023），Mesh2Tex - 2304.05868
    • Levin & Fried（2024），微分扩散 - 2306.00950

正是 AI 和开源社区的开放精神，才使得像 StableGen 这样的项目成为可能。

---

💡 计划中的功能列表

以下是我们未来计划实现的一些功能（不分先后顺序）：

• 超分辨率： 支持对生成的纹理进行超分辨率处理。
• 自定义 VAE 和 CLIP 模型选择： 除了自定义 ControlNet 和 LoRA 模型外，还能够选择自定义的 VAE 和 CLIP 模型。
• 细化模式改进： 例如基于画笔的修复功能。
• 基于画笔的修复： 可直接在视口中绘制遮罩，以进行有针对性的局部编辑。
• 针对 TRELLIS.2 的更好重网格化： 实现更先进的重网格化技术，以提升生成网格的质量。

如果您有任何建议，请随时提交问题！

---

📧 联系方式

奥德雷·萨卡拉

• 邮箱：sakalaondrej@gmail.com
• X/Twitter：@sakalond

---

最后更新日期：2026年3月5日

StableGen 快速上手指南

StableGen 是一款开源 Blender 插件，旨在将生成式 AI 融入 3D 工作流。它支持通过文本或单张图片生成带贴图的 3D 模型（基于 TRELLIS.2），并能利用 SDXL、FLUX.1-dev 或 Qwen Image Edit 对现有模型进行高质量纹理生成与细化。

环境准备

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

系统要求

• 操作系统: Windows, macOS, 或 Linux
• Blender 版本: 4.2+ 或 5.1+
• GPU: 推荐 NVIDIA 显卡（支持 CUDA），显存建议 8GB 以上（生成高分辨率模型需更多显存）。
• 磁盘空间: 预留至少 20GB 空间用于安装 ComfyUI 后端及下载模型权重。

前置依赖

StableGen 依赖本地运行的 ComfyUI 作为计算后端。

1. 安装 Python: 确保已安装 Python 3.10 或更高版本。
2. 安装 ComfyUI:
   • 官方仓库：ComfyUI GitHub
   • 国内加速建议：若访问 GitHub 较慢，可使用 Gitee 镜像或国内源克隆。

   git clone https://github.com/comfyanonymous/ComfyUI.git
   cd ComfyUI
   pip install -r requirements.txt
   # 国内用户推荐使用清华/阿里源加速 pip 安装
   # pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   

3. 安装必要节点: StableGen 需要 ComfyUI-TRELLIS2 等自定义节点。插件安装脚本会自动处理部分依赖，但建议预先熟悉 ComfyUI 管理器 (ComfyUI Manager) 的使用。

安装步骤

1. 下载插件

访问 StableGen Releases 页面 下载最新版本的 .zip 安装包。

2. 在 Blender 中安装

1. 打开 Blender，进入 Edit (编辑) > Preferences (偏好设置)。
2. 选择左侧 Add-ons (插件) 标签页。
3. 点击右上角 Install... 按钮，选择下载的 .zip 文件。
4. 在列表中找到 StableGen，勾选复选框以启用插件。

3. 配置后端连接

1. 启动 ComfyUI 服务器（确保其监听地址允许本地连接，通常为 http://127.0.0.1:8188）。
2. 在 Blender 右侧属性面板找到 StableGen 选项卡。
3. 在 ComfyUI Server URL 字段中输入您的 ComfyUI 地址（默认即可）。
4. 点击 Connect 测试连接状态。若显示成功，即可开始使用。

提示: 首次运行时，插件可能会提示运行 installer.py 脚本以自动安装缺失的 ComfyUI 自定义节点（如 TRELLIS2 相关节点），请按提示操作。

基本使用

场景一：从文本/图片生成 3D 模型 (Text/Image to 3D)

此流程利用 TRELLIS.2 模型直接从零生成带贴图的网格。

1. 打开面板: 在 Blender 右侧边栏 (N 键) 切换到 StableGen 标签。
2. 选择模式: 在 Generation Mode 中选择 Text to 3D 或 Image to 3D。
3. 输入提示词/图片:
   • 若选文本模式，在 Prompt 框输入描述（例如："fantasy dragon, intricate details, 4k"）。
   • 若选图片模式，上传一张参考图。
4. 配置参数:
   • Resolution: 推荐选择 1024 Cascade 以平衡速度与细节。
   • Texture Pipeline: 可选择使用 TRELLIS 原生 PBR 贴图，或勾选 Use Diffusion Texturing 调用 SDXL/Flux/Qwen 进行重绘以提升质感。
5. 生成: 点击 Generate 按钮。
   • 系统将先在 ComfyUI 中生成候选视图，确认后可自动构建 3D 网格并导入 Blender 场景。

场景二：为现有模型添加纹理 (Texturing Existing Model)

此流程适用于您已有的低模或未贴图模型，利用多视角一致性技术进行贴图。

1. 准备模型: 在场景中选中一个或多个需要贴图的 Mesh 物体。
2. 设置相机:
   • 在 StableGen 面板的 Camera Setup 部分，选择一种放置策略（如 Orbit Ring 或 Hemisphere）。
   • 点击 Add Cameras 自动生成环绕模型的相机阵列。
3. 编写提示词:
   • 在全局 Prompt 中输入整体风格描述。
   • （可选）展开相机列表，为特定视角的相机输入独立的 View-Specific Prompt 以细化局部细节。
4. 配置生成引擎:
   • 在 Backend Settings 中选择底模（Checkpoint），如 SDXL, FLUX.1-dev 或 Qwen Image Edit。
   • 开启 ControlNet (Depth/Normal) 以确保纹理贴合几何结构。
5. 执行纹理化:
   • 选择 Sequential Mode (高质量，逐视角生成) 或 Grid Mode (快速预览)。
   • 点击 Start Texturing。
   • 插件将控制 ComfyUI 逐帧渲染视角，并通过智能混合算法将纹理投射回模型的 UV 上。

完成后，您可以在材质编辑器中查看生成的图像纹理，或使用 Texture Baking 工具将其烘焙为标准 UV 贴图以便进一步编辑。