SphereSfM Dataset

This is the node the whole SplatKit pack is built around. Feed it a WAN-generated equirectangular fly-through video and it hands you a COLMAP dataset - images/ + sparse/0 plus a sparse point cloud - that trains straight away in any COLMAP-compatible 3D Gaussian Splatting trainer. No external venv, nothing to compile, no nvdiffrast. Just one catch that shapes everything else: you're building a trainable scene out of a single panorama.

That's the whole trick worth understanding first. One equirect image is a single viewpoint, and one viewpoint can't constrain a 3D scene. So SplatKit invents the missing viewpoints: MoGe estimates depth from your pano and turns it into a mesh, you draw a camera path through that mesh, WAN fills the holes the pano never saw, and this node runs classical structure-from-motion over the result. The SfM stage is what most people miss - this isn't a feed-forward model guessing poses (the VGGT/WorldMirror crowd), it's geometry actually solved from the imagery. Real poses and real matches, at the price of needing actual parallax in the clip.

How it works

The node shells out to colmap_sphere.exe, a CUDA build of SphereSfM - a spherical-camera fork of COLMAP 3.8 that adds a SPHERE camera model. It runs SIFT feature extraction, matching, and spherical bundle adjustment directly on the equirectangular frames, then sphere_cubic_reprojecer converts the SPHERE reconstruction into six pinhole (SIMPLE_PINHOLE, 90°) cube faces per frame. Ordinary pinhole cameras - so no trainer needs special equirect/unscented projection support. The binary auto-downloads into the pack's bin/ on first run (~37 MB, SHA-256 verified); nothing to install by hand.

Inputs that matter

Only output_name is required; everything else is optional. The ones a beginner actually touches:

• output_name - the dataset folder under ComfyUI/output/. Your COLMAP dataset lands in <output_name>/images/ + sparse/0/.
• pano_frames_1 - the WAN equirect video. "Optional" is a lie; SfM needs frames. Wire it.
• initial_pano - the pristine source panorama WAN was conditioned on. It lands at frame 0000, anchoring the solve on the clean original instead of WAN's drifted first frame. initial_pano_mode replace (default) overwrites WAN's frame 0; prepend keeps both.
• mode - colmap_now (default) runs SfM and writes the cube-face dataset. panorama_only skips SfM and saves the raw equirects, so you can upscale the coherent video first and run SfM on the upscaled panoramas - the best-quality path.
• init_min_tri_angle - the one you'll actually fiddle with when SfM refuses to start (see below).
• frame_stride / max_frames - thin long clips to keep SfM fast; keep enough overlap to still match.
• face_size - cube-face output resolution. 0 = auto (~equirect width / 4). Raise it for sharper images, more disk.

The rest (max_num_features, peak_threshold, edge_threshold, max_num_matches) are real COLMAP flags exposed as widgets, and you'll basically never touch them. matcher_type is sequential by default because your frames are ordered video - flip to exhaustive only for unordered stills.

Outputs

model_dir (the COLMAP dataset folder - feed it to your 3DGS trainer or the upscale workflow), plus num_images and num_points to sanity-check that SfM actually reconstructed something. Wire extra WAN clips into pano_frames_2/3/4 to concatenate multiple trajectories into one reconstruction.

Install

The whole pack installs together (all nodes live under the SplatKit category in ComfyUI):

cd ComfyUI/custom_nodes
git clone https://github.com/mickmumpitz/ComfyUI-SplatKit
python_embeded\python.exe -m pip install -r ComfyUI-SplatKit/requirements.txt

Non-portable install: python -m pip install -r ComfyUI-SplatKit/requirements.txt, then restart. You supply a WAN 2.1 i2v checkpoint and the Matrix-3D pano LoRA, converted with tools/convert_pano_lora.py into your loras folder. First run pulls the MoGe checkpoint into ComfyUI/models/MoGe.

Common issues

• "No good initial image pair found." This is the classic. COLMAP's default init_min_tri_angle is 16°, tuned for wide-baseline photos; WAN/orbit clips have modest parallax (~4–15°), so SplatKit defaults to 4 - lower it further if SfM still won't start.
• A static pan won't triangulate. This node needs real camera movement/parallax and a textured scene. Slow orbit = sparse cloud; no motion = nothing.
• "Need at least 3 frames" - lower frame_stride or raise max_frames.
• GPU requirements. The CUDA build needs an NVIDIA Turing or newer for GPU matching; without one you fall back to CPU (slower, same result). macOS needs a self-built colmap_sphere binary set via COLMAP_SPHERE_EXE.
• The prompt matters. It must describe the actual scene - a wrong prompt visibly degrades what WAN paints into the holes, and bad holes mean bad SfM matches.

There's also reuse_solve: leave it off for the first build, turn it on when re-running the same clip - it skips the expensive solve and just re-renders the cube faces, guarded by a fingerprint that silently re-solves if anything changed.