一张图变成 3D：TRELLIS 图生3D 与文生3D 的最简上手路径
【免费下载链接】TRELLISOfficial repo for paper "Structured 3D Latents for Scalable and Versatile 3D Generation" (CVPR'25 Spotlight).项目地址: https://gitcode.com/gh_mirrors/trell/TRELLIS
TRELLIS 是一个大规模 3D 资产生成模型：你输入一张图或一段文字，它直接输出辐射场、3D 高斯和网格三种格式的 3D 资产，还能做局部编辑。适合想把 2D 素材变成可编辑 3D 模型的设计师和开发者，跑通后你会拿到带纹理的 .glb 网格、.ply 高斯和一段旋转预览视频。
项目亮点速览
- 三种输出格式：辐射场、3D 高斯、网格
- 同一对象可生成变体与局部编辑
- 基于 2B 参数模型与 500K 资产训练
环境准备与安装
先确认几项硬性依赖，缺一不可：
- 系统：Linux（官方仅在 Linux 测试，Windows 需自行处理）
- GPU：NVIDIA 卡，显存至少 16GB（A100 / A6000 已验证）
- CUDA：Toolkit 11.8 或 12.2，用于编译部分子模块
- Python：3.8 及以上，建议用 Conda 管理依赖
安装只需两条命令，其余依赖由脚本统一拉取，首次耗时较长属正常现象：
git clone --recurse-submodules https://gitcode.com/gh_mirrors/trell/TRELLIS.git && cd TRELLIS . ./setup.sh --new-env --basic --xformers --flash-attn --diffoctreerast --spconv --mipgaussian --kaolin --nvdiffrast如果脚本执行失败，优先检查 CUDA 版本与PATH是否匹配，可用. ./setup.sh --help查看参数说明。
你的第一次生成
官方推荐从图生3D 入手，质量通常优于文生3D。这段代码加载microsoft/TRELLIS-image-large模型，把仓库自带的assets/example_image/T.png转成 3D 资产并渲染一段旋转视频。
import os os.environ['SPCONV_ALGO'] = 'native' # 单次运行建议设为 native from PIL import Image from trellis.pipelines import TrellisImageTo3DPipeline from trellis.utils import render_utils pipeline = TrellisImageTo3DPipeline.from_pretrained("microsoft/TRELLIS-image-large") pipeline.cuda() image = Image.open("assets/example_image/T.png") outputs = pipeline.run(image, seed=1) # 含 gaussian / radiance_field / mesh video = render_utils.render_video(outputs['gaussian'][0])['color']运行后终端会打印采样进度，outputs同时拿到高斯、辐射场、网格三种表示，video就是高斯渲染出的旋转帧。想从文字直接生成时，把 pipeline 换成TrellisTextTo3DPipeline并传入一句描述即可，参考example_text.py。
调参与定制
最影响输出质量的参数如下，改哪个、影响什么一目了然：
| 参数 | 改什么 | 影响什么 |
|---|---|---|
seed | 固定随机种子 | 复现同一生成结果 |
sparse_structure_sampler_params | steps、cfg_strength | 几何结构的采样步数与保真度 |
slat_sampler_params | steps、cfg_strength | 纹理 / 材质等外观细节质量 |
to_glb的simplify、texture_size | 网格简化比例、贴图分辨率 | 导出 .glb 的面数与贴图 |
ATTN_BACKEND环境变量 | flash-attn/xformers | 注意力后端，老架构用xformers |
模型架构与超参在configs/generation/与configs/vae/，改完可直接用train.py启动训练或复现配置。
进阶玩法（按需选读）
- 多图条件生成：把同一对象的多视角图组成列表传入即可，无需额外训练。
outputs = pipeline.run_multi_image(images, seed=1) - 对象变体：基于已有网格生成换材质 / 外观的新资产，无需额外训练。
outputs = pipeline.run_variant(base_mesh, "Rugged metallic texture", seed=1) - Web 演示：装好 demo 依赖后起 Gradio 界面，需额外准备。
. ./setup.sh --demo
避坑与 FAQ
- CUDA OOM→ 模型与渲染同占显存 → 减小
num_samples或换 16GB 以上卡。 - Windows 装不上→ 官方仅测试 Linux → 改用 Linux 或 WSL 环境。
- 首次运行卡住→ 正在下载 1.2B 模型与 DINOv2 → 提前本地下载或挂代理加速。
- spconv / flash-attn 编译报错→ CUDA 版本与
PATH不匹配 →export正确 CUDA 路径后重装。 - V100 报 flash-attn 不支持→ 老架构不兼容 → 去掉
--flash-attn并设ATTN_BACKEND=xformers。
后续学习路径
trellis/pipelines/：图生3D 与文生3D 的推理流水线源码。configs/generation/与configs/vae/：生成模型与 VAE 的全部配置。example.py、example_text.py、example_variant.py：三条完整可运行示例。
看完这几处，你就能改出自己的生成配置。
【免费下载链接】TRELLISOfficial repo for paper "Structured 3D Latents for Scalable and Versatile 3D Generation" (CVPR'25 Spotlight).项目地址: https://gitcode.com/gh_mirrors/trell/TRELLIS
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
