ComfyUI-Trellis2-TiledDecode

ComfyUI-Trellis2-TiledDecode

VRAM-bounded spatial tiling for ComfyUI's native TRELLIS.2 shape decoding and texture decoding, packaged as a custom node. Drop-in replacements for VaeDecodeShapeTrellis / VaeDecodeTextureTrellis that let you decode large 3D shapes (1024–1536) on GPUs that OOM.

Works on stock ComfyUI.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/Aero-Ex/ComfyUI-Trellis2-TiledDecode.git

Restart ComfyUI. No extra dependencies.

Usage

Swap your existing decode nodes:

| Native node | Replacement | |---|---| | VaeDecodeShapeTrellis | Trellis2 Tiled Shape Decode | | VaeDecodeTextureTrellis | Trellis2 Tiled Texture Decode |

Inputs/outputs are identical (mesh + shape_subdivides, voxel colors), so existing workflows only need the nodes swapped.

Parameters

| Widget | Default | Meaning | |---|---|---| | tile_size | 48 | Decode window size in latent cells (coarse grid). | | tile_overlap | 8 | Context shared between neighboring tiles. Must be < tile_size / 2. Higher = better boundary fidelity, linearly more compute. |

Larger tiles are also faster: redundant halo work scales with overlap relative to core width (~3x at 48/8 vs ~27x at 24/8).

• OOM during decode -> lower tile_size by ~25%.
• When tile_size reaches the grid extent (64 @1024, 96 @1536) the node automatically degrades to a single monolithic pass.

How it works

The TRELLIS.2 shape decoder is a sparse submanifold-conv UNet whose receptive field effectively spans the whole latent, so exact tiled equivalence is mathematically out of reach. What this node guarantees instead is structurally perfect stitching:

• Windows decode with halo context; only predictions owned by each window's disjoint core are kept.
• Every dual vertex has exactly one canonical instance; cross-boundary faces reference the owning tile's vertices through a merged key table — no duplicated geometry, no seams, no cracks.
• Subdivision guides are merged per latent root voxel and matched to the texture decoder by coordinate rather than row order, so texturing stays consistent.

Expect small boundary-region differences vs a monolithic decode (typically >99% of vertices within 1 voxel at default overlap); mesh topology and vertex density match the native grid exactly.

Compatibility notes

On import, the pack applies two tiny runtime shims to comfy.ldm.trellis2.vae:

1. SparseChannel2Spatial matches subdivision guides by coordinate key (with a zero-overhead fast path for already-aligned inputs) and tolerates empty intermediate stages.
2. SparseTensor shape helpers tolerate empty tensors.

Both are strict supersets of stock behaviour and make the native texture node work with tiled guides too. If upstream ships equivalent handling, the shims become no-ops.

License

MIT.