trellis2.mp4

(GitHub 용량 제한으로 인해 압축된 버전입니다. 프로젝트 페이지에서 전체 품질의 영상을 확인하세요!)

TRELLIS.2는 고충실도 image-to-3D 생성을 위해 설계된 최첨단 대규모 3D 생성 모델 (4B 파라미터)입니다. 이 모델은 O-Voxel이라 불리는 새로운 "field-free" 희소 복셀 (sparse voxel) 구조를 활용하여 복잡한 위상 (topology), 날카로운 특징, 그리고 완전한 PBR 재질을 가진 임의의 3D 에셋을 재구성하고 생성합니다.

우리의 4B 파라미터 모델은 vanilla DiTs를 사용하여 뛰어난 충실도와 효율성으로 고해상도의 완전한 텍스처가 입혀진 에셋을 생성합니다. 또한 16배 공간 다운샘플링 (spatial downsampling)을 수행하는 Sparse 3D VAE를 사용하여 에셋을 압축된 잠재 공간 (latent space)으로 인코딩합니다.

*NVIDIA H100 GPU에서 테스트됨.

O-Voxel 표현 방식은 등가면 필드 (iso-surface fields)의 한계를 깨뜨립니다. 손실 없는 변환 없이 복잡한 구조를 견고하게 처리합니다:

• ✅ Open Surfaces (예: 의류, 나뭇잎)
• ✅ Non-manifold Geometry (비매니폴드 기하 구조)
• ✅ Internal Enclosed Structures (내부 폐쇄 구조)

기본 색상을 넘어, TRELLIS.2는 Base Color, Roughness, Metallic, Opacity를 포함한 임의의 표면 속성을 모델링하여 실사 같은 렌더링과 투명도 지원을 가능하게 합니다.

데이터 처리는 완전한 rendering-free 및 optimization-free의 즉각적인 변환을 위해 간소화되었습니다.

< 10s (단일 CPU): 텍스처가 입혀진 메쉬 (Textured Mesh) → O-Voxel
< 100ms (CUDA): O-Voxel → 텍스처가 입혀진 메쉬 (Textured Mesh)

• 논문 공개
• image-to-3D 추론 코드 공개
• 사전 학습된 체크포인트 (4B) 공개
• Hugging Face Spaces 데모
• 형태 조건부 텍스처 생성 (shape-conditioned texture generation) 추론 코드 공개
• 학습 코드 공개

시스템 (System): 코드는 현재 Linux에서만 테스트되었습니다.
하드웨어 (Hardware): 최소 24GB 이상의 메모리를 가진 NVIDIA GPU가 필요합니다. 코드는 NVIDIA A100 및 H100 GPU에서 검증되었습니다.
소프트웨어 (Software):

• 특정 패키지를 컴파일하려면 CUDA Toolkit이 필요합니다. 권장 버전은 12.4입니다.

• 종속성 (dependencies) 관리를 위해 Conda 사용을 권장합니다.

• Python 버전 3.8 이상이 필요합니다.

저장소 (repo) 클론:

git clone -b main https://github.com/microsoft/TRELLIS.2.git --recursive cd TRELLIS.2

종속성 (dependencies) 설치:

다음 명령어를 실행하기 전에 주의할 사항이 있습니다:

• --new-env를 추가하면 trellis2라는 이름의 새로운 conda 환경이 생성됩니다. 기존 conda 환경을 사용하려면 이 플래그를 제거하십시오.
• 기본적으로 trellis2 환경은 CUDA 12.4와 함께 pytorch 2.6.0을 사용합니다. 다른 버전의 CUDA를 사용하려면 --new-env 플래그를 제거하고 필요한 종속성을 수동으로 설치하십시오. 설치 명령어는 PyTorch를 참조하십시오.
• 여러 버전의 CUDA Toolkit이 설치되어 있는 경우, 명령어를 실행하기 전에 CUDA_HOME을 올바른 버전으로 설정해야 합니다. 예를 들어, CUDA Toolkit 12.4와 13.0이 설치되어 있다면, 명령어를 실행하기 전에 export CUDA_HOME=/usr/local/cuda-12.4를 실행할 수 있습니다.
• 기본적으로 코드는 어텐션 (attention)을 위해 flash-attn 백엔드를 사용합니다. flash-attn을 지원하지 않는 GPU (예: NVIDIA V100)의 경우, xformers를 수동으로 설치하고 코드를 실행하기 전에 ATTN_BACKEND 환경 변수를 xformers로 설정할 수 있습니다. 자세한 내용은 최소 예제 (Minimal Example)를 참조하십시오.
• 종속성 (dependencies)의 수가 많기 때문에 설치에 시간이 다소 걸릴 수 있습니다. 인내심을 갖고 기다려 주십시오. 문제가 발생할 경우, 한 번에 하나의 플래그만 지정하여 종속성을 하나씩 설치해 볼 수 있습니다.
• 설치 중 문제가 발생하면 언제든지 이슈 (issue)를 제기하거나 저희에게 연락해 주십시오.

