Hunyuan 3D 2.1 VAE Decoder

This is the payoff node. Hy3DMeshGenerator produces abstract latents, and Hy3D21VAEDecode is what turns them into a TRIMESH you can preview, postprocess, paint, and export. It's the bridge between the shape model and everything after it - wire it as Hy3DMeshGenerator → Hy3D21VAEDecode → Hy3D21PostprocessMesh and you've got the skeleton of every mesh-generation workflow in this pack.

The node takes the HY3DVAE from Hy3D21VAELoader and the HY3DLATENT from the mesh generator, then runs the geometry VAE's decoder and extracts a surface mesh. The "decode" here isn't reconstructing pixels - it's an octree-based volume reconstruction followed by a marching-cubes extraction to get triangle soup.

The inputs that matter

• vae, latents - the two required feeds, both from sibling nodes in this pack.
• octree_resolution (default 384) - the grid resolution of the volume reconstruction. This is the single biggest quality/memory tradeoff. Higher = more detail, more VRAM, slower; 384 is the tested sweet spot. If you're memory-limited, drop it in steps of 8.
• num_chunks (default 8000) - how many chunks the extraction processes at once. The tooltip says it straight: higher uses more memory but runs faster. When a big mesh OOMs, lower this before anything else.
• mc_level (default 0.0) - the iso-level threshold for marching cubes. -1 to 1. Leave it at 0; fiddling with it mostly changes how thick or perforated the surface looks.
• mc_algo (mc / dmc) - plain marching cubes vs. dual marching cubes. dmc can be more memory-efficient on chunky octrees; mc is the safe default.
• box_v (default 1.01) - the bounding-box scale of the output volume. You'll rarely touch it.
• enable_flash_vdm (default true) - toggles the FlashVDM-accelerated decoder. Keep it on unless it's causing crashes (some setups hit a missing-kernel error and flip it off).
• force_offload (default false) - shoves the VAE back to CPU once decoding finishes, which is polite to your other nodes but slows a re-run.

How it works

Under the hood: vae.decode(latents) reconstructs the volume, then vae.latents2mesh(...) extracts the surface with your chosen algorithm at the chosen octree resolution. The node flips face winding to a consistent orientation, builds a trimesh, frees the VAE, and empties the cache. The output is a raw, unwashed mesh - expect floaters and degenerate faces, which is why the pack always funnels it through Hy3D21PostprocessMesh next.

Installing and troubleshooting

Install the pack normally (git clone https://github.com/visualbruno/ComfyUI-Hunyuan3d-2-1, pip install -r requirements.txt) and make sure both .ckpt files are in place. The decode itself needs the HY3DVAE loaded, so a failure here usually traces back to Hy3D21VAELoader.

Two failure modes are common and both are memory-shaped. First is a CUDA OOM during extraction - lower num_chunks, then octree_resolution, in that order. Second is a "flash_vdm kernel" error on a picky GPU - set enable_flash_vdm off and rerun; the decode gets slower but works. And if the result looks like Swiss cheese, that's not a crash - crank octree_resolution up on your next run and let the mesh carry more geometry.