HunyuanWorld Panorama to 3D World

The panorama nodes are pretty, but the payoff of this whole pack is the moment a flat 360° image stops being flat. HYWorldSceneGen is that moment. It takes a panorama and decomposes it into a layered 3D mesh world - foreground objects separated from the sky and depth, each on its own mesh layer - which is the difference between "nice wallpaper" and "a place you can orbit a camera through." This is HunyuanWorld's LayerDecomposition + WorldComposer pipeline, and it's the node the other four exist to feed.

How it works

Feed it a panorama file and the node runs a three-stage decomposition. First, ZIM segmentation (those two ONNX models you installed) labels the image into regions; Real-ESRGAN super-resolves them; then a pair of inpainting LoRAs (PanoInpaint-Scene and PanoInpaint-Sky) strip the foreground out to build separate layers - first the labels_fg1 objects, then labels_fg2. Each remaining layer gets pushed back in depth by WorldComposer, which reconstructs the scene as a parallax-arranged mesh world. You get one .ply mesh per layer, written to disk, plus the JSON telling you where everything went.

It's genuinely heavy: the decomposer runs those inpaint models (more FLUX-family inference), and the composer needs Open3D. This is the node where the README's VRAM table matters most - full precision wants ~40 GB; fp8_quantization drops it to ~24 GB.

Inputs and outputs that matter

• panorama_path - required. A file path string, not an image. This is where people get burned: wire the panorama_path output from HYWorldText2Pano or HYWorldImage2Pano into this, or paste a path to a saved PNG. If it's empty or wrong you'll get a FileNotFoundError before anything renders.
• labels_fg1 / labels_fg2 - space-separated object labels for the two foreground layers. This is the fun part: list the things you want pulled out and made three-dimensional. stones flowers in layer one, trees mountains in layer two, per the README's examples. Leave them empty and the decomposition still runs, but you're giving up the layering that makes the world feel solid.
• scene_class - outdoor or indoor. Pick the right one; it steers the scene priors.
• target_resolution - default 3840, up to 7680. Higher means finer meshes and much longer runs. 3840 is a sane default.
• export_draco - also write .drc (Draco-compressed) copies of each mesh, handy if you're shipping to the web.
• output_dir - where the meshes land; auto-generated temp dir if you leave it empty.

Outputs: mesh_paths_json (a JSON string listing the .ply/.drc files), output_directory (where they are), and layer_count (how many mesh layers you got - a useful sanity check that decomposition actually found something).

Installing it

Same pack, same prerequisites: ComfyUI Manager → HunyuanWorld 3D World Generation, or

cd ComfyUI/custom_nodes
git clone https://github.com/krmahil/comfyui-hunyuan-world.git
pip install -r comfyui-hunyuan-world/requirements.txt

Plus HunyuanWorld-1.0 (hy3dworld), Real-ESRGAN, the ZIM segmentation ONNX files (place the zim_vit_l_2092/ folder inside the HunyuanWorld-1.0 directory), and a HuggingFace login. Note the README calls Open3D >= 0.18 required - this node raises a clear error if open3d isn't importable.

Common issues

• FileNotFoundError: Panorama image not found - you wired the IMAGE output instead of the path, or the path points at nothing. Use the second output of the pano nodes.
• Missing Open3D - the node prints that 3D generation won't work; pip install open3d>=0.18.
• Only one or two layers - often your foreground labels don't match what's actually in the scene. Try labels that name the obvious objects ("bushes", "rocks", "people" - then keep the person out of it).
• OOM during decomposition - it's doing multiple inpaint passes; turn on fp8_quantization before you blame your card.

The output is a set of .ply files - those open fine in Blender or MeshLab, or you can wire the JSON into a downstream mesh viewer. The README's example workflows (text_to_3d_world.json, image_to_3d_world.json) show the two-node wiring if you want a graph to copy.