# Local 3D generation

> Local 3D generation 執行環境：trellis.cpp 是 Microsoft TRELLIS.2 的 C++ 移植版，能在你自己的 NVIDIA 或 Vulkan GPU 上，把單張影像變成有貼圖的 3D 模型（GLB，含 PBR 材質），每個模型都不收費。可執行 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-hant/packages/aigd.trellis

## 安裝

在專案資料夾中，使用 gamedev CLI：

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

在桌面應用程式中：開啟「套件」視窗（狀態列上的套件圖示），選擇 **瀏覽**，搜尋 `aigd.trellis`，然後點 **加入專案**。更多資訊：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 是執行環境，透過 [trellis.cpp](https://github.com/pwilkin/trellis.cpp)（Microsoft TRELLIS.2 的 C++/GGML 移植版），在這台電腦上、用你自己的 GPU，把單張影像變成有貼圖的 3D 模型（GLB，含 PBR 材質）。所有內容都在你的電腦上產生，而且產生不花任何費用。這個套件本身不含模型：它會執行 3D 模型套件 [TRELLIS.2 4B](https://ai-game.dev/packages/aigd.model3d-trellis2-4b) 與 [Pixal3D](https://ai-game.dev/packages/aigd.model3d-pixal3d)。適合有 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 工作要花幾分鐘；你隨時可以停止它。

## 模型是獨立的套件

這個套件不含任何模型。請從套件瀏覽器安裝模型套件，再從模型面板下載它的檔案。未經你確認不會下載任何東西，而且你會先看到大小。

- `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。

## 會下載哪些內容

上游發行版，以標籤固定並以 sha256 檢查：`pwilkin/trellis.cpp` [`v0.8.1`](https://github.com/pwilkin/trellis.cpp/releases/tag/v0.8.1)（提交 `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 晶片上執行（Metal；上游在配備 24 GB 記憶體的 M5 上測得 res-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 並未自行託管這些檔案。
````
