# TRELLIS.2 4B (3D 모델)

> 로컬 이미지→3D: Microsoft의 TRELLIS.2 4B는 이미지 한 장을 텍스처가 있는 3D 모델(GLB, UV 아틀라스 및 PBR 머티리얼 포함)로 만들어 게임 에셋에 활용합니다. 해상도는 512, 1024 또는 1536입니다. NVIDIA 또는 Vulkan GPU와 16 GB 비디오 메모리에서 trellis.cpp로 실행됩니다. MIT이며, 이미지 인코더에는 Meta의 DINOv3 라이선스가 적용됩니다.

- Id: `aigd.model3d-trellis2-4b`
- 소스: 공식 (자사 `aigd.*`)
- 카테고리: 3D
- 게시자: AI Game Dev (`aigd`), 인증됨
- 최신 버전: 1.0.5 (2026-11-22 게시)
- 라이선스: SEE LICENSE IN README.md
- AI Game Dev 앱 필요: `>=0.32.0-beta.6`
- 네이티브 코드: 아니요
- 평점: 아직 평가 없음
- HTML 페이지: https://ai-game.dev/ko/packages/aigd.model3d-trellis2-4b

## 설치

gamedev CLI를 사용한다면 프로젝트 폴더에서:

```bash
gamedev pkg add aigd.model3d-trellis2-4b
```

데스크톱 앱에서 Packages 창을 열고(상태 표시줄의 패키지 아이콘) **Browse**를 선택한 뒤 `aigd.model3d-trellis2-4b`를 검색하고 **Add to Project**를 클릭합니다. 자세히: https://ai-game.dev/docs/wiki/app/packages

## 버전

| 버전 | 게시일 | 앱 필요 | 참고 |
|---|---|---|---|
| 1.0.5 | 2026-11-22 | `>=0.32.0-beta.6` | 최신 |
| 1.0.4 | 2026-11-21 | `>=0.32.0-beta.6` | - |

## 설명

````markdown
# TRELLIS.2 4B (`aigd.model3d-trellis2-4b`)

