# 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/ko/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에서 텍스처가 입혀진 3D 모델(PBR 머티리얼을 포함한 GLB)로 만들어 주는 런타임이며, Microsoft TRELLIS.2를 C++/GGML로 포팅한 [trellis.cpp](https://github.com/pwilkin/trellis.cpp)를 사용합니다. 모든 작업은 내 컴퓨터에서 이루어지고, 만드는 데 비용이 들지 않습니다. 이 패키지 자체에는 모델이 없고, 3D 모델 패키지인 [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 사용 개발자에게 적합합니다.

## 무엇을 만들 수 있나요

모델 패키지를 설치하면 다음과 같은 작업을 할 수 있습니다.

- 이미지 한 장으로 텍스처가 입혀진 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 | NVIDIA(CUDA 13) 또는 Vulkan을 지원하는 x64, 프리뷰 |
| 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로 변환하세요.

## 다운로드되는 항목

태그로 고정하고 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 silicon에서 실행됩니다(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 PC에는 이미 설치되어 있습니다. 압축 파일에는 이 런타임이 포함되어 있지 않습니다.

앱은 드라이버나 시스템 라이브러리를 설치하지 않습니다. 무언가 빠져 있으면 무엇을 설치해야 하는지 알려 줍니다.

## 라이선스

- 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가 직접 호스팅하지 않습니다.
````
