visualbruno/ComfyUI-Trellis2

ComfyUI Wrapper for Microsoft Trellis.2 - Native and Compact Structured Latents for 3D Generation

📦 ComfyUI-Trellis2란 무엇인가요?

Microsoft의 TRELLIS.2 3D 생성 파이프라인을 확산 모델을 위한 시각적 노드 기반 UI인 ComfyUI로 가져오는 커뮤니티 관리형 커스텀 노드 팩입니다. 익숙한 ComfyUI 캔버스 내에서 하나 이상의 이미지를 텍스처가 포함된 3D 메시, 다중 뷰 렌더링 및 복셀 기반 재구성 모델로 변환하는 엔드투엔드 워크플로우를 구축할 수 있습니다.

✨ 주요 기능 (변경 로그 기준)

다중 뷰 생성 – Sparse MultiView Generator, ImageCond MultiView Generator, Shape Cascade MultiView Generator 등의 노드를 통해 여러 시점에서 일관된 기하학적 구조를 생성합니다.
메시 텍스처링 및 정교화 – Mesh Texturing Multi-View, Mesh Texturing Pixal3D MultiView, Mesh With Voxel Multi-View Generator를 통해 UV 매핑 텍스처 추가, Pixal3D-T 모델 지원 및 복셀 기반 세부 처리가 가능합니다.
기하학 처리 – 리메싱(remeshing), 스무딩(smoothing) (PyMeshlab, Trimesh), 구멍 채우기(hole filling) (Meshlib, CuMesh), 정점 용접(vertex welding), 법선 스무딩(normal smoothing) 및 **단순화(simplification)**를 위한 노드를 제공합니다.
렌더링 – Render MultiView (Nvdiffrast) 및 Preview 3D를 통해 ComfyUI 내에서 직접 결과를 시각화할 수 있습니다.
고급 샘플러 – 확산 단계를 위한 실험적인 Heun, RK4, RK5 샘플러.
외부 모델 지원 – Facebook의 DINO-v3 비전 모델이 필요하며, 선택적으로 TencentARC/Pixal3D-T(natten 패키지 필요)를 지원합니다.
플랫폼별 wheel – Windows 환경의 Torch 2.7/2.8을 위한 CuMesh, nvdiffrast, nvdiffrec_render, FlexGEMM 및 o_voxel의 사전 컴파일된 바이너리를 제공합니다.

🛠️ 설치 (빠른 시작)

사전 요구 사항
- ComfyUI(표준 또는 포터블 버전)를 설치합니다.
- HuggingFace에서 DINO-v3 모델을 다운로드하여 ComfyUI/models/facebook/dinov3-vitl16-pretrain-lvd1689m에 배치합니다.
- (선택 사항) Pixal3D-T 지원이 필요한 경우, GitHub 저장소에서 natten 패키지를 설치합니다.
제공된 wheel 설치 – 사용 중인 Torch 버전(2.7.0 또는 2.8.0)에 맞는 폴더를 선택하고 README에 표시된 pip install …/*.whl 명령을 실행합니다. 일반 Python 설치와 ComfyUI 포터블 번들용 명령은 다릅니다.

Python 의존성 설치

pip install -r ComfyUI/custom_nodes/ComfyUI-Trellis2/requirements.txt

커스텀 빌드 (선택 사항) – 작성자가 패치한 o_voxel, CuMesh 또는 FlexGEMM 버전이 필요한 경우, 링크된 저장소를 복제하여 설치하십시오.
ComfyUI를 재시작하면 새로운 Trellis2 노드가 Trellis2 카테고리에 나타납니다.

🚀 사용 방법

“PreProcess Image” 노드 추가 (선택적으로 rembg를 사용하여 remove_background 수행).
이미지를 Multi-View Generator에 입력 – 필요한 스타일(Sparse, ImageCond, Shape 등)을 선택합니다.
선택적으로 “Mesh With Voxel … Generator” 실행 – 복셀 표현을 생성한 다음 Voxel to Mesh 노드로 메시로 변환합니다.
기하학적 구조 정교화 – Smooth Mesh, Fill Holes With Meshlib, Weld Vertices 또는 Simplify Trimesh를 사용합니다.
메시 텍스처링 – Mesh Texturing Multi-View (또는 고품질 텍스처 맵을 위한 Pixal3D 전용 노드)를 사용합니다.
렌더링 – *Render MultiView (Nvdiffrast)*로 결과를 렌더링하거나 Preview 3D를 통해 실시간으로 확인합니다.
내보내기 – Export Mesh 노드를 사용합니다. 출력물은 미리보기 노드와 호환되며 표준 3D 형식으로 저장할 수 있습니다.

저장소에는 Projection_Blender_Qwen_XViews, Projection MultiView Texturing 및 Pixal3D 파이프라인과 같은 일반적인 작업을 위한 ComfyUI 그래프가 포함된 example_workflows 폴더가 있습니다.

📚 도움을 받는 곳

Discord 커뮤니티 (감사의 글에 링크됨) – 활발한 사용자들이 워크플로우 팁과 버그 수정 사항을 공유합니다.
“Blackwell Fix” – README에서 언급된 알려진 문제에 대한 커뮤니티 패치.
작성자의 Trellis.2, CuMesh 및 FlexGEMM 포크에는 추가 문서와 최신 버그 수정 사항이 포함되어 있습니다.

🔗 관련 프로젝트

Microsoft/TRELLIS.2 – 다중 뷰 확산 기반 3D 생성을 수행하는 원본 연구 코드.
ComfyUI – 이 래퍼가 플러그인되는 노드 기반 UI.
Pixal3D – 일부 노드에서 사용되는 고품질 3D 모델 데이터셋.

ComfyUI-Trellis2는 시각적 워크플로우를 선호하는 아티스트와 개발자가 Microsoft의 최첨단 3D 확산 파이프라인을 사용할 수 있도록 하는 가교 역할을 합니다. 필요한 컴파일된 확장이 번들로 제공되며, 풍부한 기하학 처리 노드와 예제 그래프가 포함되어 있어 몇 분 안에 텍스처가 포함된 메시 생성을 시작할 수 있습니다.