TRELLIS.2 4B는 Microsoft의 [TRELLIS.2](https://huggingface.co/microsoft/TRELLIS.2-4B) 이미지→3D 모델입니다. 이미지 한 장을 텍스처가 있는 3D 모델로 바꿉니다. 즉 UV 아틀라스와 PBR 머티리얼(베이스 컬러, 메탈릭, 러프니스)을 갖춘 GLB이며, 해상도 1024에서 약 300,000개의 면을 생성합니다. AI Game Dev에서는 **[로컬 3D 생성](https://ai-game.dev/packages/aigd.trellis)**(`aigd.trellis`, trellis.cpp)을 통해 NVIDIA(CUDA) 또는 Vulkan GPU와 16 GB 비디오 메모리에서 GPU로 실행됩니다. 클라우드 서비스 없이 콘셉트 아트에서 텍스처가 있는 에셋을 만들고 싶은 개발자에게 적합합니다.

## 만들 수 있는 것

- 사진 한 장이나 콘셉트 이미지 한 장으로 텍스처가 있고 PBR을 지원하는 소품, 무기, 가구, 탈것, 캐릭터를 만들 수 있습니다.
- 일반 사진으로 모델을 만들 수 있습니다. 배경은 자동으로 제거됩니다(BiRefNet).
- 해상도 512의 가벼운 초안 또는 1536의 더 자세한 모델을 만들 수 있습니다.

## 요청 예시

- “`Concepts/potion.png`을(를) TRELLIS.2로 텍스처가 있는 3D 모델로 만들어 주세요.”
- “먼저 이 오래된 라디오 사진으로 해상도 512의 텍스처가 있는 GLB를 만들어 주세요. 빠르게 확인하고 싶어요.”
- “기사 콘셉트의 3D 모델을 1536으로 생성해 주세요.”

## 주요 특징

|  |  |
|---|---|
| 모델 ID | `aigd.model3d-trellis2-4b.f16` |
| 작업 | 이미지 → 3D (PNG 또는 JPEG 이미지 한 장) |
| 출력 | UV 아틀라스와 PBR 머티리얼이 포함된 텍스처 GLB(PNG 텍스처) |
| 해상도 | 512, 1024(기본값), 1536 |
| 스텝 | 기본 12 |
| 실행 환경 | 16 GB 비디오 메모리를 갖춘 NVIDIA(CUDA) 또는 Vulkan GPU |
| 다운로드 | 16.5 GB, 파일 10개 |
| 라이선스 | MIT이며, DINOv3 인코더에는 Meta의 DINOv3 License가 적용됩니다 |

## TRELLIS.2 또는 Pixal3D

둘 다 [로컬 3D 생성](https://ai-game.dev/packages/aigd.trellis)에서 실행되며 텍스처 GLB를 만듭니다.

- **TRELLIS.2 4B**(이 패키지): 기본 모델이며, 더 가벼운 512 해상도도 지원합니다.
- **[Pixal3D](https://ai-game.dev/packages/aigd.model3d-pixal3d)**: Tencent ARC의 TRELLIS.2 파인튜닝 모델로, 사진의 실루엣을 더 가깝게 따릅니다. 해상도는 1024와 1536만 지원합니다. TRELLIS.2와 파일 3.5 GB를 공유하므로 둘을 함께 설치하면 약 27 GB입니다.

NVIDIA GPU에서 텍스처 없는 메시가 필요하다면 [TripoSG](https://ai-game.dev/packages/aigd.model3d-triposg), [Hunyuan3D-2.1 Shape](https://ai-game.dev/packages/aigd.model3d-hunyuan3d-2-1-shape), [Step1X-3D Geometry](https://ai-game.dev/packages/aigd.model3d-step1x-3d-geometry)을 참고하세요.

## 제한 사항과 측정값

- **입력:** 객체 하나가 담긴 PNG 또는 JPEG 이미지 한 장입니다. 배경은 자동으로 제거되므로(BiRefNet) 일반 사진도 사용할 수 있으며, 이미 투명도가 있는 이미지는 그대로 유지됩니다.
- **출력:** 자체 포함형 GLB 하나(PNG 텍스처)입니다.
- **해상도:** 512(가벼움), 1024(기본값, 512→1024 캐스케이드), 1536입니다.
- **항상 텍스처 포함:** 지오메트리만 생성하는 실행은 제공되지 않습니다. trellis.cpp v0.8.1은 텍스처링 중에만 메시를 단순화하므로, 텍스처가 없으면 원시 디코딩 메시(측정된 15.67 million개의 면)를 출력하며 이는 앱의 GLB 제한을 초과합니다. 그 외에 이를 단순화하는 런타임 플래그는 없습니다.
- **비트 단위로 동일하지 않음:** 같은 이미지, 시드, 설정이라도 비트 단위로 동일한 GLB가 나오지 않습니다. 시드 42로 CUDA에서 두 번 실행했을 때 둘 다 유효한 GLB를 생성했지만 지오메트리와 SHA-256 해시가 달랐으며, 기록된 시드는 요청 설정을 식별합니다.
- **하드웨어:** **16 GB** 비디오 메모리를 갖춘 NVIDIA(CUDA) 또는 Vulkan GPU입니다. 업스트림은 1024 캐스케이드가 16 GB 카드에서 실행된다고 밝히며, 모델 로드를 포함해 RTX 5060 Ti 16 GB에서 모델당 3:16–7:23(Radeon 8060S iGPU에서는 6:09–12:39)을 측정했습니다.
- **다운로드:** 16.5 GB, 파일 10개입니다.

Windows에서 RTX 4090을 사용해 시드 42와 12스텝으로 이미지 한 장을 생성했을 때 다음과 같은 엔드투엔드 시간과 장치 전체 VRAM 최고치가 나왔습니다. 시작 VRAM 사용량은 3,676–4,819 MiB였습니다.

| 백엔드 | 해상도 | 시간 | 최고 VRAM |
|---|---:|---:|---:|
| CUDA | 512 | 60.77 s | 7,321 MiB |
| CUDA | 1024 | 290.88 s | 10,166 MiB |
| CUDA | 1536 | 687.35 s | 14,857 MiB |
| Vulkan | 512 | 147.04 s | 7,558 MiB |
| Vulkan | 1024 | 710.54 s | 13,447 MiB |

## 다운로드되는 항목

모두 [`ilintar/trellis2-gguf`](https://huggingface.co/ilintar/trellis2-gguf)의 리비전 `a57397bd3d351599d9729fc144b3f87c3f87d65b`에서 가져오며(F16 가중치, F32 노름), sha256으로 확인합니다:

| 파일 | 설명 | 원본 모델 | 라이선스 |
|---|---|---|---|
| `ss_flow`, `shape_flow_512`, `shape_flow_1024`, `tex_flow_512`, `tex_flow_1024` | 세 단계의 1.3B 플로 트랜스포머(형상과 텍스처 각각 두 해상도) | [microsoft/TRELLIS.2-4B](https://huggingface.co/microsoft/TRELLIS.2-4B) | MIT |
| `shape_dec`, `tex_dec` | 형상 및 텍스처 디코더 | microsoft/TRELLIS.2-4B | MIT |
| `ss_dec` | 희소 구조 디코더 | [microsoft/TRELLIS-image-large](https://huggingface.co/microsoft/TRELLIS-image-large) | MIT |
| `dinov3` | DINOv3 ViT-L/16 이미지 인코더 | [timm/vit_large_patch16_dinov3.lvd1689m](https://huggingface.co/timm/vit_large_patch16_dinov3.lvd1689m)(Meta의 DINOv3) | [DINOv3 License](https://ai.meta.com/resources/models-and-libraries/dinov3-license/) |
| `birefnet` | 배경 제거 | [ZhengPeng7/BiRefNet](https://huggingface.co/ZhengPeng7/BiRefNet) | MIT |

## 라이선스

TRELLIS.2는 **MIT**입니다. 상업적 사용이 허용되며 생성한 것에 대한 권리는 사용자에게 있습니다(아래 DINOv3 인코더의 사용 제한과 관련하여 앱이 다운로드 전에 라이선스 동의를 요청합니다). MIT가 아닌 구성 요소가 하나 있습니다:

- **DINOv3 이미지 인코더**(`dinov3.gguf`) — Meta의 [DINOv3 License](https://ai.meta.com/resources/models-and-libraries/dinov3-license/)(2025년 8월 14일). 상업적 사용을 허용하는 무료, 전 세계, 로열티 없는 라이선스이며 다음 조건이 있습니다:
  - 인코더 또는 그 파생물을 배포하는 경우 DINOv3 License 사본을 포함하고 관련 웹사이트, 사용자 인터페이스, 블로그 게시물, 소개 페이지 또는 제품 문서에 **"Built with DINOv3"을(를) 눈에 띄게 표시**해야 합니다.
  - ITAR의 적용을 받는 활동이나 무역 통제로 금지된 최종 사용에는 사용할 수 없습니다. 여기에는 군사 또는 전쟁, 원자력 산업 또는 응용, 간첩 행위, 총기 및 불법 무기가 포함됩니다. 무역 제재의 대상이 아니어야 합니다.
  - 기본 구성 요소를 리버스 엔지니어링할 수 없습니다. 라이선스를 위반하거나 자료와 관련해 Meta를 상대로 소송을 제기하면 Meta는 라이선스를 종료할 수 있습니다.
- GGUF 리포지토리 `ilintar/trellis2-gguf`는 라이선스를 "other"로 선언하고 원본 모델을 가리키며, 자체 조건을 추가하지 않습니다.
- Meta의 라이선스 페이지(2025년 8월 14일, 위에 링크됨)에는 "Built with DINOv3" 의무가 포함되어 있지만, DINOv3 코드와 함께 제공되는 사본(2025년 8월 19일)에는 포함되어 있지 않습니다. 이 패키지는 더 엄격한 쪽을 따릅니다.

필수 저작자 표시 문구:

> TRELLIS.2 © Microsoft Corporation (MIT). Built with DINOv3 (DINOv3 License, © Meta Platforms).
> BiRefNet © ZhengPeng7 (MIT).

제한 사항을 분명히 하면 다음과 같습니다. 위에 나온 DINOv3 저작자 표시와 군사/무기/무역 통제 금지입니다. 매출 상한도, 지역 제한도, 워터마크도 없습니다.

모든 파일은 Hugging Face에서 다운로드됩니다. AI Game Dev는 해당 파일을 호스팅하지 않습니다. 모델을 다운로드하면 해당 라이선스에 동의하게 됩니다.
````
