ComfyUI-TRELLIS2: Transform Images Into 3D Meshes Instantly

Turn any 2D image into production-ready 3D assets with PBR materials in minutes—not hours.

3D content creation has always been the bottleneck. Artists spend days modeling, texturing, and optimizing a single asset. Game studios hemorrhage budgets on asset pipelines. Independent creators hit a wall when their vision demands three-dimensional reality. What if you could generate high-quality 3D meshes directly from concept art, photos, or sketches? No manual modeling. No complex software. Just results.

Enter ComfyUI-TRELLIS2—the revolutionary wrapper that brings Microsoft's cutting-edge TRELLIS.2 model into your ComfyUI workflow. This isn't another experimental toy. It's a production-ready bridge to state-of-the-art image-to-3D generation that outputs meshes with physically based rendering materials. In this deep dive, you'll discover how to install, configure, and master this essential tool. We'll walk through real code examples, explore advanced optimization techniques, and reveal why this package is dominating conversations in 3D AI communities.

What Is ComfyUI-TRELLIS2?

ComfyUI-TRELLIS2 is a custom node package that integrates Microsoft's TRELLIS.2 model directly into ComfyUI's visual workflow environment. Created by developer Andrea Pozzetti, this wrapper transforms the powerful but complex TRELLIS.2 architecture into drag-and-drop nodes that any ComfyUI user can leverage immediately.

TRELLIS.2 itself represents a breakthrough in 3D generative AI. Unlike earlier models that produced voxel-based outputs or low-resolution meshes, TRELLIS.2 generates high-fidelity 3D meshes with complete PBR material sets—including diffuse, normal, roughness, and metallic maps—from a single input image. The model uses a sophisticated diffusion-based approach trained on millions of 3D assets, understanding geometry, topology, and material properties simultaneously.

The significance? Democratization of 3D asset creation. Concept artists can instantly prototype characters. E-commerce platforms can generate 3D product views from photos. Game developers can populate worlds with unique props without hiring an army of modelers. The repository has gained rapid traction because it solves a genuine pipeline problem: making advanced AI accessible through ComfyUI's intuitive interface.

Andrea Pozzetti's wrapper handles all the heavy lifting—model loading, inference optimization, and output formatting—so you focus on creativity, not configuration. It's trending because it works. The live test gallery showcases diverse examples from stylized characters to realistic objects, proving versatility across art styles.

Key Features That Make It Essential

Seamless ComfyUI Integration The package installs as native ComfyUI nodes. No external scripts. No command-line gymnastics. You get dedicated nodes for image preprocessing, mesh generation, and material extraction that plug directly into existing workflows. This integration preserves ComfyUI's real-time preview system, letting you visualize parameters instantly.

State-of-the-Art TRELLIS.2 Model You're tapping into Microsoft's research-grade architecture. The model understands occlusion, depth, and surface properties from a single viewpoint. It doesn't just extrude shapes—it infers complete 3D structure, generating plausible geometry for hidden regions based on learned patterns from massive 3D datasets.

Production-Ready PBR Materials Every mesh comes with a full Physically Based Rendering material suite. Diffuse maps for color, normal maps for surface detail, roughness for micro-surface scattering, and metallic maps for reflectivity. These materials work immediately in Blender, Unity, Unreal Engine, and any PBR-compliant renderer. No manual retexturing required.

Intelligent Mesh Optimization The wrapper automatically performs remeshing and decimation based on target polygon budgets. Generate hero assets at 50k polygons or background props at 5k—all from the same node. The system balances detail preservation with performance, crucial for real-time applications.

Batch Processing Power Process entire folders of images automatically. The node accepts batch inputs, applying consistent settings across hundreds of source images. This transforms weeks of asset creation into overnight jobs. Perfect for generating variant props or processing product catalogs.

Advanced Parameter Control Fine-tune sampling steps, guidance scale, and mesh resolution through exposed parameters. Control material quality separately from geometry detail. Adjust UV unwrapping strategies for specific pipeline needs. These controls give technical artists the precision they demand.

Memory-Efficient Inference Smart GPU memory management prevents crashes on consumer hardware. The wrapper implements gradient checkpointing and progressive loading for large models. Run generation on 8GB VRAM cards without sacrificing quality through intelligent tiling and caching strategies.

Real-World Use Cases That Shine

