surflo-pipeline

Surflo v0 — Field Notes from a Real Deployment

Everything learned running Surflo v0 (Anttwo/Surflo) on Modal GPU, written so that the next agent or engineer does not repeat the same 20+ hours.

Read this first. The single most valuable fact in this repo is in 02-INSTALL.md: Surflo requires Python 3.10, and the way you usually ask for a specific Python in a container image silently does not work. If you skip that, nothing else you try will matter.

---

TL;DR for an agent in a hurry

---

⚠️ Read this before you cite any conclusion here

This repo records a partially completed investigation, and it is important to know which parts are solid.

Solid (measured, reproducible):

• The environment facts: Python 3.10 requirement, the missing torch 2.4.1 cp313 wheel, the add_python failure, which optional dependency gates which feature.
• The file-format gotchas: which .ply carries colour, PLY header validation, the ~1 KB/s artifact transfer limit.
• The raw run statistics in 04-EXPERIMENT.md.

NOT solid (do not cite as established):

• The verdict "Surflo does not fit our task." The control experiment that was supposed to support it was run in the wrong mode (plain, the degraded one). When re-examined, that control output is also a blob. So the two live hypotheses — domain mismatch vs our setup is broken — were never separated. A proper guided control on real photos was launched but its result is not yet in this repo. See 05-RESULTS.md for the exact status.

If you are picking this up: run the control in code/ctrl_guided.py first, before trusting anything about quality.

---

What Surflo is

Multi-view 3D reconstruction. You give it 2–80 RGB images of a scene (no poses, no intrinsics) and it returns a Gaussian-splat field, point clouds and a mesh.

Two inference modes, and the difference matters enormously:

guided also has presets: guided=minimal (fast) and guided=default (full, with texturing). If you only ever run plain you will conclude the model is broken. It is not — plain is simply the degraded path.

---

Repo contents

---

The one-paragraph version

Surflo is a real, working multi-view reconstructor, but its dependency graph is version-brittle and gated: Python 3.10 exactly, torch 2.4.1 exactly, and a set of optional compiled extensions (fused_ssim, geodel, nvdiffrast) that are installed from external git repositories, not the project tree. Several of these fail silently — a build step can print rc=0 having installed nothing. Budget your time for the environment, not the inference: inference itself took 32–180 s on an L4, while getting a correct environment took the bulk of the effort.