ComfyUI-SimpleTrellis2

ComfyUI-SimpleTrellis2

A simplified ComfyUI node for microsoft/TRELLIS.2. It generates a PBR GLB asset from a single image with a compact workflow: one main node, local model loading, progress logging, direct GLB preview, GLB path output, and ComfyUI MESH output.

This node vendors the required trellis2 Python package under the custom node directory and loads core model files from models/trellis2.

Preview

Node

Node name: Simple Trellis2 Image to GLB + Mesh

Category: Trellis2/Simple

Outputs:

• glb_path: GLB file path exported by the TRELLIS.2/o_voxel exporter. By default it is saved directly under output/.
• preprocessed_image: Background-removed and cropped image used for inference.
• mesh: ComfyUI official MESH output. You can connect it to ComfyUI's official Save 3D Model / SaveGLB node.

The node also returns a ComfyUI 3D preview entry for the internally exported GLB, so the generated model can be previewed directly when your ComfyUI frontend has 3D preview support.

Note: glb_path uses TRELLIS.2's own PBR export path and usually preserves richer material output. The mesh output is intended for ComfyUI-native workflows; ComfyUI's official GLB saver stores geometry plus optional vertex colors/texture and is not identical to TRELLIS.2's full PBR texture baking.

Install

Clone or place this repository into ComfyUI custom_nodes:

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/starsFriday/ComfyUI-SimpleTrellis2.git

Install dependencies with the Python interpreter used by your ComfyUI installation:

cd /path/to/ComfyUI
python custom_nodes/ComfyUI-SimpleTrellis2/install.py

Check dependencies and model paths without installing anything:

python custom_nodes/ComfyUI-SimpleTrellis2/install.py --check

The installer does not install or upgrade torch. Install a CUDA-enabled PyTorch build compatible with your ComfyUI first.

The bundled prebuilt CUDA wheels in install.py target:

• Linux x86_64
• Python 3.12
• PyTorch 2.8.0
• CUDA 12.8 PyTorch runtime

If your stack is different, the installer skips those fixed wheels and the final check will show which packages are missing. In that case, install matching builds manually.

By default the installer also avoids upgrading pip, setuptools, and wheel. If your build tools are too old, run:

python custom_nodes/ComfyUI-SimpleTrellis2/install.py --upgrade-build-tools

Model Layout

Default model path:

models/trellis2

Expected core layout:

models/trellis2/
├── pipeline.json
├── ckpts/
│   ├── ss_flow_img_dit_1_3B_64_bf16.json
│   ├── ss_flow_img_dit_1_3B_64_bf16.safetensors
│   ├── shape_dec_next_dc_f16c32_fp16.json
│   ├── shape_dec_next_dc_f16c32_fp16.safetensors
│   ├── slat_flow_img2shape_dit_1_3B_512_bf16.json
│   ├── slat_flow_img2shape_dit_1_3B_512_bf16.safetensors
│   ├── slat_flow_img2shape_dit_1_3B_1024_bf16.json
│   ├── slat_flow_img2shape_dit_1_3B_1024_bf16.safetensors
│   ├── tex_dec_next_dc_f16c32_fp16.json
│   ├── tex_dec_next_dc_f16c32_fp16.safetensors
│   ├── slat_flow_imgshape2tex_dit_1_3B_512_bf16.json
│   ├── slat_flow_imgshape2tex_dit_1_3B_512_bf16.safetensors
│   ├── slat_flow_imgshape2tex_dit_1_3B_1024_bf16.json
│   ├── slat_flow_imgshape2tex_dit_1_3B_1024_bf16.safetensors
│   ├── ss_dec_conv3d_16l8_fp16.json
│   └── ss_dec_conv3d_16l8_fp16.safetensors
├── camenduru_dinov3-vitl16-pretrain-lvd1689m/
└── briaai_RMBG-2.0/

