查看 Markdown

Direct3D-S2

Direct3D-S2 是 DreamTech 的图像转 3D 模型。它在稀疏体素上生成有符号距离场,先在 512^3,再在 1024^3,最后把物体作为网格返回。上游需要只支持 CUDA 的扩展;LibreYOLO 通过 LibreGen 工厂用纯 PyTorch 运行同样的权重。

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

安装

bash
pip install "libreyolo[gen]"

这个 extra 会带上 diffusers、transformers(DINOv2 编码器)和 scikit-image(marching cubes)。

预测

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

Python
from libreyolo import LibreGen, SAMPLE_IMAGE model = LibreGen("direct3d-s2")     # 权重在首次使用时下载result = model(SAMPLE_IMAGE, seed=0) result.save("object.obj")m = result.meshesprint(m.vertices[0].shape, m.faces[0].shape)
CLI
# 把物体以 .obj 保存到 runs/generate/predict 下libreyolo generate source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/guggenheim-bilbao.jpg model=direct3d-s2 seed=0
设置
from libreyolo import LibreGen, SAMPLE_IMAGE model = LibreGen("direct3d-s2")result = model(SAMPLE_IMAGE, resolution=512)     # 第一遍之后就停止result = model(SAMPLE_IMAGE, steps=(25, 15, 8))  # 每个阶段用更少的步数

一个稠密 flow transformer 找出被占据的 64^3 体素,一个带空间稀疏注意力的稀疏 flow transformer 在这些体素上对潜变量去噪,一个稀疏解码器再把它转成 512^3 的有符号距离场。第二遍在 1024^3 上重复这一过程。网格是该场的零值面,由 marching cubes 提取。上游只能在 CUDA 上运行(torchsparse、flash-attn、Triton 内核、一个 CUDA 体素化器);LibreYOLO 用 PyTorch 运算替换它们并保留参数名,所以发布的检查点(checkpoint)在 CUDA、Apple MPS 和 CPU 上都能原样加载。

同一个种子给出同一个物体;在 CUDA 上,初始噪声与上游在 torch.manual_seed(seed) 下的一致。result.meshes 包含 vertices (V, 3),z 轴朝上,范围 [-0.5, 0.5]^3,以及 faces (F, 3)。上游可选的重新网格化和补洞没有包含在内(它们依赖 GPL 工具),所以网格就是 marching cubes 返回的样子。

纯 PyTorch 下它很慢:库在 RTX A6000 上测得一个 1024^3 的物体约需 18 分钟和 23 GB 显存,而上游的 CUDA 内核只要 2.5 分钟。resolution=512 会在第一遍之后停止。

设置

设置默认值含义
resolution10241024(上游默认)或 512。
steps(50, 30, 15)稠密、512 和 1024 三个阶段的步数;传一个整数则三个阶段都用它。
guidance7.0三个阶段的无分类器引导(classifier-free guidance)。

变体

一个检查点,v11(Direct3D-S2 v1.1):8 个网络共 20 亿参数,约 4.2 GB,另加 DINOv2 ViT-L/14 的 1.2 GB 和 BiRefNet 的 0.4 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 组织里的每个检查点都附有许可,同一家族内也不一定相同。该仓库是权威来源;以下摘要说明本页上次验证时适用的情况。

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

原始工作
Direct3D-S2, DreamTech
上游许可
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; the flow transformers, SDF VAE decoders, refiners and spatial sparse attention it adapts from Direct3D-S2 keep MIT, with the attention following native-sparse-attention-triton (Apache-2.0) and the transformer modules TRELLIS's (MIT), noted in libreyolo/models/gen/direct3d_s2/NOTICE. Upstream's hole filling and remeshing, which need GPL-licensed pymeshfix and python-igraph, are not used. The wushuang98/Direct3D-S2 v1.1 weights (MIT) are redistributed unchanged as LibreYOLO/LibreDirect3DS2v11; the BiRefNet weights (MIT) come from LibreYOLO/LibreTRELLISl and the DINOv2 encoder, facebook/dinov2-with-registers-large (Apache-2.0), from Meta. All are pinned and none is gated.

Direct3D-S2 出自 DreamTech(DreamTechAI/Direct3D-S2)。代码和 wushuang98/Direct3D-S2 v1.1 权重采用 MIT 许可,所以保留声明即可商用。LibreYOLO 以 LibreYOLO/LibreDirect3DS2v11 原样再分发这些权重。BiRefNet(MIT)来自 LibreYOLO/LibreTRELLISl,DINOv2 编码器 facebook/dinov2-with-registers-large(Apache-2.0)来自 Meta。上游采用 GPL 许可的 pymeshfix 和 python-igraph 都没有使用。

引用

@article{wu2025direct3ds2gigascale3dgeneration,
  title={Direct3D-S2: Gigascale 3D Generation Made Easy with Spatial Sparse Attention}, 
  author={Shuang Wu and Youtian Lin and Feihu Zhang and Yifei Zeng and Yikang Yang and Yajie Bao and Jiachen Qian and Siyu Zhu and Philip Torr and Xun Cao and Yao Yao},
  journal={arXiv preprint arXiv:2505.17412},
  year={2025}
}

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

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