livadies/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

Question	Answer
Does Surflo need Python 3.10?	Yes, hard. requires-python = "==3.10.*"
Does torch==2.4.1 exist for Python 3.13?	No. Only 2.5.0+cu124, 2.5.1+cu124, 2.6.0+cu124
Does modal.Image(add_python="3.10") give you 3.10?	Not reliably — install 3.10 yourself
Does mode=plain need the CUDA extensions?	No — and it produces garbage. Use guided
Which output file holds the colour?	point_cloud_normals.ply — not point_cloud_rgb.ply
Is gsplat required?	No. Warning is non-fatal
Is nvdiffrast required?	Only for texturing (mesh_textured.ply)
Does Surflo work on synthetic T-pose anime renders?	Not in our tests — see 05-RESULTS.md
Is that conclusion proven?	No. See the warning below

---

⚠️ 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:

mode	needs CUDA extensions?	outputs	observed quality
mode=plain	no	initial.ply, final.ply	unusable blob
mode=guided	yes	point_cloud_normals.ply, point_cloud_rgb.ply, mesh.ply, (+mesh_textured.ply)	structured, but see results

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

file	what it is
01-DECISION.md	Should you use Surflo? Decision matrix and honest costs
02-INSTALL.md	The exact install that works, incl. the Python 3.10 fix
03-PITFALLS.md	Every trap: symptom → cause → fix, with the evidence
04-EXPERIMENT.md	What was actually run, with numbers
05-RESULTS.md	Visual + numeric results, and what is still unproven
06-PATHS.md	Every path: local, Modal volume, HF
code/	The scripts, as run
evidence/	The images the conclusions are drawn from

---

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.