The shared sparse-structure decoder, DINOv3, and RMBG helper models can be reused if compatible local folders already exist. The node searches models/trellis2 first, then shared locations such as models/pixal3d/camenduru_dinov3-vitl16-pretrain-lvd1689m, models/pixal3d/briaai_RMBG-2.0, models/RMBG/RMBG-2.0, and models/rembg/RMBG-2.0.

Model Download

Install the Hugging Face CLI if needed:

python -m pip install -U huggingface-hub

Download the main TRELLIS.2 model:

cd /path/to/ComfyUI
mkdir -p models/trellis2
huggingface-cli download microsoft/TRELLIS.2-4B --local-dir models/trellis2

Download the shared sparse-structure decoder if it is not already available locally:

huggingface-cli download microsoft/TRELLIS-image-large \
  ckpts/ss_dec_conv3d_16l8_fp16.json \
  ckpts/ss_dec_conv3d_16l8_fp16.safetensors \
  --local-dir models/trellis2

Download DINOv3 only if you do not already have a compatible local folder such as models/pixal3d/camenduru_dinov3-vitl16-pretrain-lvd1689m:

huggingface-cli download camenduru/dinov3-vitl16-pretrain-lvd1689m \
  --local-dir models/trellis2/camenduru_dinov3-vitl16-pretrain-lvd1689m

Download RMBG-2.0 only if you do not already have a compatible local folder such as models/pixal3d/briaai_RMBG-2.0, models/RMBG/RMBG-2.0, or models/rembg/RMBG-2.0:

huggingface-cli download briaai/RMBG-2.0 \
  --local-dir models/trellis2/briaai_RMBG-2.0

If you intentionally want the node to download missing model files during execution, enable allow_hf_download. For reproducible ComfyUI runs, keeping it disabled and downloading models ahead of time is recommended.

Recommended Defaults

Start with:

• model_path: models/trellis2
• resolution: 1024_cascade
• low_vram: True
• sampling_steps: 12
• texture_size: 2048
• keep_model_loaded: True
• allow_hf_download: False

For faster tests, use resolution=512. For higher detail, try 1536_cascade; it is much slower and requires more VRAM.

Troubleshooting

Run the checker first:

cd /path/to/ComfyUI
python custom_nodes/ComfyUI-SimpleTrellis2/install.py --check

Check that the node imports:

python -c "import sys; sys.path.insert(0, 'custom_nodes/ComfyUI-SimpleTrellis2'); import nodes; print(nodes.NODE_DISPLAY_NAME_MAPPINGS)"

If CUDA extension packages are missing, rerun:

python custom_nodes/ComfyUI-SimpleTrellis2/install.py

If the direct 3D preview is blank but the saved GLB opens correctly, try disabling use_webp_texture. Some browser-side viewers have incomplete support for GLB files that use WebP texture extensions.

Notes

• CUDA is required. CPU inference is not supported.
• TRELLIS.2 is a 4B-parameter model and needs substantial VRAM. The upstream project recommends an NVIDIA GPU with at least 24 GB of memory.
• The first generation in a fresh ComfyUI session can be slow because the TRELLIS.2 pipeline, helper models, and CUDA kernels need to load and initialize. With keep_model_loaded=True, second and later generations in the same session are much faster.
• If your workflow only needs the official ComfyUI saver, connect the mesh output to Save 3D Model. If you want TRELLIS.2's own material export, use glb_path.

Credits

• TRELLIS.2 GitHub: https://github.com/microsoft/TRELLIS.2
• TRELLIS.2 Hugging Face: https://huggingface.co/microsoft/TRELLIS.2-4B
• Shared TRELLIS sparse decoder: https://huggingface.co/microsoft/TRELLIS-image-large
• DINOv3 mirror: https://huggingface.co/camenduru/dinov3-vitl16-pretrain-lvd1689m
• RMBG-2.0: https://huggingface.co/briaai/RMBG-2.0