Hy3D VAE Decode

Hy3DVAEDecode is the moment the Hunyuan3D shape model's work becomes something real. Upstream, Hy3DGenerateMesh produces shape latents - a compressed voxel-ish representation of the object. This node runs those latents through the VAE decoder and then extracts a triangle mesh from the result. No decode, no mesh. It's the difference between "I generated the idea of a chair" and "here's a chair I can export."

How it works

It takes a HY3DVAE (from Hy3DModelLoader or Hy3DVAELoader) and HY3DLATENT (from Hy3DGenerateMesh / Hy3DGenerateMeshMultiView), scales the latents back by the VAE's scale factor, decodes them, and runs marching cubes to carve a surface out of the decoded volume. The output is a TRIMESH - the type the whole rest of the pack consumes.

The inputs that actually matter, and that you'll tune:

• octree_resolution (default 384) - how fine the voxel grid is. Higher means more geometric detail and more VRAM; 384 is the sensible default, and going higher is where cards start to sweat.
• mc_algo - mc (plain marching cubes) or dmc (differentiable marching cubes). dmc generally gives cleaner geometry; mc is the safe fallback.
• num_chunks (default 8000) - chunks processed per pass. Higher = faster, but the author's tooltip is the whole story: "higher values use more memory." When you OOM during decode, this is the first thing to turn down.
• mc_level (default 0) - the iso-surface threshold. Leave it alone unless you know why you're touching it.
• box_v (default 1.01) - the bounding volume the latents occupy.

Two optional toggles: enable_flash_vdm (default on, the fast decoder) and force_offload (default on, shoves the VAE back off GPU when done - leave it on unless your next node needs the VAE hot).

Where it sits

In the example workflow the chain is: LoadImage → Hy3DModelLoader → Hy3DGenerateMesh → Hy3DVAEDecode → Hy3DPostprocessMesh. So decode is the bridge between "shape sampling" and "mesh cleanup," and the mesh it spits out is raw - floaters, degenerate faces, way too many triangles. That's normal, not a bug; the postprocess node right after it exists to fix exactly that.

Install

Pack-level install (Manager search "Hunyuan3DWrapper", or git clone https://github.com/kijai/ComfyUI-Hunyuan3DWrapper into custom_nodes), then pip install -r requirements.txt. Decode needs no extra compiled deps - that's the texture stage's problem, not yours here.

Common issues

• OOM at decode - drop octree_resolution toward 256 and num_chunks down; both are direct VRAM levers. Try mc instead of dmc too.
• Watertight-looking but mushy - you're at a low octree resolution. If your card can take it, nudge toward 512.
• VAE mismatch - decoding turbo latents with the standard VAE (or vice versa) gives garbage. The turbo VAE auto-detects in Hy3DVAELoader, but only if you actually loaded it.