# Local 3D generation

> Local 3D generation 运行时：trellis.cpp，Microsoft TRELLIS.2 的 C++ 移植版，能在你自己的 NVIDIA 或 Vulkan GPU 上把一张图片变成带贴图的 3D 模型（带 PBR 材质的 GLB），每个模型零成本。它运行 TRELLIS.2 4B 和 Pixal3D 模型包，这些模型包需单独安装。Windows；Linux 预览版。

- ID: `aigd.trellis`
- 来源: 官方 (第一方 `aigd.*`)
- 分类: 3D
- 发布者: AI Game Dev (`aigd`), 已验证
- 最新版本: 1.0.3 (发布于 2026-11-22)
- 许可证: MIT
- 需要 AI Game Dev 应用: `>=0.32.0-beta.6`
- 原生代码: 否
- 评分: 暂无评分
- HTML 页面: https://ai-game.dev/zh-hans/packages/aigd.trellis

## 安装

使用 gamedev CLI，在项目文件夹中运行：

```bash
gamedev pkg add aigd.trellis
```

在桌面应用中：打开 Packages 窗口（状态栏中的包图标），选择 **Browse**，搜索 `aigd.trellis`，然后点击 **Add to Project**。更多：https://ai-game.dev/docs/wiki/app/packages

## 版本

| 版本 | 发布时间 | 需要应用 | 备注 |
|---|---|---|---|
| 1.0.3 | 2026-11-22 | `>=0.32.0-beta.6` | 最新 |
| 1.0.2 | 2026-11-21 | `>=0.32.0-beta.6` | - |

## 描述

````markdown
# Local 3D generation (`aigd.trellis`)

