# Spirula Studio deleted its dependencies instead of wrapping them

> Satyajit Ghana — Head of Engineering @ Inkers Technology
> canonical: https://ai.thesatyajit.com/articles/spirula-studio
> date: 2026-09-22
> tags: 3d, gaussian-splatting, performance, explainer, cuda
When a project describes itself as "one self-contained binary" covering camera
alignment through to 3D Gaussian Splatting training, my first move is to open
the CMake and count the `FetchContent_Declare` calls. That is where the seams
usually are: a launcher, a config schema, and six other people's repositories
doing the work.

[Spirula Studio](https://github.com/harry7557558/spirula-studio) has two.
`glfw` and `imgui`. That is the entire external fetch list.

<Video
  src="/articles/spirula-studio/pipeline-loop"
  poster="/articles/spirula-studio/pipeline-loop-poster.jpg"
  alt="A twelve-second screen capture of the Spirula Studio desktop application, captioned in three parts. Under '360° Camera Support — Fisheye / Equisolid / Equirectangular Panorama' a circular fisheye frame of a room is shown inside the app's viewport. Under 'Built-In AI Masking — SAM 3 / Text Prompt / Fisheye Border' the same fisheye frame appears with a red segmentation mask over its background. Under 'Lightning-Fast SfM — GPU Accelerated + Fisheye/360° Support' a sparse point cloud of a building assembles in the viewport, then a long aerial capture of a river and a road appears as a reconstructed point cloud with a caption reading '5374 images, 25min @ RTX 5070 Laptop GPU'."
  caption="An excerpt (frames 72–135 of 212) from the project's own hero animation, at its native 5 fps. The captions and the figures in them are the project's claims, not my measurements — I have not run the binary. The source is silent. (Spirula Studio, spirula.studio hero animation; GPLv3, licence and asset credits committed beside the clip.)"
/>

This matters beyond tidiness. Every Gaussian-splatting pipeline I have had to
put into production died at the same place: not at the training, but at the
seams. A COLMAP that has to be built with the right CUDA arch. A PyTorch wheel
that fights the driver. A masking script that pulls a second CUDA stack in
beside the first. An `ffmpeg` that is on the machine but wrong. The model was
never the hard part; the bill of materials was.

So the interesting question about Spirula Studio is not whether it trains good
splats. It is whether "no Python, no PyTorch, no separate COLMAP install" is a
packaging claim or a rewrite.

## It is a rewrite

<DependencyLedger />

Read the module READMEs and the same sentence appears six times in slightly
different words: *"with no onnxruntime, no PyTorch and no converter."* Each
module says what it replaced and why:

- **`src/sfm/`** — *"A standalone SfM pipeline — images in, a COLMAP
  `sparse/` model out — with a GPU compute backend (Vulkan + Slang) and no
  heavy dependencies… It exists to replace the `colmap` subprocess."* The rule
  it sets for itself is the one that makes this defensible: *"Port algorithms,
  not code. COLMAP is the reference for behaviour and parameter defaults; the
  implementation is ours, against our own data structures."* COLMAP's on-disk
  formats stay the interchange format precisely so any one stage can be swapped
  back for COLMAP's to bisect a failure.
- **`src/nn/`** — a general inference layer: its own Vulkan runtime, a device
  tensor, an op set, host image I/O. *"It knows nothing about any model."* No
  computation graph, deliberately: *"a module's forward pass reads as
  straight-line C++ next to its PyTorch reference, and the arena's scoping is
  the whole memory strategy."*
- **`src/sam/`** — SAM 2 / 2.1 / 3 on that layer, a Vulkan + Slang port of
  [sam3.cpp](https://github.com/PABannier/sam3.cpp), itself a ggml port of
  Meta's SAM 3. It exists *"to replace the Python/PyTorch subprocess the GUI
  used to shell out to for masking."*
- **`src/video/`** — frame extraction without ffmpeg, on
  `VK_KHR_video_decode_*`, with the containers, bitstream parsing and
  reference-picture management written here because *"a hardware decoder does
  entropy decoding, motion compensation and filtering. It does **not** track
  reference-picture state, and Vulkan makes that the application's job."*

The checkpoints are the honest exception and the project is precise about it.
ALIKED's weights are *"COLMAP's, fetched from COLMAP's release URL and parsed
in process. We host nothing and convert nothing."* The ONNX reader is
`nn/io/Onnx.cpp`, a ~400-line varint walk of protobuf that reads *initializers
only* — the graph structure is hard-coded in C++, so nothing has to understand
an operator or a shape rule. The point of that is stated plainly: **parity**.
Both sides run the same bytes, so a difference against
`colmap feature_extractor --FeatureExtraction.type ALIKED_N16ROT` is yours and
can be bisected, "which is exactly how the two bugs below were found."

That is the tell of a real port rather than a reimplementation-by-vibes. The
modules report their parity as a number: MoGe-2's forward pass matches
onnxruntime on the same checkpoint to a relative L2 of **3.8e-6**, Metric3D
v2's to **1.5e-3**, and LoMa's three networks each match on the same bytes.

## The `-DSS_ENABLE_PATENTED=ON` line

Buried in the build instructions is the most grown-up licensing decision I have
seen in a hobby-scale repository:

<Callout type="warning">
"**Compiled only with `-DSS_ENABLE_PATENTED=ON`, which is OFF by default.** The
H.264 / H.265 / AV1 bitstream parsers are the one piece of this repository
carrying third-party patent exposure, and this is a GPLv3 tree. With the option
off, `src/video/` is neither compiled nor linked and every consumer falls back
to an external ffmpeg: the GUI says why in the dataset panel, and
`spirula sam video` / `extract` say so and exit."
</Callout>

Nine thousand lines of decoder, written, tested, and fenced behind a flag that
defaults to off, with the fallback wired and the user told why. The upside of
turning it on is stated too — roughly 15× faster frame extraction, a 127-second
1080p30 clip in ten seconds, masking that rides along on the same device pass,
and no ffmpeg to install.

## Where the numbers are

The feature list is the marketing surface: cross-vendor via Vulkan, one
strategy combining MCMC/IGS+/MRNF, 10 million SH3 Gaussians in 8 GB of VRAM
under quantized training, native 360 and equirectangular support, a modified
bilateral grid and PPISP for exposure and white balance. I have not run the
binary and have no measurement of my own to put against any of it.

What I can read is the engineering documentation, and there the numbers have
the shape of things someone actually measured and then had to live with. My
favourite is the one that argues *against* a speedup.

<FpDeterminism />

The mapping stage spends most of its time in bundle adjustment, and most of
those solves are provisional — a growth-phase refinement followed by more
growth, a merge-tree level followed by another level. Running them in fp32 is
worth 25–35% of the stage, and the README does the arithmetic for why:
*"on solves large enough to be arithmetic-bound, halving the bytes every kernel
moves is worth ~2×, and below a few dozen images the scalar makes no difference
at all because those solves are bounded by dispatch count instead."*

It is fp64 anyway. The reason is the one that only shows up if you run the same
job three times:

<Callout type="note">
"The Schur and Jacobian kernels accumulate with floating-point atomics, whose
execution order is arbitrary, so no two solves agree in their last bits. At
fp64 that perturbation is ~1e-16 and never crosses a decision threshold — the
whole pipeline is reproducible run to run. At fp32 it is ~1e-7 and crosses them
constantly, and LM's accept/reject plus the mapper's filters turn a last-bit
difference into a different reconstruction."
</Callout>

The README reports three identical runs of a 379-image capture: **96.1 AUC@10
every time** in fp64, and **96.5 / 92.3 / 91.5** in fp32. Noisier *and* 2.7
points worse on average. The flag to take the speed anyway exists, `--ba-real-coarse float`,
and the default does not use it.

This is a familiar bruise. Non-determinism from atomic ordering is the thing
that makes a CUDA pipeline impossible to debug — you fix a bug, the number
moves, and you cannot tell whether you fixed it. Paying 30% to keep a pipeline
bit-reproducible is the right trade, and almost nobody makes it, because the
30% is visible in a benchmark and the reproducibility is not.

The second measurement in that family is about an abandoned design rather than
a scalar. An earlier "manage" loop repaired a model by growing it without a
bound: *"on a 5356-image capture it spent 65 minutes to merge three models and
recover 119 images, and ended with three near-copies of one reconstruction."*
That is in the README, describing code that has since been replaced, under the
switch that still turns it off.

## The 360 path

The claim I most wanted to check is the one about 360 cameras, because it is
where most pipelines cheat. The cheap version is: undistort the panorama into
six or ten pinhole faces, hand those to COLMAP, and call it support. Spirula
does not do that.

<OsvPath />

The whole thing hangs on treating the two lenses as a **rig** with known
geometry rather than as two unrelated cameras. `kind: dual-fisheye` says the
first two members are back-to-back lenses of one camera: the second turned 180°
about the image vertical, the baseline between them its only translation. The
repository reports how well that nominal geometry holds — Insta360 X, DJI Osmo
360 and a PortalCam's two fisheyes *"all calibrate within 0.8–1.4 degrees of
that rotation, so it is refined; the Osmo and the PortalCam, measured against
something metric, put the baseline within a millimetre of the axis"* — and then
uses it from the seed pair on, instead of waiting for each lens to register
independently.

Once a member is calibrated, registration changes shape: *"a candidate whose
frame has no lens placed yet brings the whole frame, and the frame — not a lens
— is what the PnP estimates: every calibrated member's 2D–3D correspondences go
into one pool, and one LO-RANSAC over that pool solves for the frame's pose…
scored against **all** the members, so a hypothesis that explains one lens and
contradicts the other nine loses to one that explains the frame."*

The rig-mate extension is the part with the most useful negative result.
Extending a verified pair to the other lens verifies **72–95%** of the time on
dual fisheyes and **6%** on a `.360`'s ten narrow views — so it is enabled for
the first and stopped for the second, with the measurement printed rather than
a heuristic asserted.

And the metric gauge is where the Osmo 360 gets special-cased by its own
deficiency rather than by name. Scale and up normally come from the
accelerometer through pre-integration and from the GPS log. What is missing is
refused *by its own uncertainty* rather than by a rule: *"a camera that only
pans gets up and no scale, a stale phone fix gets no GPS, a file with an
attitude stream but no raw gyro (the Osmo 360) pre-integrates from the attitude
instead."* The check that it worked is gravity: **9.82 m/s² within 0.3° of up**
on a 118-second walk, and the whole fit takes 0.3 s.

Then the uncertainties get printed and not enforced, for a reason worth
quoting at every team that has ever shipped a quality gate:

<Callout type="warning">
"Measured against a reference whose error is correlated — GPS drift — they
under-state the real error by 3.9–4.5×: on one flight a 2% gate on them passed
a 3.6% scale error. **A gate that passes what it exists to catch is worse than
no gate**, so they are printed as the lower bounds they are."
</Callout>

## What I would want before putting it in a pipeline

The gap is comparison. The SfM README's own unstarted list names it twice:
*"what is left is a scored comparison of the three frontends on a public dataset
— nothing here says which to reach for"*, and, separately, *"parity
benchmarking on ETH3D / IMC."* So the port is verified against onnxruntime and
COLMAP for *agreement*, which is the harder and more useful check, but nothing
says whether the finished reconstruction is as good as COLMAP's on a dataset
both have seen.

The support surface is also one person's. The README says so — *"developed and
maintained almost entirely by one person"* — and the git history says the same:
50 commits in the public tree, the most recent three on the day before I wrote
this, all titled "render: misc UI/UX fixes". Against that, 471,999 lines of
C++, Slang and CUDA across `src/`, of which roughly 286,000 is hand-written once
the generated kernel instantiations and the translation catalogues are taken
out.

<RepoCard repo="harry7557558/spirula-studio" />

<Figure
  src="/articles/spirula-studio/fig1.jpg"
  alt="The Spirula Studio desktop application. A dark ImGui interface with a left panel of training parameters and a large viewport showing a Gaussian-splat reconstruction of an outdoor scene, with a training progress readout and camera frustums drawn over the splats."
  caption="The GUI. The same TrainerCore drives this and `spirula train` on the command line; the dataset parsers, the viewer server and the training driver were each once implemented twice, in Python and C++, and the Python halves were deleted after a parity gate proved the pairs agreed. (Spirula Studio, assets/screenshot.png; GPLv3, licence committed beside the image.)"
/>

The other thing I would want is a licence read before adopting. Spirula Studio
is **GPLv3**, not Apache or MIT, which is a different conversation from most of
the splatting ecosystem — gsplat is Apache-2.0, nerfstudio is Apache-2.0. If
you are shipping a product, that binary is a subprocess boundary you have to
think about, and `-DSS_ENABLE_PATENTED=ON` is a second one.

None of which changes the thing I keep coming back to. The reason a splat
pipeline is painful in production is that it is six stacks pretending to be
one. This is one stack. Somebody sat down and wrote the SfM, the inference
runtime, the video decoders and the segmentation model as compute shaders,
checked each against the thing it replaced to six decimal places, and then
refused the 30% speedup that would have made the result irreproducible.

<ChangeMyMind>

<Falsifier claim="Spirula Studio wraps almost nothing: its only external build-time fetches are glfw and imgui, and the components it replaced — COLMAP, PyTorch, ffmpeg, onnxruntime — were rewritten rather than vendored.">
Checked by grepping `FetchContent_Declare` and `GIT_REPOSITORY` across
`CMakeLists.txt` and `cmake/*.cmake` at the tip of the public tree, and by
reading the six module READMEs. A vendored third-party tree under a path I did
not search, a submodule, or a runtime `dlopen` of a system library doing the
real work would overturn it. Note the scope: this is a claim about *code*, not
about weights — the checkpoints are all somebody else's and the project says so.
</Falsifier>

<Falsifier claim="Keeping bundle adjustment in fp64 buys bit-reproducibility, and fp32 costs 2.7 points of mean AUC@10 with a five-point spread across identical runs.">
Three runs of one 379-image capture, reported by the project, not by me. Three
runs is thin. Run the same capture ten times at each scalar on a different GPU
and vendor: if fp32's spread collapses, the atomic-ordering story is specific to
one driver's scheduling and the default is over-cautious. If fp64 ever varies at
all, the reproducibility claim is wrong outright.
</Falsifier>

<Falsifier claim="The dual-fisheye rig path is real 360 support — the two lenses are reconstructed as a rig with known relative geometry, not undistorted into pinhole faces first.">
Read from `src/sfm/README.md` and `src/sfm/core/Rig.h`'s documentation, plus
the `.insv`/`.OSV` multi-track handling in `DatasetPrep.cpp`. If the frames are
in fact resampled to pinhole faces before matching — `app/GeometryWarp.h` does
exactly that for the depth models, so the machinery exists — then the rig is
operating on rectified crops and the distinction I am drawing is thinner than I
claim. Running `spirula sfm auto` on a real `.OSV` with `--rig` logging on
would settle it in one run.
</Falsifier>

<Falsifier claim="Nothing establishes that Spirula Studio's finished reconstructions are as accurate as COLMAP's; the verification is parity of components, not of results.">
An absence claim, and the project asserts it too — item 17 of its own unstarted
list is "parity benchmarking on ETH3D / IMC", and item 15 says "nothing here
says which [frontend] to reach for". A published ETH3D or IMC table, from the
author or anyone else, kills this immediately, and I would like it to.
</Falsifier>

<Falsifier claim="The hero animation's captions — 5,374 images in 25 minutes on an RTX 5070 Laptop GPU, 10 M SH3 Gaussians in 8 GB — are the project's claims and are unverified here.">
This one is trivially falsifiable in the right direction: anyone with the
binary and one of those captures can reproduce or fail to reproduce it. I am
flagging it because the video in this article is evidence of what the software
looks like running, not evidence that the numbers burned into its captions are
right, and those two are easy to conflate.
</Falsifier>

</ChangeMyMind>