人工智能计算机视觉媒体生成预训练3D渲染【免费下载链接】TRELLISOfficial repo for paper Structured 3D Latents for Scalable and Versatile 3D Generation (CVPR25 Spotlight).项目地址https://gitcode.com/gh_mirrors/trell/TRELLIS点击查看免费下载TRELLIS 是一个基于 Structured 3D Latents结构化 3D 潜空间简称 SLAT统一表征的大型 3D 资产生成模型支持以文本或图像为条件直接生成辐射场Radiance Fields、3D 高斯3D Gaussians与网格Meshes等多种格式的高质量 3D 资产。本篇指南以仓库根目录的 README.md 为核心骨架结合train.py、setup.sh、example.py、app.py及trellis/pipelines下的源码实现系统讲解 TRELLIS 的环境安装、预训练模型加载、最小推理示例、Web 演示、多视角条件与变体生成以及单机/多机训练与配置调优帮助读者从零上手并深入理解这一 CVPR25 Spotlight 工作。TRELLIS 是什么以 SLAT 为核心的三段式 3D 生成TRELLIS 的核心创新是一条统一的Structured LATentSLAT表征它把 3D 资产编码为带稀疏结构坐标的特征张量既能高效表达几何与外观又能通过不同的解码器输出不同格式。配合为 SLAT 专门设计的Rectified Flow Transformer骨干网络在trellis/models/structured_latent_flow.py与trellis/models/sparse_structure_flow.py中实现TRELLIS 提供了参数规模最高达20 亿的预训练模型训练数据覆盖 50 万级别的多样化 3D 资产。官方在 README 中给出的三大能力定位是高画质可生成形状与纹理细节丰富、多样性充足的 3D 资产多格式输出接受文本或图像提示可解码为辐射场、3D 高斯、网格等不同表示适配多样化下游需求灵活编辑支持对生成结果做局部编辑或生成同物体的不同变体。从推理链路看TrellisImageTo3DPipeline.run()见 trellis_image_to_3d.py清晰地体现了粗到细的两阶段采样先用稀疏结构流模型采样并解码出体素坐标sample_sparse_structure再在坐标上采样结构化潜变量sample_slat最后通过decode_slat一次性得到 mesh / gaussian / radiance_field 三种表示——这也对应configs/generation/与configs/vae/中成对出现的稀疏结构模型与 SLat 模型。环境安装与依赖解析前置要求官方在 README 中明确了运行环境底线系统代码仅在Linux上经过测试Windows 方案未完全验证硬件需要至少16GB 显存的 NVIDIA GPU已在 A100 与 A6000 上验证软件需要CUDA Toolkit已测试 11.8 与 12.2 两个版本以编译部分子模块推荐使用 Conda 管理依赖要求Python 3.8setup.sh新建环境时实际使用 Python 3.10见 setup.sh。克隆与一键安装git clone --recurse-submodules https://gitcode.com/gh_mirrors/trell/TRELLIS.git cd TRELLIS安装脚本setup.sh支持按需组合子模块README 推荐的完整安装命令为. ./setup.sh --new-env --basic --xformers --flash-attn --diffoctreerast --spconv --mipgaussian --kaolin --nvdiffrastsetup.sh的可用参数可通过. ./setup.sh --help查看源码见 setup.sh参数作用-h, --help显示帮助信息--new-env新建名为trellis的 conda 环境--basic安装基础依赖pillow、imageio、rembg、trimesh、open3d、transformers 等--train安装训练依赖tensorboard、pandas、lpips、pillow-simd 等--xformers安装 xformers按 PyTorch/CUDA 版本自动匹配--flash-attn安装 flash-attn--diffoctreerast安装可微八叉树光栅化渲染器辐射场渲染用--spconv安装 spconv稀疏卷积按 CUDA 11/12 选择 cu118/cu120--mipgaussian安装 mip-splatting 的高斯光栅化子模块--kaolin安装 NVIDIA kaolin--nvdiffrast安装 nvdiffrast--demo安装演示所需全部依赖gradio 4.44.1 与 gradio_litmodel3d安装注意事项以下几点直接决定安装与运行成败--new-env语义加上该参数会创建全新 conda 环境trellisPython 3.10 PyTorch 2.4.0 CUDA 11.8见 setup.sh若想复用已有环境请去掉该参数并手动安装 PyTorch多 CUDA 版本共存若机器同时装有 CUDA 11.8 与 12.2需在运行命令前把PATH指向正确版本例如export PATH/usr/local/cuda-11.8/bin:$PATH注意力后端默认使用flash-attn后端不支持 flash-attn 的 GPU如 V100应去掉--flash-attn只装 xformers并在运行代码前设置环境变量ATTN_BACKENDxformers依赖数量大、编译耗时长若出错可按参数逐个安装排查。运行期环境变量example.py开头的注释给出了两个重要的运行期环境变量源码见 example.py# os.environ[ATTN_BACKEND] xformers # 可选 flash-attn 或 xformers默认 flash-attn os.environ[SPCONV_ALGO] native # 可选 native 或 auto默认 autoATTN_BACKEND选择注意力实现后端需与安装的子模块一致SPCONV_ALGOauto更快但会在启动时做 benchmark若只运行一次官方建议设为native。预训练模型与加载方式官方提供四个主干模型均托管于 Hugging Face模型说明参数量TRELLIS-image-large大规模图像到 3D 模型1.2BTRELLIS-text-base基础文本到 3D 模型342MTRELLIS-text-large大规模文本到 3D 模型1.1BTRELLIS-text-xlarge超大规模文本到 3D 模型2.0B两点官方建议值得注意图像条件版本性能更优推荐优先使用所有 VAE 均已包含在 TRELLIS-image-large 仓库中因此加载该模型即可获得完整的编解码器。加载方式支持两种对应TrellisImageTo3DPipeline.from_pretrained的实现见 trellis_image_to_3d.py# 方式一直接从模型仓库名加载 pipeline TrellisImageTo3DPipeline.from_pretrained(microsoft/TRELLIS-image-large) # 方式二从本地目录加载保持目录结构不变 pipeline TrellisImageTo3DPipeline.from_pretrained(/path/to/TRELLIS-image-large)在from_pretrained内部管线会从_pretrained_args中恢复稀疏结构采样器、SLat 采样器、SLat 归一化参数与条件编码模型图像条件使用 DINOv2torch.hub.load(facebookresearch/dinov2, ...)见 trellis_image_to_3d.py文本条件使用 CLIP 文本编码器见 trellis_text_to_3d.py。最小推理示例从单张图片生成三种表示以下完整示例来自 example.py是官方推荐的图像到 3D 最小流程import os # os.environ[ATTN_BACKEND] xformers # Can be flash-attn or xformers, default is flash-attn os.environ[SPCONV_ALGO] native # Can be native or auto, default is auto. import imageio from PIL import Image from trellis.pipelines import TrellisImageTo3DPipeline from trellis.utils import render_utils, postprocessing_utils # Load a pipeline from a model folder or a Hugging Face model hub. pipeline TrellisImageTo3DPipeline.from_pretrained(microsoft/TRELLIS-image-large) pipeline.cuda() # Load an image image Image.open(assets/example_image/T.png) # Run the pipeline outputs pipeline.run( image, seed1, # Optional parameters # sparse_structure_sampler_params{ # steps: 12, # cfg_strength: 7.5, # }, # slat_sampler_params{ # steps: 12, # cfg_strength: 3, # }, ) # outputs is a dictionary containing generated 3D assets in different formats: # - outputs[gaussian]: a list of 3D Gaussians # - outputs[radiance_field]: a list of radiance fields # - outputs[mesh]: a list of meshes # Render the outputs video render_utils.render_video(outputs[gaussian][0])[color] imageio.mimsave(sample_gs.mp4, video, fps30) video render_utils.render_video(outputs[radiance_field][0])[color] imageio.mimsave(sample_rf.mp4, video, fps30) video render_utils.render_video(outputs[mesh][0])[normal] imageio.mimsave(sample_mesh.mp4, video, fps30) # GLB files can be extracted from the outputs glb postprocessing_utils.to_glb( outputs[gaussian][0], outputs[mesh][0], simplify0.95, # Ratio of triangles to remove in the simplification process texture_size1024, # Size of the texture used for the GLB ) glb.export(sample.glb) # Save Gaussians as PLY files outputs[gaussian][0].save_ply(sample.ply)运行结束后工作目录将产生五个产物含义如下sample_gs.mp43D 高斯表示的视频预览sample_rf.mp4辐射场表示的视频预览sample_mesh.mp4网格表示法线着色的视频预览sample.glb从高斯与网格提取的带纹理 GLB 文件sample.ply3D 高斯的 PLY 文件。管线参数与底层采样细节pipeline.run()的完整签名见 trellis_image_to_3d.py常用参数为imagePIL 图像提示num_samples生成样本数默认 1seed随机种子默认 42sparse_structure_sampler_params第一阶段稀疏结构采样器参数常用steps与cfg_strengthslat_sampler_params第二阶段结构化潜变量采样器参数常用steps与cfg_strengthformats解码目标格式列表默认[mesh, gaussian, radiance_field]可裁剪以省显存preprocess_image是否执行自动预处理背景抠除、按 alpha 裁剪并缩放到 518×518默认 True。图像预处理在 trellis_image_to_3d.py 中实现若输入为 RGBA 且 alpha 非全 255 则直接使用 alpha 通道否则用 rembg 的u2net模型抠图随后按 alpha 包围盒裁剪、放大 1.2 倍并缩放到 518×518。这正是 README 中 Web Demo 描述有 alpha 通道就用它作为 mask否则用 rembg 抠背景的底层依据。采样步数与 CFG 强度如何影响结果steps与cfg_strength对应采样器FlowEulerSampler/FlowEulerCfgSampler的参数见 flow_euler.pystepsEuler 法离散时间步数默认 50步数越多精度越高、耗时越长官方示例与 Web Demo 常用 12 步cfg_strengthClassifier-Free Guidance 强度默认 3.0越大越贴近条件、多样性降低示例中第一阶段常用 7.5、第二阶段常用 3.0rescale_t时间步重缩放因子cfg_interval仅在指定时间区间施加引导见FlowEulerGuidanceIntervalSampler。采样器的内部流程sample方法先构造t_seq linspace(1, 0, steps1)的时间序列再逐步执行sample_once的欧拉更新x_{t-1} x_t - (t - t_prev) * v。管线中通过sampler_params {**self.xxx_sampler_params, **sampler_params}将预训练默认参数与用户覆盖参数合并运行时传入采样器见 trellis_image_to_3d.py。Web 演示Gradio 界面一键生成与导出TRELLIS 的官方 Gradio 演示 提供浏览器交互式生成。先安装演示依赖. ./setup.sh --demo再启动服务python app.py按终端提示的地址访问即可。该演示在 README 描述的基础上从源码看还包含以下可操作要素见 app.py单图 / 多图两个输入 Tab单图模式走pipeline.run多图模式走pipeline.run_multi_image并提供stochastic与multidiffusion两种多图融合算法切换两阶段生成参数滑块Stage 1 稀疏结构生成Guidance Strength 默认 7.5、Sampling Steps 默认 12与 Stage 2 结构化潜变量生成Guidance Strength 默认 3.0、Steps 默认 12GLB 提取参数simplify网格简化比例默认 0.95可选 0.9–0.98与texture_size纹理分辨率默认 1024可选 512–2048导出能力生成后可将当前状态打包pack_state进浏览器端状态再一键Extract GLB或Extract GaussianGaussian PLY 体积可达约 50MB内置assets/example_image/与assets/example_multi_image/中的示例图可直接点选体验。进阶玩法多图条件与同物体变体生成README 的 Updates 部分记录了 12/26 与 03/25 两轮重要更新其中两项能力有对应示例脚本是理解 TRELLIS 表达能力的关键入口多视角图像条件免训练算法2024-12-18 起支持多图条件run_multi_image无需训练专用模型即可用多张视角图约束生成属于 tuning-free 算法对姿态不一致或细节冲突的输入图效果可能不理想。核心实现是inject_sampler_multi_image上下文管理器见 trellis_image_to_3d.py提供两种模式stochastic按步数循环轮换使用不同视角作为条件multidiffusion每个步把多视角预测结果求平均后再施加 CFG。完整示例见 example_multi_image.py它加载assets/example_multi_image/character_{1,2,3}.png三个视角并拼接渲染输出sample_multi.mp4。文本驱动的变体生成2025-03-25 随 TRELLIS-text 模型一同发布。TrellisTextTo3DPipeline.run_variant见 trellis_text_to_3d.py先对输入网格做体素化voxelize64³ 分辨率、归一化到 [-0.5, 0.5] 包围盒再在固定结构坐标上重新采样 SLat实现同结构、换风格。示例见 example_variant.py以assets/T.ply为底模用 Rugged, metallic texture with orange and white paint finish... 的提示词生成工业风变体。文本到 3D 的官方建议README 特别提醒文本到 3D 推荐先使用文本到图像模型生成图片再走 TRELLIS-image 管线——纯文本条件模型受限于数据创造性与细节不如图像条件模型。文本到 3D 的最小示例见 example_text.py使用microsoft/TRELLIS-text-xlarge。数据集TRELLIS-500K 与数据工具链TRELLIS-500K 是官方发布的 50 万级 3D 资产生成数据集素材来源于 Objaverse(XL)、ABO、3D-FUTURE、HSSD 与 Toys4k 等公开数据集并基于美学分数过滤。完整的采集、筛选、预处理流程与各脚本说明见 DATASET.md。仓库的dataset_toolkits/目录提供了配套工具链render.py、render_cond.py、voxelize.py、encode_latent.py、extract_feature.py、build_metadata.py、calculate_aesthetic_scores.py等可将原始网格数据处理为训练所需的稀疏结构与 SLat 潜变量。训练时通过--data_dir指定数据目录支持逗号分隔多个数据集见 train.py 中datasets的加载方式。训练配置驱动的模块化框架TRELLIS 的训练代码以 train.py 为入口仓库目录划分清晰trellis/datasets负责数据加载与预处理trellis/models存放各模型组件trellis/modules提供稀疏模块、注意力、Transformer 等自定义算子trellis/pipelines负责推理管线trellis/renderers提供各表示的可微渲染trellis/representations实现高斯/网格/八叉树/辐射场表征trellis/trainers承载训练逻辑trellis/utils提供可视化与工具函数。训练前置条件安装全部训练依赖--trainLinux NVIDIA GPU官方在 A100 上训练多机训练需确保节点间可通过指定的 master 地址与端口通信数据集按 TRELLIS-500K 同构组织用--data_dir指定。配置文件模型、数据与训练器三位一体超参与模型架构全部定义在configs/下。以图像条件 SLat 流模型 configs/generation/slat_flow_img_dit_L_64l8p2_fp16.json 为例它包含三大部分models.denoiserElasticSLatFlowModel关键参数包括resolution: 64稀疏网格分辨率、in_channels/out_channels: 8SLat 通道数、model_channels: 1024、num_blocks: 24、num_heads: 16、patch_size: 2、pe_mode: ape、qk_rms_norm: true、use_fp16: truedatasetImageConditionedSLat包括image_size: 518、max_num_voxels: 32768、min_aesthetic_score: 4.5以及 SLat 的逐通道mean/std归一化统计量8 维向量对应 8 通道潜变量与预训练 SLat 解码器引用trainerImageConditionedSparseFlowMatchingCFGTrainer包括max_steps: 1000000、batch_size_per_gpu: 8、batch_split: 4、AdamWlr1e-4、EMA 率 0.9999、fp16_mode: inflat_all、弹性内存控制器LinearMemoryController目标显存占用比 0.75、自适应梯度裁剪AdaptiveGradClippermax_norm 1.0、p_uncond: 0.1无条件训练比例支撑 CFG、t_schedulelogitNormal 时间分布与sigma_min: 1e-5。README 给出的完整配置清单及对应预训练权重如下这些配置同时解释了训练与推理同构的设计推理管线加载的正是这些模型的产物配置文件对应预训练权重说明configs/vae/ss_vae_conv3d_16l8_fp16.jsonSparse Structure VAE 编码器/解码器稀疏结构 VAEconfigs/vae/slat_vae_enc_dec_gs_swin8_B_64l8_fp16.jsonSLat 编码器 高斯解码器SLat VAE高斯解码configs/vae/slat_vae_dec_rf_swin8_B_64l8_fp16.jsonSLat 辐射场解码器SLat 辐射场解码器configs/vae/slat_vae_dec_mesh_swin8_B_64l8_fp16.jsonSLat 网格解码器SLat 网格解码器configs/generation/ss_flow_img_dit_L_16l8_fp16.json图像条件稀疏结构去噪器图像条件稀疏结构流模型configs/generation/slat_flow_img_dit_L_64l8p2_fp16.json图像条件 SLat 去噪器图像条件 SLat 流模型configs/generation/ss_flow_txt_dit_B_16l8_fp16.jsonBase 文本条件稀疏结构去噪器Base 文本条件稀疏结构流模型configs/generation/slat_flow_txt_dit_B_64l8p2_fp16.jsonBase 文本条件 SLat 去噪器Base 文本条件 SLat 流模型configs/generation/ss_flow_txt_dit_L_16l8_fp16.jsonLarge 文本条件稀疏结构去噪器Large 文本条件稀疏结构流模型configs/generation/slat_flow_txt_dit_L_64l8p2_fp16.jsonLarge 文本条件 SLat 去噪器Large 文本条件 SLat 流模型configs/generation/ss_flow_txt_dit_XL_16l8_fp16.jsonXL 文本条件稀疏结构去噪器XL 文本条件稀疏结构流模型configs/generation/slat_flow_txt_dit_XL_64l8p2_fp16.jsonXL 文本条件 SLat 去噪器XL 文本条件 SLat 流模型train.py 命令行参数训练脚本的完整用法与 train.py 中 argparse 定义一致usage: train.py [-h] --config CONFIG --output_dir OUTPUT_DIR [--load_dir LOAD_DIR] [--ckpt CKPT] [--data_dir DATA_DIR] [--auto_retry AUTO_RETRY] [--tryrun] [--profile] [--num_nodes NUM_NODES] [--node_rank NODE_RANK] [--num_gpus NUM_GPUS] [--master_addr MASTER_ADDR] [--master_port MASTER_PORT] options: -h, --help 显示帮助并退出 --config CONFIG 实验配置文件必填 --output_dir OUTPUT_DIR 输出目录必填 --load_dir LOAD_DIR 加载目录默认取 output_dir --ckpt CKPT 恢复训练的检查点步数默认 latest --data_dir DATA_DIR 数据目录 --auto_retry AUTO_RETRY 出错重试次数 --tryrun 只做试运行不真正训练 --profile 训练性能剖析 --num_nodes NUM_NODES 节点数 --node_rank NODE_RANK 节点编号 --num_gpus NUM_GPUS 每节点 GPU 数默认使用全部 --master_addr MASTER_ADDR 分布式训练的 master 地址 --master_port MASTER_PORT 分布式训练端口单机训练训练一个图像到 3D 的第二阶段SLat 网格解码器模型python train.py \ --config configs/vae/slat_vae_dec_mesh_swin8_B_64l8_fp16.json \ --output_dir outputs/slat_vae_dec_mesh_swin8_B_64l8_fp16_1node \ --data_dir /path/to/your/dataset1,/path/to/your/dataset2脚本会自动使用本机全部可用 GPU可用--num_gpus限制使用的 GPU 数量。多机分布式训练以 2 节点训练图像条件 SLat 流模型为例python train.py \ --config configs/generation/slat_flow_img_dit_L_64l8p2_fp16.json \ --output_dir outputs/slat_flow_img_dit_L_64l8p2_fp16_2nodes \ --data_dir /path/to/your/dataset1,/path/to/your/dataset2 \ --num_nodes 2 \ --node_rank 0 \ --master_addr $MASTER_ADDR \ --master_port $MASTER_PORT每个节点需相应调整node_rank、master_addr、master_port。从 train.py 的main函数可以看清分布式启动逻辑全局 rank 由node_rank * num_gpus local_rank计算world_size num_nodes * num_gpus多卡时通过mp.spawn拉起子进程并使用setup_dist初始化分布式环境。断点续训默认情况下训练会自动从同一输出目录中最新保存的检查点恢复。若要指定恢复来源用--load_dir与--ckptpython train.py \ --config configs/generation/slat_flow_img_dit_L_64l8p2_fp16.json \ --output_dir outputs/slat_flow_img_dit_L_64l8p2_fp16_resume \ --data_dir /path/to/your/dataset1,/path/to/your/dataset2 \ --load_dir /path/to/your/checkpoint \ --ckpt [step]检查点查找逻辑在 train.py 的find_ckpt中--ckpt latest时扫描load_dir/ckpts/misc_*step*.pt取最大步数--ckpt none表示从零开始也可直接传入整数步数。训练辅助选项自动重试--auto_retry N指定间歇性错误的重试次数train.py外层循环会捕获异常并重跑见 train.py试运行--tryrun用于在启动完整训练前校验配置与环境构建数据集、模型、trainer 后直接退出见 train.py性能剖析--profile开启训练剖析用于定位性能瓶颈日志与配置落盘主节点会在output_dir下保存command.txt完整启动命令与config.json解析后的配置见 train.py。许可证与引用TRELLIS 模型与大部分代码遵循 MIT License。两个子模块采用不同许可diffoctreerast本项目开发的、基于 diff-gaussian-rasterization 派生的 CUDA 实时可微八叉树渲染器用于辐射场渲染与修改版 FlexiCubes支持顶点属性的版本。引用本工作时请按 README 提供的 BibTeX 条目引用article{xiang2024structured, title {Structured 3D Latents for Scalable and Versatile 3D Generation}, author {Xiang, Jianfeng and Lv, Zelong and Xu, Sicheng and Deng, Yu and Wang, Ruicheng and Zhang, Bowen and Chen, Dong and Tong, Xin and Yang, Jiaolong}, journal {arXiv preprint arXiv:2412.01506}, year {2024} }结语从推理到训练的完整路径回看整条链路TRELLIS 用 SLAT 统一了结构稀疏坐标 内容潜特征的表达两阶段 Rectified Flow 生成稀疏结构 → 结构化潜变量 多格式解码mesh / gaussian / radiance_field构成了清晰的推理管线而configs/下的配置与train.py的模块化框架让研究者既可以一键复现图像/文本条件下的 VAE 与流模型训练也能在此基础上微调或扩展。无论是调用example.py完成最小推理、启动app.py做交互式 Web 演示还是参考example_multi_image.py/example_variant.py探索多视角与变体能力均可从本指南对应的源码与配置路径出发逐步深入 TRELLIS 的每一层实现。赞分享人工智能计算机视觉媒体生成预训练3D渲染【免费下载链接】TRELLISOfficial repo for paper Structured 3D Latents for Scalable and Versatile 3D Generation (CVPR25 Spotlight).项目地址https://gitcode.com/gh_mirrors/trell/TRELLIS点击查看免费下载相关推荐腾讯混元3D模型实战指南从云端部署到3D资产生成全流程解析背景介绍 在数字内容创作领域3D资产的生成一直是技术与艺术结合的难点。腾讯云最新推出的混元3D模型Hunyuan3D彻底改变了这一现状作为一套完整的大规人工智能基础模型计算机视觉模型推理服务TRELLIS.2 实战指南基于 O-Voxel 原生稀疏结构潜变量的 4B 图像转 3D 生成、PBR 纹理与全流程训练TRELLIS.2 实战指南基于 O Voxel 原生稀疏结构潜变量的 4B 图像转 3D 生成、PBR 纹理与全流程训练 TRELLIS.2 是微软开源的大人工智能大模型预训练图形学媒体生成TRELLIS单节点训练指南高效训练大型3D生成模型的终极方案TRELLIS单节点训练指南高效训练大型3D生成模型的终极方案 想要快速上手强大的3D生成AI模型吗TRELLIS作为新一代结构化3D潜在空间生成框架让单人工智能计算机视觉媒体生成预训练3D渲染创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考