Hunyuan3D V1 - Image Loader

The Image Loader is the quietest node in this pack, and also the one that sets the quality ceiling for your entire image-to-3D run. It takes an ordinary ComfyUI image and turns it into the exact thing Hunyuan3D-1 wants to see: a single subject, on transparency, with a small config object that tells the rest of the chain where to save. Screw this step up and no amount of cleverness in the mesh stages will save you.

It's the image-to-3D entry point. The full chain is Image Loader → Image2Views → Views2Mesh, and if you compare it to the text-to-3D path you'll notice the loader plays the role that Text2Image does there - it's the thing that manufactures the clean subject image the mesh models can actually read. The difference is that here the artist is you, and your input photo.

How it works

Under the hood it's disarmingly simple: your IMAGE tensor becomes a PIL image, then gets passed through rembg - the long-running open-source background-removal library - with its default u2net segmentation model. The result is an RGBA cutout, saved as img_nobg.png in a fresh timestamped folder under ComfyUI/output/Hunyuan3D-1/. The node returns that cutout as a Hunyuan3D1Image plus a Hunyuan3D1Config whose only real content is that folder path, so every downstream node writes into the same run directory.

Two implementation details worth knowing, because they surprise people. First, if you feed it an image that already has an alpha channel, the rembg pass is skipped and your cutout is used as-is - the code treats an RGBA input as "already done." Second, it only looks at the first frame of a batch. Drop a batch in and you get the first image back, no error. For one subject per run, that's fine.

What you should actually care about

The input is one IMAGE, and its quality is the whole ballgame. rembg's u2net is the historical default - fast, tiny, runs fine on CPU, but its edges are merely acceptable. It struggles with hair, fur, thin structures, and anything semi-transparent, and it's been that way since 2020. The KB's background-removal essay is blunt about it: u2net is the "you get what you pay for" option, and if you're extracting a product or a character with tricky edges, the cutout will show it.

So the practical advice: give the loader a photo with a clean subject on a contrasting, uncluttered background. The better your source, the cleaner the alpha, and the less work the multi-view stage has to do to hide your mistakes. If your photo's subject has flyaway hair, clean it up in an editor first - or accept that the 3D model will inherit the halo. There's no quality knob here; there's just your input.

Install and gotchas

Install is the pack's standard ordeal: this whole pack is not a ComfyUI Manager one-click. Fresh ComfyUI recommended, Python 3.12, and heavy native deps (pytorch3d, Open3D, nvdiffrast, Ninja) plus the pack's requirements.txt. The 3D weights are a manual huggingface-cli download tencent/Hunyuan3D-1 --local-dir ./weights inside the pack folder.

One honest caveat: the 3D model ecosystem moved on after this pack. By the time you're reading this, Hunyuan3D-2.x and newer 3D generators exist, and if you already run ComfyUI-3D-Pack you don't need this wrapper at all - it has its own Hunyuan3D-1 implementation. But if you're running this pack, this loader is where your results are made or broken. Get the cutout right and the rest of the chain has a fighting chance.