MV-SAM3D Scene From Dir

Every multi-view 3D pipeline has this friction: your views and masks live somewhere on disk, and the reconstruction code wants them in one specific folder layout. MV-SAM3D Scene From Dir is the node for the case where that folder already exists - either because you prepared it yourself in the official MV-SAM3D layout, or because you just want to run the paper's example without hunting for input files at all.

It's the sibling of MV-SAM3D Load Views, and the choice between them is simple. Load Views takes images and masks as tensors in your graph and writes them to disk for you. Scene From Dir takes a path and validates what's already there, then hands the same MVSAM3D_SCENE socket to Run Multi-View. If your views are already files, this node saves you the batch/Image-Batch plumbing entirely.

How it works

The official MV-SAM3D scene layout is scene/images/ holding your views, plus a mask subfolder named after the object (e.g. scene/stuffed_toy/) holding one RGBA mask per view, with the mask stored in the alpha channel. Scene From Dir checks that layout - the images folder, the mask subfolder, a non-zero view count - and packages it into the scene output Run Multi-View consumes.

It also knows about a flat layout for people who kept it simple: a single folder of N.png plus N_mask.png pairs, no subfolders. Either way, the node verifies the folder before Run Multi-View ever starts, so you get a clear error ("mask subfolder 'x' not found") instead of a cryptic mid-inference failure.

The two inputs

• scene_dir - the scene folder in the official layout. Here's the trick worth knowing: leave it empty and the node uses the paper's bundled example scene - 8 views of a stuffed toy that ship inside the pinned MV-SAM3D submodule. That's the fastest way to smoke-test the whole pack: empty scene_dir, empty mask_prompt, queue example_workflows/mvsam3d_paper_example.json, and you're reconstructing the exact scene from the paper with its exact default settings (seed 42, 50/25 steps).
• mask_prompt - the mask subfolder name. Three combinations:
  • empty scene_dir + empty mask_prompt → the bundled stuffed_toy example;
  • custom scene_dir + mask_prompt set → official layout (scene/images/ + scene/<mask_prompt>/);
  • custom scene_dir + empty mask_prompt → flat N.png + N_mask.png layout.

Both inputs also act as a poor-man's mask selector: with the official layout, the mask subfolder name is how the upstream loader picks which object's masks to use when a scene folder holds several objects.

The single output, scene (MVSAM3D_SCENE), carries the folder path, mask prompt, and view count - wire it into MV-SAM3D Run Multi-View.

Installing

Search ComfyUI Manager for "MV-SAM3D (Unofficial Wrapper)" (repo robinduckett/ComfyUI-MVSAM3D-Unofficial) or clone it:

cd ComfyUI/custom_nodes
git clone --recursive https://github.com/robinduckett/ComfyUI-MVSAM3D-Unofficial.git
cd ComfyUI-MVSAM3D-Unofficial
python scripts/setup_env.py

That one-time setup_env.py also fetches the pinned MV-SAM3D checkout into vendor/MV-SAM3D if it's missing - which is exactly what Scene From Dir falls back on when you leave scene_dir empty. And as with every node in this pack, the non-negotiable prerequisite is ComfyUI-SAM3DObjects installed and run once: this pack reuses its pixi environment and its downloaded SAM 3D Objects weights rather than shipping its own.

Common issues

• "scene_dir does not exist" - you pointed at a folder that isn't there; create it or fix the path.
• "mask subfolder 'x' not found" - the official layout expects scene/<mask_prompt>/; either the folder is missing or you typed the name wrong. Remember masks here are RGBA files with the mask in the alpha channel.
• "no view images found" - an empty folder, or files that don't end in .png/.jpg. Every view still needs a mask when you run it - the loader skips maskless views.

One workflow note: Load Views and Scene From Dir both feed the same MVSAM3D_SCENE socket, so you can build a scene inside the graph, test it, and later swap in a pre-existing folder by replacing one node - no other wiring changes.