Local 3D generation 是在这台电脑上、用你自己的 GPU，借助 [trellis.cpp](https://github.com/pwilkin/trellis.cpp)（Microsoft TRELLIS.2 的 C++/GGML 移植版）把一张图片变成带贴图 3D 模型（带 PBR 材质的 GLB）的运行时。一切都在这台电脑上完成，而且不花一分钱。这个包本身不含任何模型：它运行 [TRELLIS.2 4B](https://ai-game.dev/packages/aigd.model3d-trellis2-4b) 和 [Pixal3D](https://ai-game.dev/packages/aigd.model3d-pixal3d) 这两个 3D 模型包。它适合拥有 NVIDIA 或 Vulkan GPU、想不依赖云服务就拿到带贴图 3D 资产的开发者。

## 你可以做什么

安装模型包之后：

- 从一张图片生成带贴图、可直接用于 PBR 的道具、武器、家具、载具和角色。
- 概念图或真实物体照片的 3D 版本。
- 两步实现文本生成 3D：先用本地或云端图像模型生成图片，再把它变成 3D。

## 示例请求

- “把 `Concepts/crate.png` 变成带贴图的 3D 模型。”
- “做一张木制市集摊位的图片，然后把它变成 3D 模型。”
- “用 Pixal3D 以分辨率 1024 生成这张照片的 3D 模型。”

## 亮点

|  |  |
|---|---|
| 运行时 | trellis.cpp v0.8.1 (MIT) |
| 功能 | 图像转带贴图 3D（GLB，PBR 材质） |
| 模型 | 单独的包：TRELLIS.2 4B（约 16.5 GB），Pixal3D（约 14.5 GB） |
| Windows | NVIDIA GPU（CUDA 13）或 AMD / Intel / 其他 GPU（Vulkan） |
| Linux | x64，带 NVIDIA（CUDA 13）或 Vulkan，预览版 |
| macOS | 不提供（上游没有构建版本） |
| 下载 | 14–16 MB（Vulkan）或 715 MB（CUDA，含 NVIDIA 运行时） |
| 许可 | MIT；每个模型包各自声明其许可 |

## 如何运行

这个包只有数据（`aigd-package.json`，不含代码）。它告诉 AI Game Dev 该为你的电脑下载哪个 trellis.cpp 版本。应用会自行下载、校验并运行该程序。在你打开之前，它的 **3D Gen** 开关是关着的。

3D 模型与本地图像、片段和语音共用同一个本地 GPU 队列：同一时间只运行一个模型，3D 任务会等排在它前面的图像或片段任务做完（反过来也一样）。一个 3D 任务要跑几分钟；你可以随时停止它。

## 模型是单独的包

这个包不包含任何模型。先从 Packages 浏览器安装模型包，再到 Models 面板下载它的文件。未经你确认不会下载任何内容，而且你会先看到大小。

- `aigd.model3d-trellis2-4b` — TRELLIS.2 4B（Microsoft），约 16.5 GB。
- `aigd.model3d-pixal3d` — Pixal3D（Tencent ARC），约 14.5 GB；它与 TRELLIS.2 共用 3.5 GB 的文件，所以两个都装约 27 GB。

每个模型都带贴图：trellis.cpp v0.8.1 只在贴图时简化网格，而它仅含原始几何的网格（数百万个面）超出了应用的 GLB 限制，因此不提供只出几何的运行方式。

文本生成 3D（先由图像模型出图，再图像转 3D）还没接上：请先用本地或云端图像模型生成图片，再把它变成 3D。

## 会下载什么

上游发行版，按 tag 固定并用 sha256 校验：`pwilkin/trellis.cpp` [`v0.8.1`](https://github.com/pwilkin/trellis.cpp/releases/tag/v0.8.1)（commit `c0bed38`）。应用会为你的电脑挑选一个变体。

| 变体 | 适用电脑 | 下载 |
|---|---|---|
| `win-x64-cuda13` | Windows，NVIDIA GPU（驱动 580.88 或更新，计算能力 7.5 或更高：RTX 20 系列及之后） | 715 MB（程序 + NVIDIA CUDA 13 运行时） |
| `win-x64-vulkan` | Windows，AMD / Intel / 其他 GPU | 14 MB |
| `linux-x64-cuda13` | Linux x64，NVIDIA GPU（驱动 580.65 或更新），glibc 2.34 及 libstdc++ `GLIBCXX_3.4.30` 或更新（Ubuntu 22.04+），`libgomp.so.1` | 715 MB |
| `linux-x64-vulkan` | Linux x64，配 Vulkan GPU，glibc 2.34 及 libstdc++ `GLIBCXX_3.4.30` 或更新（Ubuntu 22.04+），`libgomp.so.1` 和 `libvulkan.so.1` | 16 MB |

**Linux 为预览版**：尚未在真实 Linux GPU 上测试。

不提供：

- **macOS。** trellis.cpp 能在 Apple silicon 上运行（Metal；上游在 24 GB 的 M5 上测得 512 分辨率模型耗时 9:21），但上游没有发布 macOS 构建版本。需要从源码构建。
- **ROCm** 构建（上游将其标为实验性，且只针对一个 APU，gfx1151）以及面向 Pascal/Volta GPU（计算能力 6–7）的 `cuda12` 构建。AMD GPU 请使用 Vulkan。

Windows 构建需要 Microsoft Visual C++ 2015–2022 运行时（`MSVCP140.dll`，`VCRUNTIME140_1.dll`），大多数 Windows 电脑已经装了；压缩包里并不自带。

应用从不安装驱动或系统库。如果缺少什么，它会告诉你需要安装哪些。

## 许可

- trellis.cpp — MIT，© Piotr Wilkin（[许可证](https://github.com/pwilkin/trellis.cpp/blob/v0.8.1/LICENSE)）。
- 内置的第三方代码，全部编译进发行版二进制文件：ggml（MIT）、xatlas（MIT）、meshoptimizer（MIT）、Fast Quadric Mesh Simplification（MIT）、cpp-httplib（MIT）、stb（MIT 或公有领域）、libwebp（[BSD-3-Clause](https://github.com/webmproject/libwebp/blob/v1.5.0/COPYING)）。
- NVIDIA CUDA 运行时（cudart、cuBLAS），仅存在于 CUDA 变体中——由上游依据 [NVIDIA CUDA EULA](https://docs.nvidia.com/cuda/eula/) 再分发。
- 本包 — MIT。每个模型包各自声明其许可。

必需署名：使用本程序无需署名。发行版压缩包里不含许可文本；如果你再分发这些二进制文件，请自行附上声明：上游的 [LICENSE](https://github.com/pwilkin/trellis.cpp/blob/v0.8.1/LICENSE)、[`thirdparty/`](https://github.com/pwilkin/trellis.cpp/tree/v0.8.1/thirdparty) 下的各项许可、libwebp 的 BSD 声明，以及 CUDA 变体的 NVIDIA CUDA EULA。

限制：运行时没有任何限制。模型包自带限制（见各自说明）。

所有文件都从上游 GitHub 发行版下载。AI Game Dev 不托管这些文件。
````