Indie Game Development A solo developer needs 50 unique environmental props for a forest level. Instead of weeks of modeling, they batch-process concept art sketches through ComfyUI-TRELLIS2. Each sketch becomes a textured 3D model in under two minutes. The developer spends time polishing hero assets, not creating background clutter. Result: Production-ready asset library in a weekend.

E-Commerce Product Visualization An online furniture retailer wants interactive 3D views for 200 products. Traditional photogrammetry requires studio setup and hours per item. With ComfyUI-TRELLIS2, they feed product photos into an automated workflow that generates clean meshes and materials. Result: 3D product configurator launched in days, not months, boosting conversion rates by 40%.

Concept Art Pipeline A film studio's art director creates character designs in 2D. The 3D department previously rebuilt each design from scratch for previsualization. Now, designs flow through ComfyUI-TRELLIS2 nodes, generating base meshes that modelers refine. Result: Concept-to-3D time reduced from 5 days to 4 hours, enabling faster creative iteration.

Architectural Prototyping An architect photographs a building facade and needs a 3D model for client VR walkthroughs. Manual modeling captures every detail. ComfyUI-TRELLIS2 generates the structural mesh and material maps from a single photo. Result: Immersive client presentations created in hours, winning more projects through rapid visualization.

NFT and Digital Art Creation A digital artist creates 2D character collections. They use ComfyUI-TRELLIS2 to generate 3D versions for metaverse integration. The batch system processes entire collections automatically, maintaining stylistic consistency. Result: Expanded product offerings and new revenue streams without hiring 3D artists.

Step-by-Step Installation & Setup Guide

Prerequisites

Before installing, verify your system meets these requirements:

• ComfyUI installed and running (latest version recommended)
• Python 3.10+ with pip package manager
• CUDA-capable GPU with minimum 8GB VRAM (12GB+ recommended for high-resolution outputs)
• Git for repository cloning
• At least 20GB free disk space for model files

Method 1: ComfyUI Manager (Recommended)

This one-click method handles dependencies automatically:

1. Launch ComfyUI and open the Manager tab
2. Click Install Custom Nodes in the sidebar
3. Type "ComfyUI-TRELLIS2" in the search field
4. Click the install button next to the correct result
5. Wait for the process to complete (5-10 minutes on first install)
6. Restart ComfyUI completely—this is critical for node registration
7. Verify installation by checking for TRELLIS2 category in the node menu

Method 2: Manual Installation

For advanced users or debugging:

# Navigate to your ComfyUI custom_nodes directory
cd ComfyUI/custom_nodes

# Clone the repository
git clone https://github.com/PozzettiAndrea/ComfyUI-TRELLIS2.git

# Enter the directory
cd ComfyUI-TRELLIS2

# Install Python dependencies
pip install -r requirements.txt

# Download TRELLIS.2 model files
python download_models.py --all

# Return to ComfyUI root and restart
cd ../..
python main.py

Post-Installation Configuration

After installation, configure these settings for optimal performance:

1. GPU Memory Allocation: In ComfyUI's extra_model_config.yaml, set gpu_memory_limit to 80% of your VRAM
2. Model Cache Path: Specify a fast SSD location for model caching in trellis2_config.json
3. Output Directory: Set your preferred mesh export folder in the node properties panel
4. Verify Setup: Run the included test_workflow.json to confirm all nodes function correctly

Real Code Examples from the Repository

Example 1: Basic Node Registration Structure

This snippet shows how the wrapper registers TRELLIS2 nodes within ComfyUI's system:

# nodes.py - Core node registration for ComfyUI-TRELLIS2
from .trellis2_processor import Trellis2ImageTo3D
import folder_paths

# Register custom node category and mappings
NODE_CLASS_MAPPINGS = {
    "Trellis2ImageTo3D": Trellis2ImageTo3D,
    "Trellis2BatchProcessor": Trellis2BatchProcessor,
    "Trellis2MaterialExtractor": Trellis2MaterialExtractor
}

NODE_DISPLAY_NAME_MAPPINGS = {
    "Trellis2ImageTo3D": "TRELLIS2 Image to 3D",
    "Trellis2BatchProcessor": "TRELLIS2 Batch Processor",
    "Trellis2MaterialExtractor": "TRELLIS2 Material Extractor"
}

# Add custom output directory for generated meshes
folder_paths.folder_names_and_paths["trellis2_meshes"] = (
    ["output/trellis2_meshes"],
    {".obj", ".gltf", ".fbx"}
)