trellis2라는 이름의 새로운 conda 환경 생성

및 의존성 (dependencies)을 설치합니다: . ./setup.sh --new-env --basic --flash-attn --nvdiffrast --nvdiffrec --cumesh --o-voxel --flexgemm

setup.sh의 상세한 사용법은 다음 명령어를 실행하여 확인할 수 있습니다: . ./setup.sh --help

. 사용법: setup.sh [OPTIONS] 옵션: -h, --help 이 도움말 메시지를 표시합니다 --new-env 새로운 conda 환경을 생성합니다 --basic 기본 의존성을 설치합니다 --flash-attn flash-attention을 설치합니다 --cumesh cumesh를 설치합니다 --o-voxel o-voxel을 설치합니다 --flexgemm flexgemm을 설치합니다 --nvdiffrast nvdiffrast를 설치합니다 --nvdiffrec nvdiffrec를 설치합니다

사전 학습된 모델(pretrained model)인 TRELLIS.2-4B는 Hugging Face에서 사용할 수 있습니다. 자세한 내용은 해당 모델 카드(model card)를 참조하십시오.

다음은 3D 에셋 (asset) 생성을 위해 사전 학습된 모델을 사용하는 예시입니다.

import os
os.environ['OPENCV_IO_ENABLE_OPENEXR'] = '1'
os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "expandable_segments:True" # GPU 메모리를 절약할 수 있습니다
...

실행 시, 스크립트는 다음과 같은 파일들을 생성합니다:

sample.mp4
: PBR 재질 (materials) 및 환경 조명 (environmental lighting)과 함께 생성된 3D 에셋을 시각화한 비디오입니다.

sample.glb
: GLB 형식으로 추출된 PBR 준비 완료된 3D 에셋입니다.

참고: .glb 파일은 기본적으로 OPAQUE 모드로 내보내집니다. 텍스처 맵 (texture map) 내에 알파 채널 (alpha channel)이 보존되어 있지만, 초기에는 활성화되지 않습니다. 투명도를 적용하려면 에셋을 3D 소프트웨어로 가져온 후, 텍스처의 알파 채널을 재질의 불투명도 (opacity) 또는 알파 입력에 수동으로 연결하십시오.

app.py는 이미지에서 3D 에셋 생성을 위한 간단한 웹 데모 (web demo)를 제공합니다. 다음 명령어로 데모를 실행할 수 있습니다:

python app.py

그 후, 터미널에 표시된 주소로 데모에 접속할 수 있습니다.

특정 3D 형상에 대한 PBR 텍스처를 생성하는 예시는 example_texturing.py를 참조하십시오. 또한, app_texturing.py를 사용하여 PBR 텍스처 생성을 위한 웹 데모를 실행할 수 있습니다.

저희는 전체 학습 코드베이스 (codebase)를 제공하여, 사용자가 TRELLIS.2를 처음부터 학습시키거나 커스텀 데이터셋으로 미세 조정 (fine-tune)할 수 있도록 합니다.

학습을 시작하기 전에, 가공되지 않은 3D 에셋 (raw 3D assets)은 반드시 O-Voxel 표현 방식 (representation)으로 변환되어야 합니다. 이 프로세스에는 메쉬 변환 (mesh conversion), 압축된 구조적 잠재 표현 생성 (compact structured latent generation), 그리고 메타데이터 준비가 포함됩니다.

📂

데이터 전처리 (data preprocessing) 및 데이터셋 구성에 대한 자세한 지침은 data_toolkit/README.md를 참조하십시오.

학습은 train.py 스크립트를 통해 관리되며, 이 스크립트는 실험 설정을 위해 여러 명령줄 인자 (command-line arguments)를 허용합니다:

--config: 실험 설정 파일 (configuration file) 경로.
--output_dir: 학습 결과물이 저장될 디렉토리.
--load_dir: 체크포인트 (checkpoint)를 불러올 디렉토리 (output_dir이 기본값).
--ckpt: 재개할 체크포인트 단계 (최신 단계가 기본값).
--data_dir: 데이터셋 경로 또는 데이터셋 위치를 지정하는 JSON 문자열.
--auto_retry: 실패 시 자동 재시도 횟수.
--tryrun: 실제 학습 없이 드라이 런 (dry run) 수행.
--profile: 학습 프로파일링 (profiling) 활성화.
--num_nodes: 분산 학습 (distributed training)을 위한 노드 수.
--node_rank: 현재 노드의 랭크 (rank).
--num_gpus: 노드당 GPU 수 (사용 가능한 모든 GPU가 기본값).
--master_addr: 분산 학습을 위한 마스터 노드 주소.
--master_port: 분산 학습 통신을 위한 포트.

형태 (shape) SC-VAE를 학습하려면 다음을 실행하십시오:

