UltraShape Refine

This is the whole point of the pack. Everything else - the model loader, the mesh loaders, the selectors and savers - exists to get data in and out of this one node. It takes your coarse mesh plus the reference image that made it, runs a voxel-conditioned diffusion process for a few dozen steps, and returns a refined ULTRASHAPE_OUTPUT with visibly sharper geometry: crisp edges, real detail, a mesh that hugs the source image instead of vaguely resembling it.

If you've been following image-to-3D at all, you know the standard complaint about generated meshes - great silhouette, mushy surface, topology you wouldn't want to rig. UltraShape attacks the surface half. The community consensus when this dropped (r/comfyui, Jan 2026): generate your base with Trellis 2 or Hunyuan3D, run it through this, then send the refined mesh to a texturing pipeline. It won't texture anything - it's pure geometry. Don't expect it to either.

How it works

The mechanism is worth knowing because it explains every knob. The coarse mesh arrives as a set of voxel indices (from the Load Coarse Mesh node), which act as positional anchors for the diffusion transformer - the model is told "structure is fixed here, now invent the fine detail around it." Your image is converted to an RGBA PIL image, optionally background-removed, then encoded by the conditioner. Over steps (default 50) diffusion steps, the DiT generates latent geometry, and at the end a marching-cubes pass extracts an actual triangle mesh at your chosen octree_resolution. Progress shows in ComfyUI's progress bar, which is nice for a node that can run for minutes.

The inputs that matter

Three are structural: model (from Load Model), coarse_mesh (from Load Coarse Mesh), and image (any IMAGE - your source image, ideally the exact one that generated the coarse mesh). Then the dials:

• octree_resolution - default 384, the VRAM boss. The tooltip is blunt: 384 ≈ 8 GB, 512 ≈ 16 GB, 1024 ≈ 48 GB+. Start at 384, move up only when your card has headroom. This is the single biggest quality-vs-memory trade in the pack.
• num_chunks - default 8000, and read this as chunk size for volume decoding: lower = less VRAM, slower; higher = faster, more VRAM. It's the second lever when you're close to the edge. (Yes, the README's own troubleshooting section says "increase num_chunks" - the code's tooltip disagrees, and the code is right: this one runs the opposite way.)
• guidance_scale (5.0) - how hard the image pulls. Standard diffusion behavior: too low, vague; too high, artifacts.
• steps (50), seed (42) - steps for quality, seed for reproducibility. Change the seed to de-correlate the detail when a run looks "wrong."
• remove_bg - off by default. Flip it on and the node runs rembg on your reference image first; genuinely useful when your source has a busy background. Fails gracefully (logs a warning) if rembg isn't available.
• mc_level (0.0) and box_v (1.0) - marching-cubes iso level and bounding-box scale. Leave them alone until you're chasing artifacts; small nudges of mc_level are the only ones worth experimenting with.

Output is one refined_mesh of type ULTRASHAPE_OUTPUT. From here you can save it (UltraShape Save GLB/OBJ), preview it (UltraShape Convert To GLB/OBJ), or bridge it into the Trellis2 world with UltraShape Output To Trimesh.

Install and the VRAM reality

cd ComfyUI/custom_nodes
git clone https://github.com/jtydhr88/ComfyUI-UltraShape1
cd ComfyUI-UltraShape1
pip install -r requirements.txt

Weights to ComfyUI/models/UltraShape/ultrashape_v1.pt from infinith/UltraShape; ComfyUI Manager finds the pack as ComfyUI-UltraShape1. Plan on ~8-12 GB to load the model plus another ~8 GB for a 384-resolution refine - 16 GB total is the honest entry point, 32 GB if you want the higher octree resolutions. If it OOMs: low_vram on the Load Model node, num_chunks down, octree_resolution to 256 or 384. The pack's README calls out one more quirk: extremely simple meshes can throw tensor size mismatches, which the plugin auto-pads to survive. It'll run; the output just won't be spectacular, because there's not much structure to refine.