__all__ = ['NODE_CLASS_MAPPINGS', 'NODE_DISPLAY_NAME_MAPPINGS']

Explanation: This code registers three core nodes with ComfyUI. The NODE_CLASS_MAPPINGS dictionary links internal Python classes to node identifiers, while NODE_DISPLAY_NAME_MAPPINGS provides user-friendly names. The folder_paths modification ensures generated meshes save to a dedicated directory with proper file extensions recognized by ComfyUI's file system.

Example 2: Core Image-to-3D Processing Logic

The main inference function demonstrates how the wrapper interfaces with TRELLIS.2:

# trellis2_processor.py - Main processing class
import torch
from trellis2.model import Trellis2Pipeline
from trellis2.utils import postprocess_mesh

class Trellis2ImageTo3D:
    def __init__(self):
        self.pipeline = None
        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
    
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {
                "image": ("IMAGE",),
                "mesh_resolution": (["low", "medium", "high", "ultra"],),
                "guidance_scale": ("FLOAT", {"default": 7.5, "min": 1.0, "max": 20.0}),
                "num_inference_steps": ("INT", {"default": 50, "min": 10, "max": 100}),
            },
            "optional": {
                "seed": ("INT", {"default": 0, "min": 0, "max": 0xffffffffffffffff}),
            }
        }
    
    RETURN_TYPES = ("MESH", "MATERIAL", "STRING")
    RETURN_NAMES = ("mesh", "material_maps", "file_path")
    FUNCTION = "generate_3d"
    CATEGORY = "TRELLIS2"
    
    def generate_3d(self, image, mesh_resolution, guidance_scale, 
                    num_inference_steps, seed=0):
        # Lazy-load pipeline on first use
        if self.pipeline is None:
            self.pipeline = Trellis2Pipeline.from_pretrained(
                "microsoft/TRELLIS-2-Base",
                torch_dtype=torch.float16
            ).to(self.device)
        
        # Preprocess image tensor to PIL format
        pil_image = self._tensor_to_pil(image)
        
        # Generate 3D mesh with materials
        with torch.no_grad():
            output = self.pipeline(
                image=pil_image,
                resolution=mesh_resolution,
                guidance_scale=guidance_scale,
                num_inference_steps=num_inference_steps,
                generator=torch.Generator().manual_seed(seed)
            )
        
        # Post-process and save mesh
        mesh_path = postprocess_mesh(
            output,
            save_dir="output/trellis2_meshes",
            format="gltf",
            optimize=True
        )
        
        return (output.mesh, output.materials, mesh_path)

Explanation: This class defines the core node interface. INPUT_TYPES specifies the parameters exposed in ComfyUI—image input, quality settings, and sampling controls. The generate_3d method handles lazy model loading (saving VRAM), image preprocessing, inference through TRELLIS.2, and post-processing. The postprocess_mesh function optimizes topology and saves files in glTF format for broad compatibility.

Example 3: Workflow JSON Configuration

This example shows a complete ComfyUI workflow configuration:

{
  "1": {
    "inputs": {
      "image": "example_character.png",
      "mesh_resolution": "high",
      "guidance_scale": 8.0,
      "num_inference_steps": 60,
      "seed": 42
    },
    "class_type": "Trellis2ImageTo3D",
    "_meta": {
      "title": "TRELLIS2 Image to 3D"
    }
  },
  "2": {
    "inputs": {
      "mesh": ["1", 0],
      "material_maps": ["1", 1],
      "export_format": "gltf",
      "apply_decimation": true,
      "target_polycount": 25000
    },
    "class_type": "Trellis2MaterialExtractor",
    "_meta": {
      "title": "TRELLIS2 Material Extractor"
    }
  },
  "3": {
    "inputs": {
      "mesh_path": ["2", 2],
      "preview_quality": "high"
    },
    "class_type": "Trellis2PreviewNode",
    "_meta": {
      "title": "Preview 3D Mesh"
    }
  }
}

Explanation: This JSON defines a three-node workflow. Node 1 processes the source image with high-quality settings. Node 2 takes the generated mesh and materials, applies polygon decimation to 25k triangles, and exports as glTF. Node 3 creates an interactive 3D preview within ComfyUI. The ["1", 0] syntax connects node outputs to inputs, creating a visual data flow.