python train.py \
--config configs/scvae/shape_vae_next_dc_f16c32_fp16.json \
--output_dir results/shape_vae_next_dc_f16c32_fp16 \
...

이 명령은 shape_vae_next_dc_f16c32_fp16.json 설정을 사용하여 Objaverse-XL 데이터셋에서 형태 SC-VAE를 학습합니다. 학습 결과는 results/shape_vae_next_dc_f16c32_fp16에 저장됩니다.

데이터셋은 JSON 문자열로 지정되며, 각 데이터셋 항목에는 다음이 포함됩니다:

base: 데이터셋의 루트 디렉토리.
mesh_dump: 전처리된 메쉬 덤프 (mesh dumps)가 포함된 디렉토리.
dual_grid: 미리 계산된 듀얼 그리드 (dual-grid) 표현이 포함된 디렉토리.
asset_stats

: 미리 계산된 에셋 통계 (asset statistics)가 포함된 디렉토리.

더 높은 해상도에서 모델을 미세 조정 (fine-tune)하려면, shape_vae_next_dc_f16c32_fp16_ft_512.json 설정을 사용하세요. finetune_ckpt 필드를 업데이트하고 그에 따라 데이터셋 경로를 조정해야 함을 기억하세요.

텍스처 SC-VAE를 학습하려면 다음을 실행하세요:

python train.py \
--config configs/scvae/tex_vae_next_dc_f16c32_fp16.json \
--output_dir results/tex_vae_next_dc_f16c32_fp16 \
...

희소 구조 흐름 (sparse structure flow) 모델을 학습하려면 다음을 실행하세요:

python train.py \
--config configs/gen/ss_flow_img_dit_1_3B_64_bf16.json \
--output_dir results/ss_flow_img_dit_1_3B_64_bf16 \
...

이 명령은 지정된 설정 파일을 사용하여 Objaverse-XL 데이터셋에서 희소 구조 흐름 (sparse-structure flow) 모델을 학습합니다. 출력 결과는 results/ss_flow_img_dit_1_3B_64_bf16에 저장됩니다.

데이터셋 설정에는 다음이 포함됩니다:

base: 루트 데이터셋 디렉토리.
ss_latent: 미리 계산된 희소 구조 잠재 표현 (sparse-structure latents)이 포함된 디렉토리.
render_cond: 조건부 렌더링 이미지 (conditional rendering images)가 포함된 디렉토리.

형태 (shape) 및 텍스처 생성을 위한 2단계 및 3단계 흐름 (flow) 모델은 다음 설정을 사용하여 학습할 수 있습니다:

• 형태 흐름 (Shape flow):
  slat_flow_img2shape_dit_1_3B_512_bf16.json

• 텍스처 흐름 (Texture flow):
  slat_flow_imgshape2tex_dit_1_3B_512_bf16.json

명령어 예시:

# 형태 흐름 (Shape flow) 모델
python train.py \
--config configs/gen/slat_flow_img2shape_dit_1_3B_512_bf16.json \
...

다음 설정 파일에서 finetune_ckpt 필드를 업데이트하고 그에 따라 데이터셋 경로를 조정함으로써 더 높은 해상도의 미세 조정 (fine-tuning)을 수행할 수 있습니다:

slat_flow_img2shape_dit_1_3B_512_bf16_ft1024.json

slat_flow_imgshape2tex_dit_1_3B_512_bf16_ft1024.json

TRELLIS.2는 저희 팀이 개발한 여러 전문화된 고성능 패키지들을 기반으로 구축되었습니다:

O-Voxel: 텍스처가 입혀진 메쉬 (textured meshes)와 O-Voxel 표현 방식 간의 변환 로직을 처리하는 핵심 라이브러리로, 즉각적인 양방향 변환을 보장합니다. FlexGEMM: Triton을 기반으로 한 효율적인 희소 합성곱 (sparse convolution) 구현체로, 희소 복셀 (sparse voxel) 구조의 빠른 처리를 가능하게 합니다. CuMesh: 고속 후처리 (post-processing), 리메싱 (remeshing), 데시메이션 (decimation) 및 UV 언래핑 (UV-unwrapping)에 사용되는 CUDA 가속 메쉬 유틸리티입니다.

이 모델과 코드는 MIT License 하에 공개됩니다.

특정 의존성 라이브러리들은 별도의 라이선스 약관에 따라 작동하므로 주의하시기 바랍니다:

nvdiffrast: 생성된 3D 에셋의 렌더링 (rendering)을 위해 사용됩니다. 이 패키지는 자체 라이선스의 적용을 받습니다. -
nvdiffrec: PBR 재질을 위한 split-sum 렌더러를 구현합니다. 이 패키지는 자체 라이선스의 적용을 받습니다.

만약 이 모델이 귀하의 연구에 유용하다면, 저희의 연구를 인용해 주세요:

@article{xiang2025trellis2,
title={Native and Compact Structured Latents for 3D Generation},
...