MV-SAM3D Load Views

MV-SAM3D reconstructs a 3D object from several photos of the same thing taken from different angles. But the research code it wraps doesn't accept ComfyUI tensors - it wants a folder on disk laid out a very particular way. MV-SAM3D Load Views is the adapter: it takes your in-memory IMAGE batch and MASK batch and writes them to disk in exactly the layout the official loader expects, so the next node in the chain (Run Multi-View) can chew on them.

This is the node you use when your views exist inside ComfyUI - generated renders, upscaled shots, anything you've batched yourself. If your views and masks already sit on disk in the MV-SAM3D layout, you can skip this node entirely and use MV-SAM3D Scene From Dir instead.

How it works

The official MV-SAM3D scene layout is scene/images/{1,2,3…}.png plus a mask subfolder scene/<object>/, where each mask is an RGBA file with the mask stored in the alpha channel. That last detail is where every beginner trips: the upstream loader reads masks from the alpha channel, so a normal grayscale PNG mask gets silently replaced by an all-ones "mask everything" image. This node writes white RGB + your mask into alpha, on purpose, so the loader sees what you intended.

It also recreates the scene folder from scratch on every run. That matters more than it sounds: stale files from a previous, larger run would be globbed up by the upstream loader and silently fused into your reconstruction. By nuking the folder first, Load Views guarantees what's on disk is what's in the graph.

The inputs that matter

• images - a batch of N views of the same object. The tooltip says it: use Image Batch (or similar) to combine individual LoadImage outputs into one batch.
• masks - a batch of N foreground masks, one per view, in the same order. The official pipeline requires masks and skips any view without one, so this isn't optional. If your source images carry alpha, that can be your mask; otherwise feed whatever segmentation you use.
• object_name - the mask subfolder name (letters/digits/._- only). Change it if you care, the default object is fine.
• scene_name - the scene folder name under output/mvsam3d_scenes/. Recreated every run, so pick something descriptive.

The one hard failure: if you pass more images than masks, it errors out with a message telling you every view needs a mask. That's a feature, not a bug - better a clear error than a reconstruction with holes.

The output is a single scene socket (MVSAM3D_SCENE) carrying the folder path, the mask prompt, and the view count. Wire it straight into Run Multi-View.

Installing

Search ComfyUI Manager for "MV-SAM3D (Unofficial Wrapper)" (repo robinduckett/ComfyUI-MVSAM3D-Unofficial), install, then run the one-time setup:

cd ComfyUI/custom_nodes/ComfyUI-MVSAM3D-Unofficial
python scripts/setup_env.py

The big prerequisite - and it's non-negotiable - is ComfyUI-SAM3DObjects installed and run once, since this pack reuses its pixi environment and its downloaded weights. There's a ready-made 4-view graph in the repo (mvsam3d_custom_views_upscaled.json) that shows the whole chain - RealESRGAN upscale, mask-from-alpha, Image Batch - wired to this node, so load that if you want a working template rather than building from scratch.

Common issues

• "got N images but only M masks" - batch size mismatch; make sure masks and images are in the same order and count.
• Wonky reconstructions with views missing - almost always a missing or wrong mask. Every view needs one.
• View order matters. MV-SAM3D treats batch order as camera order, with the first view as the reference. If your reconstruction comes out twisted, check which photo you put first, not just the node settings.