spirula-studio README

The project's README from github.com/harry7557558/spirula-studio. As one markdown file: README.md.

Spirula Studio

GPLv3 License  GitHub Releases  Platform

Download • Build from Source • Gallery • Web Viewer

Spirula Studio trains 3D Gaussian Splatting models – from raw photo/video to splat to textured mesh – in one self-contained binary. No Python/PyTorch, no separate COLMAP install. Runs on NVIDIA, AMD, Intel, and Apple GPUs via Vulkan, trains 10M full-SH Gaussians in 8 GB VRAM, and has native support for fisheye and 360° cameras.

Spirula Studio - Open Source 3D Gaussian Splatting Pipeline

Dataset credit: Garage by Simon Bethke (CC BY-SA 4.0); Flight Systems and Control Lab at UTIAS; MegaDepth-X; Mip-NeRF 360.

Features

News

Download

Binaries for Windows, Linux, and macOS can be downloaded from Releases page. Simply select the one for your platform, download and unzip, and double click to open the GUI.

If you are training on remote/cloud GPUs, you may use the CLI – Run spirula --help for details. By default, spirula train command will serve a viewer on an HTTP port, one you can forward over ssh and view training progress in your web browser.

Build from source

To build from source, Spirula Studio provides two backends:

Both provide the same training and meshing functionality. CUDA backend may be faster or slower than Vulkan depending on GPU driver, with difference generally within a few percents. Vulkan backend can be slightly more VRAM efficient in some cases.

Backend GPU/Vendor Support Platform Support Dependencies Additional Features
Vulkan NVIDIA, AMD, Intel, Apple Silicon Windows, Linux, macOS Vulkan/MoltenVK, CMake/Ninja Native support for SfM, frame extraction from videos, and AI masking
CUDA Most NVIDIA GPUs Windows, Linux CUDA, CMake/Ninja -
Details for building the Vulkan backend

Make sure you have Vulkan SDK installed. On macOS, MoltenVK is automatically fetched by CMake. Clone the repository and run the commands:

Windows with MSVC:

cd spirula-studio\
.\build_develop.bat -DSS_BACKEND=vulkan -DSS_ENABLE_PATENTED=ON

If it builds successfully, you get build_vulkan\spirula.exe.

Windows with GCC/Clang:

cd spirula-studio\
cmake -G Ninja -B build_vulkan -DCMAKE_BUILD_TYPE=Release -DSS_BACKEND=vulkan -DSS_ENABLE_PATENTED=ON -DCMAKE_MAKE_PROGRAM=Ninja
cmake --build build_vulkan -j

Pass -DCMAKE_C_COMPILER and -DCMAKE_CXX_COMPILER to the first cmake command if needed.

If it builds successfully, you get build_vulkan\spirula.exe.

Linux:

cd spirula-studio/
bash build_develop.bash -DSS_BACKEND=vulkan -DSS_ENABLE_PATENTED=ON

If it builds successfully, you get build_vulkan/spirula binary.

macOS:

cd spirula-studio/
bash build_develop.bash -DSS_BACKEND=vulkan -DSS_ENABLE_PATENTED=ON
cmake --build build --target macos_app
cmake --build build --target macos_dmg

macOS has only the one backend, so it builds into build/ rather than into a per-backend tree. If it builds successfully, you get build/spirula binary similar to Linux. Additionally, it wraps that binary in a double-clickable build/Spirula Studio.app, as well as disk image build/Spirula Studio.dmg. MoltenVK is statically linked by default and will run on a Mac without dependency installed.

Notes regarding third-party licensing

-DSS_ENABLE_PATENTED=ON enables decoding video on the GPU instead of shelling out to ffmpeg (about 15x faster frame extraction, and without need to install ffmpeg). However, AVC/HEVC bitstream parsers carry third-party patent exposure. If you turn this on, you are responsible for ensuring compliance with local patent laws regarding AVC/HEVC playback.

Masking needs a SAM checkpoint, which the GUI downloads on first use and caches. The checkpoints are Meta's models under Meta's licenses – SAM 2.1 is Apache-2.0, SAM 3 is under Meta's own, non-standard license. They are never bundled, and the GUI shows the terms before fetching anything. On the command line, point --model at a file you downloaded yourself.

