查看 Markdown

TRELLIS

TRELLIS 是微软开源的图像转 3D 模型。它先把物体构建成稀疏体素结构,再为每个被占据的体素生成 32 个 3D 高斯泼溅(Gaussian Splatting)用的高斯。上游需要只支持 CUDA 的扩展;LibreYOLO 通过 LibreGen 工厂用纯 PyTorch 运行同样的权重。

任务
3d generation
尺寸
l at 518 px
安装
pip install "libreyolo[gen]"
支持层级
兄弟层级,自 v1.8.0 起。一个独立的产品面,有自己的工厂和契约。
上游
TRELLIS,由 Microsoft Research 发布,采用 MIT 许可。论文、源码
许可
代码采用 MIT,权重采用 MIT。商用

安装

bash
pip install "libreyolo[gen]"

这个 extra 会带上 transformers,用来加载 DINOv2 图像编码器。

预测

没有任何内容需要申请访问,也不需要登录。权重在首次使用时按固定版本下载。

Python
from libreyolo import LibreGen, SAMPLE_IMAGE model = LibreGen("trellis")         # 权重在首次使用时下载result = model(SAMPLE_IMAGE, seed=0) result.save("object.ply")           # 标准 3DGS 布局result.save("object.splat")         # 紧凑的 Web 格式print(len(result.gaussians))        # 由物体决定,不是可调参数
CLI
# 把物体以 .ply 保存到 runs/generate/predict 下libreyolo generate source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/guggenheim-bilbao.jpg model=trellis seed=0
设置
from libreyolo import LibreGen, SAMPLE_IMAGE model = LibreGen("trellis")result = model(SAMPLE_IMAGE, steps=12)          # 更快的采样result = model(SAMPLE_IMAGE, guidance=3.0, margin=1.3)

一个稠密 flow transformer 在 16^3 上对物体的占据情况去噪,一个 3D CNN 把它解码为 64^3 网格中的活跃体素,一个稀疏 flow transformer 在这些体素上对结构化潜变量去噪,再由一个稀疏 transformer 把每个体素转成 32 个高斯。两个 flow 阶段都读取 518 px 输入的 DINOv2 token。因此高斯的数量由物体决定(通常为 200,000 到 600,000 个)。

上游的稀疏卷积(spconv)和注意力(xformers 或 flash-attn)只能在 CUDA 上运行。LibreYOLO 用 PyTorch 运算替换它们并保留参数名,所以发布的权重在英伟达 GPU、Apple Silicon 和 CPU 上都能原样加载。噪声像上游一样在 CPU 上抽取,所以同一个种子在每种设备上都给出同一个物体。

输出是 result.gaussians,与 Speridlabs Idol 的载荷相同:xyz、scales、rotations、opacities、sh、colors、seed 和 params,z 轴朝上,范围 [-0.5, 0.5]^3。背景移除由 LibreYOLO 移植的 BiRefNet 完成。

设置

设置默认值含义
steps25采样步数,两个 flow 阶段共用。
guidance5.0无分类器引导(classifier-free guidance),两个 flow 阶段共用。
shift3.0flow 时间偏移。
margin1.2裁剪边长与物体尺寸之比,与上游一致。

变体

一个尺寸,l(TRELLIS-image-large):4 个网络共 13 亿参数,约 2.7 GB,另加 DINOv2 ViT-L/14 编码器的 1.2 GB。

导出

任务ONNXTorchScriptExecuTorchTensorRTOpenVINOPaddleMNNRKNNAxelerancnnTFLiteCoreMLCore AI
3D generation3D generation to ONNX:不支持3D generation to TorchScript:不支持3D generation to ExecuTorch:不支持3D generation to TensorRT:不支持3D generation to OpenVINO:不支持3D generation to Paddle:不支持3D generation to MNN:不支持3D generation to RKNN:不支持3D generation to Axelera:不支持3D generation to ncnn:不支持3D generation to TFLite:不支持3D generation to CoreML:不支持3D generation to Core AI:不支持

LibreGen 的 3D 家族没有实现导出。export()、train() 和 val() 会抛出 NotImplementedError(见库里的 ADR 0031)。

许可证

请检查你所下载的具体权重在 Hugging Face 仓库中的许可。LibreYOLO 组织里的每个检查点都附有许可,同一家族内也不一定相同。该仓库是权威来源;以下摘要说明本页上次验证时适用的情况。

这里只说明涉及的许可证,不构成法律意见。如果答案对商用很重要,请自行阅读许可证并咨询法律顾问。

原始工作
TRELLIS, Microsoft Research
上游许可
MIT
LibreYOLO 代码
MIT
权重
采用 MIT 许可,重新发布在 huggingface.co/LibreYOLO
解读
MIT is a permissive license, so the code and weights can be used in commercial and closed-source products; the only obligation is to keep the copyright and license notice with copies. LibreYOLO's adapter is MIT, and the flow models, decoders, sparse modules and sampler it adapts from TRELLIS keep MIT, noted in libreyolo/models/gen/trellis/NOTICE. LibreYOLO replaces upstream's CUDA-only spconv, xformers and flash-attn calls with PyTorch, and does not use TRELLIS's Gaussian holder, which carries Inria's non-commercial Gaussian Splatting license. The microsoft/TRELLIS-image-large weights (MIT) are redistributed unchanged as LibreYOLO/LibreTRELLISl together with the BiRefNet weights (MIT); the DINOv2 image encoder, facebook/dinov2-with-registers-large (Apache-2.0), downloads from Meta. All are pinned and none is gated.

TRELLIS 出自微软研究院(microsoft/TRELLIS)。代码和 microsoft/TRELLIS-image-large 权重采用 MIT 许可,所以保留声明即可商用。LibreYOLO 把这些权重与 BiRefNet 权重(MIT)一起原样再分发为 LibreYOLO/LibreTRELLISl。DINOv2 编码器 facebook/dinov2-with-registers-large 采用 Apache-2.0 许可,从 Meta 下载。上游的高斯容器采用 Inria 的非商用 Gaussian Splatting 许可,没有使用。

引用

@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}
}

复制自作者在 github.com/microsoft/TRELLIS#-citation 上提供的引用块。

已针对 LibreYOLO v1.8.0 验证。本页的支持表、检查点和基准测试数据由已发布的库和权重生成,并非手工编写。