Advanced Usage & Best Practices

Optimize Inference Speed Enable torch.compile() on the pipeline for 30-40% speedup after the first run. Set enable_model_cpu_offload=True if VRAM is limited—this streams model components between CPU and GPU as needed, slightly slower but memory-safe.

Batch Processing Strategy When processing hundreds of images, use the Batch Processor node with max_batch_size=4 to prevent OOM errors. Process in chunks and save intermediate results. Enable persistent_cache=True to avoid reloading models between batches.

Material Quality Tuning For hero assets, increase material_samples to 256 for crisp textures. For background objects, reduce to 64 and enable texture_atlas to combine maps into a single texture sheet, reducing draw calls in game engines.

Mesh Cleanup Pipeline Always follow generation with a Decimate node set to 0.7 ratio, then a Remove Doubles operation. This eliminates the slight voxel-like artifacts inherent in diffusion-based generation, producing clean topology ready for rigging.

Seed Strategy Use incremental seeds (seed + batch_index) when generating variants. This creates cohesive asset families with shared characteristics. For completely random outputs, set seed=-1 to use system time.

Memory Management On 8GB VRAM cards, process images at 512x512 maximum. Use the low_memory_mode flag which enables 8-bit quantization via bitsandbytes, reducing VRAM usage by 50% with minimal quality loss.

Comparison with Alternatives

Why Choose ComfyUI-TRELLIS2? The combination of production-grade PBR materials, native ComfyUI integration, and intelligent batch processing makes it uniquely suited for professional pipelines. While DreamGaussian is faster, it lacks material generation. InstantMesh requires manual scripting. ComfyUI-TRELLIS2 delivers the complete package in a visual, node-based interface that artists actually want to use.

Frequently Asked Questions

What are the minimum system requirements? You'll need a CUDA-capable NVIDIA GPU with 8GB VRAM, 16GB system RAM, and 20GB free storage. AMD GPUs are not officially supported due to CUDA dependencies. CPU inference is possible but impractically slow.

Can I use generated meshes commercially? Yes. Both ComfyUI-TRELLIS2 (MIT license) and TRELLIS.2 (Microsoft Research License) permit commercial use. You own outputs generated from your input images. No attribution required, though crediting is appreciated.

How does quality compare to manual modeling? For hard-surface objects and stylized characters, quality approaches 80% of manual work. Organic forms may require cleanup. The key advantage is speed—what takes days manually takes minutes here. Use it for rapid prototyping and background assets, then refine hero pieces manually.

What image formats work best? PNG and JPEG with clear subject isolation yield best results. Images should be 512x512 to 1024x1024. The model handles transparency as background removal hints. Avoid cluttered compositions—single object on simple background works optimally.

Why is my generation slow or crashing? First, verify VRAM availability with nvidia-smi. Reduce mesh_resolution to "low" and num_inference_steps to 30. Enable low_memory_mode in node settings. If crashes persist, update GPU drivers and PyTorch to latest CUDA versions.

Can I fine-tune on my own 3D datasets? The wrapper doesn't expose fine-tuning directly. You'll need to use the original TRELLIS.2 repository for training. However, the wrapper can load custom fine-tuned models by specifying model_path in the advanced node settings.

How do I export for Unreal Engine? Use the Material Extractor node with export_format="fbx" and texture_format="png". Enable unreal_compatible_uvs to ensure proper UV channel naming. Import into Unreal using the "Import Materials" option—the generated PBR maps will auto-connect to the material graph.

Conclusion

ComfyUI-TRELLIS2 isn't just another AI wrapper—it's a paradigm shift for 3D content creation. By packaging Microsoft's research breakthrough into ComfyUI's accessible node system, Andrea Pozzetti has given creators a production-ready pipeline that turns imagination into geometry at unprecedented speed. The combination of intelligent mesh generation, full PBR material support, and batch processing addresses real studio pain points.

While manual modeling remains essential for hero assets, this tool eliminates the drudgery of background prop creation and rapid prototyping. The active Comfy3D Discord community ensures you're never stuck, and the GitHub repository receives regular updates.

Your next step: Install via ComfyUI Manager, load the example workflow, and transform your first image. Within minutes, you'll hold a 3D asset that previously demanded days of labor. The future of 3D creation is here—and it runs in ComfyUI.

Ready to revolutionize your pipeline? Star the repository and join the community discussion today.