Details for building the CUDA backend

Make sure you have a recent version of CUDA installed. On Windows, you also need MSVC compiler compatible with your CUDA version. Clone the repository and run the commands:

Windows:

cd spirula-studio\
.\build_develop.bat -DSS_BACKEND=cuda

If it builds successfully, you get build_cuda\spirula.exe.

Linux:

cd spirula-studio/
bash build_develop.bash -DSS_BACKEND=cuda

If it builds successfully, you get build_cuda/spirula binary.

You can find some professional-quality splats trained by Spirula Studio from Megascapes Library and their SuperSplat page.

Collection of splats created by the users of Spirula Studio can also be found on SuperSplat page.

Some splats created by the author of Spirula Studio can also be found on my SuperSplat page.

Trivia

Spirula Studio (formerly spirulae-splat) is named after the now-inactive project spirulae, which was named after the deep-ocean cephalopod mollusk.

Spirula Studio is developed and maintained almost entirely by one person. Issues and PRs welcome – I sometimes respond late, but rest assured that I do review them all.

spirula-studio (harry7557558/spirula-studio)

Searching Database…

这是什么?Spirula Studio 是一个 3D 高斯泼溅(3D Gaussian Splatting)训练工具:它能把原始照片或视频转换成 splat 和带纹理的网格模型,全部由一个独立的二进制文件完成。
它是用 pip 安装的 Python 工具,还是独立应用?它是一个独立的桌面应用,不是 Python 库:单个自包含的二进制文件,双击即可打开图形界面,还带有 spirula 命令行工具。不需要安装 Python、PyTorch 或单独的 COLMAP。
我怎么把它跑起来?从 Releases 页面下载适用于 Windows、Linux 或 macOS 的预编译二进制文件,解压后双击打开图形界面;命令行版(spirula --help)适合在远程机器上训练。
AI 遮罩或从源码编译方面有什么要注意的坑吗?遮罩功能需要一个 SAM 检查点,图形界面会在首次使用时自动下载(SAM 2.1 采用 Apache-2.0 许可证,SAM 3 则是 Meta 的非标准许可证)。用 -DSS_ENABLE_PATENTED=ON 编译可以让视频解码快约 15 倍,但 AVC/HEVC 的专利合规问题需要你自己负责。
我能在远程或云端的 GPU 上训练,同时看到训练进度吗?可以:spirula train 会在一个 HTTP 端口上开启查看器——通过 SSH 转发该端口,就能在本地浏览器里实时查看训练进度,而命令行程序在远程机器上运行。
它能在我的 AMD 或 Intel 显卡上运行吗,还是必须要 NVIDIA?不需要 NVIDIA:Vulkan 后端支持在 NVIDIA、AMD、Intel 和 Apple 显卡上训练——量化训练可在 8 GB 显存中容纳多达 1000 万个 SH3 高斯点。另外还有一个旧的 CUDA 后端,同样支持 NVIDIA。
为什么叫 Spirula Studio?它原名 spirulae-splat,得名于如今已停止维护的 spirulae 项目,而那个项目的名字来自 spirula——一种深海头足纲软体动物(旋壳乌贼)。
它的 splat 质量为什么有竞争力?其中一种策略结合了 MCMC、IGS+ 和 MRNF 的优点,无论小物件还是大型场景,都能得到更锐利的结果并减少漂浮噪点;此外,改进的双边网格(bilateral grid)加上 PPISP 可以校正曝光和白平衡,而且不会产生多余的色彩偏移或画面变暗。
我的重建结果尺寸不对或者发生倾斜,有办法解决吗?有:从 2026 年 9 月起,数据集创建模块能读取常见视频和图像格式中的遥测元数据,从而恢复真实的度量尺度和朝向,正是针对这个普遍反馈的问题。
Spirula Studio 是谁开发的?几乎完全由一个人开发——所有 issue 和 PR 都有人审阅,只是回复可能比较慢。专业级示例和用户作品在 SuperSplat 页面上展示。
Size
46 MB
Stars
1.8K
Age
2y
Commits · 90 Days