개요
TRELLIS.2는 고충실도 이미지-투-3D 생성을 위한 대규모 3D 생성 모델로, O-Voxel이라는 필드가 없는 희소 복셀 구조를 도입하여 임의의 토폴로지와 완전한 PBR 재질 모델링을 지원하며, 16배 공간 다운샘플링을 제공합니다.
README 미리보기
\n\n# Native and Compact Structured Latents for 3D Generation\n\n\n\n\n\n\n\nhttps://github.com/user-attachments/assets/63b43a7e-acc7-4c81-a900-6da450527d8f\n\n*(Compressed version due to GitHub size limits. See the full-quality video on our project page!)*\n\n**TRELLIS.2** is a state-of-the-art large 3D generative model (4B parameters) designed for high-fidelity **image-to-3D** generation. It leverages a novel "field-free" sparse voxel structure termed **O-Voxel** to reconstruct and generate arbitrary 3D assets with complex topologies, sharp features, and full PBR materials.\n\n\n## ✨ Features\n\n### 1. High Quality, Resolution & Efficiency\nOur 4B-parameter model generates high-resolution fully textured assets with exceptional fidelity and efficiency using vanilla DiTs. It utilizes a Sparse 3D VAE with 16× spatial downsampling to encode assets into a compact latent space.\n\n| Resolution | Total Time* | Breakdown (Shape + Mat) |\n| :--- | :--- | :--- |\n| **512³** | **~3s** | 2s + 1s |\n| **1024³** | **~17s** | 10s + 7s |\n| **1536³** | **~60s** | 35s + 25s |\n\n*Tested on NVIDIA H100 GPU.\n\n### 2. Arbitrary Topology Handling\nThe **O-Voxel** representation breaks the limits of iso-surface fields. It robustly handles complex structures without lossy conversion:\n* ✅ **Open Surfaces** (e.g., clothing, leaves)\n* ✅ **Non-manifold Geometry**\n* ✅ **Internal Enclosed Structures**\n\n### 3. Rich Texture Modeling\nBeyond basic colors, TRELLIS.2 models arbitrary surface attributes including **Base Color, Roughness, Metallic, and Opacity**, enabling photorealistic rendering and transparency support.\n\n### 4. Minimalist Processing\nData processing is streamlined for instant conversions that are fully **rendering-free** and **optimization-free**.\n* ** 📂 **Please refer to [data_toolkit/README.md](data_toolkit/README.md) for detailed instructions on data preprocessing and dataset organization.**\n\n### 2. Running Training\n\nTraining is managed through the `train.
FAQ (5)
문제 해결TRELLIS에서 알파 채널이 무시되고 내보낸 GLB가 완전히 불투명하게 표시되는 문제를 어떻게 해결하나요?
GLB가 alphaMode='OPAQUE'로 내보내지기 때문에 glTF 뷰어가 텍스처의 알파 채널을 무시하게 됩니다. o-voxel/o_voxel/postprocess.py에서 PBR 머티리얼 구성을 알파 블렌딩과 float baseColorFactor를 사용하도록 변경하세요:
alpha_mode = 'BLEND'
material = trimesh.visual.material.PBRMaterial(
baseColorTexture=Image.fromarray(np.concatenate([base_color, alpha], axis=-1)),
baseColorFactor=np.array([1.0, 1.0, 1.0, 1.0], dtype=np.float32),
metallicRoughnessTexture=Image.fromarray(
np.concatenate([np.zeros_like(metallic), roughness, metallic], axis=-1)
),
metallicFactor=1.0,
roughnessFactor=1.0,
alphaMode=alpha_mode,
doubleSided=True if not remesh else False,
)부드러운 투명도 대신 하드 알파 컷아웃을 원한다면 'BLEND' 대신 'MASK'를 사용하세요. 변경 후 GLB를 다시 내보내세요.
수동 해결 방법으로는, 기존 GLB를 Blender 또는 다른 3D 도구로 가져와 베이스 컬러 텍스처의 알파 출력을 머티리얼의 Alpha/Opacity 입력에 연결하세요. 알파 데이터는 이미 텍스처에 존재하지만 OPAQUE 모드에서는 사용되지 않습니다.
문제 해결V100 GPU에서 "LLVM ERROR: Failed to compute parent layout for slice layout" 오류를 어떻게 해결하나요?
이 오류는 V100 (sm_70)과 같은 pre-Ampere GPU에서 기본 sparse convolution GEMM 알고리즘을 사용할 때 발생합니다. trellis2/modules/sparse/conv/config.py를 편집하여 다음을 변경하세요:
FLEX_GEMM_ALGO = 'masked_implicit_gemm_splitk'를 다음으로:
FLEX_GEMM_ALGO = 'explicit_gemm'그런 다음 파이프라인을 다시 실행하세요. SPARSE_CONV_BACKEND=spconv를 설정하여 크래시를 우회하지 마세요. 이렇게 하면 오류는 사라질 수 있지만 생성된 출력이 아무런 경고 없이 손상될 수 있습니다.
문제 해결왜 Texture Flow Model 학습은 CPU 사용률이 높은 상태로 시작하는 데 수십 분이나 걸리나요?
지연은 basic.py의 run 메서드가 학습이 시작되기 전에 학습 데이터셋을 샘플링하기 때문에 발생합니다. 이 CPU-bound 전처리는 학습 샘플이 100개뿐이더라도 오랜 시간이 걸릴 수 있습니다. 학습이 더 빨리 시작되도록 시작 샘플링 프로세스에서 사용하는 num_samples 설정을 줄이세요.
문제 해결O-Voxel이 하나의 복셀 내부에서 가까이 있거나 분리된 두 컴포넌트를 병합하는 이유는 무엇이며, 이 아티팩트를 어떻게 줄일 수 있나요?
O-Voxel은 각 primal voxel에 대해 하나의 dual vertex만 추정합니다. 두 개의 표면 구성 요소가 같은 셀을 차지하면 QEF 솔루션이 이들을 평균화하는 경향이 있어 구성 요소가 병합될 수 있습니다. 이는 극단적인 경우를 강건하게 처리하는 것이 아니라, 알려진 앨리어싱/토폴로지 한계입니다. 해결 방법: 1024³ 이상과 같이 더 높은 해상도로 추출하거나 복셀화하여, 분리된 구성 요소가 같은 복셀에 들어갈 가능성을 줄입니다. 현재 구현에는 체계적인 수정 방법이 없습니다.
문제 해결**Quick caveat first:** my knowledge of TRELLIS 2 specifically may be incomplete if it released recently, so check the official repo's README for exact requirements. The setup process below is based on the original TRELLIS, which generally carries over.
## Option 1: WSL2 (most reliable on Windows)
The repo is primarily written for Linux, so WSL2 avoids most native-Windows build issues:
1. Install a Windows NVIDIA driver (don't install Linux drivers inside WSL).
2. Run `wsl --install` in PowerShell, then open Ubuntu.
3. Follow the repo's Linux install instructions inside WSL.
## Option 2: Native Windows
**Prerequisites:**
- NVIDIA GPU (the original TRELLIS wanted ~16 GB VRAM; TRELLIS 2 likely needs similar or more)
- Visual Studio Build Tools 2022 with "Desktop development with C++"
- CUDA Toolkit matching your PyTorch build (e.g., 12.4)
- Git and Miniconda
**Steps:**
```powershell
conda create -n trellis python=3.10 -y
conda activate trellis
git clone <TRELLIS-2-repo-url>
cd <repo-folder>
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt
```
**Common Windows pain points:**
- **flash-attn** doesn't build natively on Windows. Either use a community prebuilt wheel, or set the attention backend to xformers if supported (for the original: `set ATTN_BACKEND=xformers`).
- **spconv**: install the prebuilt wheel, e.g. `pip install spconv-cu124`. If you hit issues, `set SPCONV_ALGO=native` before running.
- **CUDA extensions** (nvdiffrast, diffoctreerast, flex_gemm, etc.) compile from source — this is why VS Build Tools and the CUDA Toolkit are required. Make sure `CUDA_HOME` is set.
- If memory is tight, look for low-VRAM / CPU-offload flags in the repo's docs.
**Run:**
```powershell
python app.py
```
Then open the Gradio URL it prints (usually `http://127.0.0.1:7860`).
## Option 3: Community installers
If TRELLIS 2 is recent, check for a Pinokio script or community Windows forks/ports of the repo — these bundle prebuilt dependencies and skip the compilation headaches entirely.
If you tell me your GPU and where the install is failing (exact error message), I can help troubleshoot the specific step.
이 이슈에는 확인된 네이티브 Windows 설정이 없지만, 사용자들은 다음과 같은 해결 방법을 보고했습니다:
1. **Vision of Chaos (프리웨어)**: RTX 4090/5090에서 작동하는 것으로 보고된 Windows 구현을 사용하세요. https://github.com/microsoft/TRELLIS.2/issues/4#issuecomment-3706875330 에서 참조된 설정을 확인하세요.
2. **ComfyUI 통합**: RTX 3090의 경우 https://github.com/visualbruno/ComfyUI-Trellis2 를 사용하세요.
3. **Windows에서 Docker**: https://github.com/camenduru/tostui?tab=readme-ov-file#-tostui---trellis-2 의 컨테이너화된 설정을 실행하세요.
GPU에 맞는 옵션을 선택하세요. 네이티브 또는 ComfyUI 워크플로가 실패하는 경우 Docker가 가장 이식성이 높습니다.