The project's README from github.com/ooolabdev/ooosplat. As one markdown file: README.md.
⬇️ 下载 OOOSplat 0.4.0(Windows / macOS / Ubuntu)
OOOSplat 是一款将普通环绕拍摄视频或图片序列一键转换为 3D Gaussian Splatting 的本地桌面应用。选择素材、项目目录和质量档位后,应用会自动完成画面准备、相机重建、训练与 PLY 发布,并可直接预览、调整和导出结果。
Windows 和 Apple Silicon macOS Alpha 均随应用提供 FFmpeg、FFprobe、COLMAP 和 Brush;Linux 支持目前仅作为 Ubuntu 24.04 LTS x86_64 Alpha 提供。整个生成流程使用本机 CPU 和 GPU,输入素材、工程文件、模型与日志无需上传到云端重建或训练服务。React 界面通过 Tauri 直接调用本机 Rust 后端,不需要远程服务或 localhost API。
当前版本:0.4.0
查看 OOOSplat Roadmap 了解后续规划。
0.4.0 新增图片序列输入、透明 MOV/PNG 自动 Mask、阶段级断点续跑,以及矩形、球形和盒形 Gaussian 编辑;原始
final.ply始终保留。
final.ply 发布,无需手动拼接命令或配置引擎。

logs 目录。Documents\SplatStudio\Projects。.ply,支持 Orbit、Pan 和 Zoom;“调整 / 动画”双模式切换不会重新加载模型或重置相机。edit.ply,后续保存会安全替换该文件,始终不覆盖原始 final.ply。final.ply,或将整个项目移入系统回收站。Shift + 左键拖动添加,Ctrl + 左键拖动移除;中键旋转视角,右键平移,滚轮缩放。Delete 或 Backspace 删除选中 Gaussian,按 Esc 清空临时选区。Ctrl + Z 撤销,Ctrl + Shift + Z 或 Ctrl + Y 重做。模型变换、裁切和删除共享同一历史记录;相机移动和临时黄色选区不计入历史。输入视频或图片序列
│
├─ 视频:FFprobe 分析,FFmpeg 按质量档位均匀抽帧;透明视频同步生成 RGBA 画面与 Mask
├─ 图片:按文件名排序并保留全部图片;透明 PNG 自动生成 Mask
├─ COLMAP:自动选择 CPU 或 CUDA GPU 提取特征;视频顺序匹配,图片穷举匹配
├─ COLMAP:增量重建并验证注册率和三维点
├─ Brush:使用可用 GPU 训练 Gaussian Splats
└─ 校验 PLY 后原子发布为 final.ply
只要 COLMAP 生成了至少一张注册图像和有效三维点,任务就会继续进入 Brush;注册率低于 80% 时会给出质量警告,但不再因低于 50% 自动终止。
Windows 内置的 COLMAP 使用同时支持 CPU 与 CUDA GPU 的构建,运行前会自动选择可用后端;Brush 训练使用可用图形后端,二者的 GPU 检测与运行机制相互独立。
当前交付为未签名、未公证的
.app/.dmgAlpha,仅支持 M1 或更新的 Apple Silicon Mac,不支持 Intel Mac 或 Universal Binary。
PATH 中的同名程序。本 Alpha 交付由 Ubuntu 24.04 构建的 x86_64
.deb安装包;不声明支持 Ubuntu 22.04、其他 Linux 发行版或生产环境部署。
.deb 的用户不需要这些开发工具。ffmpeg、ffprobe 和 CPU 版 colmap(仓库版本为 COLMAP 3.9)。npm run setup:engines 下载并校验。Ubuntu 依赖安装:
sudo apt update
sudo apt install -y \
build-essential curl file ffmpeg colmap \
libwebkit2gtk-4.1-dev libxdo-dev libssl-dev \
libayatana-appindicator3-dev librsvg2-dev libdbus-1-dev
请为显卡安装可用的 Vulkan 驱动(例如 NVIDIA 专有驱动,或 AMD/Intel 的 Mesa 驱动)。Ubuntu 24.04 仓库中的无 CUDA COLMAP 构建会自动使用 CPU;Brush 会在运行时选择可用的图形后端。完全 CPU-only 的软件 Vulkan 后端尚未完成端到端验证。
从 GitHub Actions 下载 OOOSplat-0.4.0-x64-linux Artifact 后,可执行:
sudo apt install ./OOOSplat-0.4.0-x64-linux.deb
.deb 会通过 Ubuntu 包管理器安装 FFmpeg、FFprobe 和 CPU 版 COLMAP;固定版本 Brush 已包含在安装包中。
OOOSplat-0.4.0-x64-windows.exe;Apple Silicon Mac 打开 OOOSplat-0.4.0-arm64-macos.dmg 并将 OOOSplat 拖入“应用程序”;Ubuntu 24.04 使用 sudo apt install ./OOOSplat-0.4.0-x64-linux.deb。edit.ply。使用提示:
| 档位 | 保留画面 | FFmpeg 抽帧率 | Brush iterations | 最大训练分辨率 |
|---|---|---|---|---|
| 快速 | 30% | 源视频 FPS × 0.30 | 8,000 | 1,200 |
| 均衡 | 50% | 源视频 FPS × 0.50 | 15,000 | 1,600 |
| 精细 | 100% | 源视频 FPS × 1.00 | 30,000 | 2,000 |
抽帧由 FFmpeg 完成,COLMAP 不负责减少帧数。程序不设置最大抽帧数量,也没有额外的 Splat 数量上限;最终 Splat 数量由素材、重建结果和 Brush 训练过程决定。
每次生成都会在项目根目录下创建一个独立文件夹:
<项目根目录>\<yyyyMMdd-HHmmss_素材名>\
final.ply 最终 Gaussian Splatting 文件
project.json 项目元数据与结果指标
edit.ply 当前编辑结果;再次保存时安全替换(可选)
preview.mp4 首次动画预览视频导出(可选)
preview-2.mp4 后续视频导出自动编号(可选)
state.json 流水线状态
source\
input.<ext> 源视频副本(视频项目)
images\ 规范化的源图片副本(图片序列项目)
work\
frames\ 抽取或准备后的输入画面
masks\ 透明素材对应的 COLMAP Mask(按需)
colmap\ COLMAP 数据库与稀疏重建
brush\ Brush 数据集与训练中间文件
logs\ FFmpeg、COLMAP、Brush 等完整日志
项目名中的 Windows 非法字符会被清理;发生重名时自动追加 -2、-3 等后缀。
应用设置和项目索引保存在:
%LOCALAPPDATA%\SplatStudio\settings.json
%LOCALAPPDATA%\SplatStudio\project-index.json
%LOCALAPPDATA%\SplatStudio\telemetry.json
OOOSplat 默认开启匿名使用统计,用于了解稳定性和各阶段耗时。可在右上角 设置 → 隐私 中随时关闭,关闭后不再发送任何请求。
会发送的内容:
| 字段 | 说明 |
|---|---|
| 安装 ID | 首次启动生成的随机 UUID,不读取硬件序列号、MAC 地址或设备指纹 |
| 应用版本、操作系统、CPU 架构 | 例如 0.4.0 / windows / x86_64 |
| 事件名 | daily_active、generation_started、generation_completed、generation_failed、pipeline_stage_completed。daily_active 每天最多一次,应用升级后当天会再报一次 |
| 质量档位与输入类型 | 枚举值,例如 balanced / video;图片序列输入报 images |
| 阶段耗时与总耗时 | 毫秒 |
| 帧数与视频时长 | 分桶值,不是原始数量 |
| 失败阶段与错误码 | 枚举值,例如 colmap_mapper_failed;不含原始错误文本 |
不会发送的内容:视频、图片、PLY 等任何素材;文件名、路径和项目名称;日志与命令输出;用户名或任何个人信息。
数据发送到 https://www.ooolab.cn/api/telemetry/event。这是应用唯一的对外网络请求,抽帧、重建与训练全部在本机完成。
开关状态和安装 ID 保存在 %LOCALAPPDATA%\SplatStudio\telemetry.json。删除该文件会在下次启动时生成一个新的随机安装 ID。
| 引擎 | 固定版本/构建 | 用途 |
|---|---|---|
| FFmpeg / FFprobe | Windows x64 8.1 LGPL shared;macOS arm64 8.1.2 LGPL shared | 视频分析与抽帧 |
| COLMAP | Windows 4.0.4 CUDA;macOS arm64 4.0.4 CPU CLI-only | 特征、匹配和相机重建 |
| Brush | v0.3.0 Windows x64 / macOS arm64 | Gaussian Splatting 训练与 PLY 导出 |
Windows、Ubuntu 和 macOS 的来源与校验策略分别记录在 engines/manifest.json、engines/manifest.linux.json 和 engines/manifest.macos.json。大型引擎文件不会提交到 Git;开发者通过 npm run setup:engines 恢复本地运行时。Release 打包前会校验来源、哈希、架构、动态库闭包和 Brush CLI 参数。
第三方许可和通知位于 licenses/:
x86_64-pc-windows-msvc。安装依赖并启动开发模式:
npm install
npm run setup:engines
npm run tauri -- dev
安装上面的 Ubuntu 系统依赖、Node.js 和 Rust 后:
npm ci
npm run setup:engines
npm run verify:engines
npm run verify:licenses
npm run tauri -- dev
也可以在仓库根目录运行 ./scripts/start-app-linux.sh,或使用 npm run start:app:linux。启动脚本会先校验本机引擎和许可映射,仅在源码更新时重新构建 Release 可执行文件。
Ubuntu 24.04 Alpha 的 setup:engines 只安装校验后的 Brush 到 engines/linux/brush/;FFmpeg、FFprobe 和 CPU 版 COLMAP 保持为系统软件包。Tauri 将 Brush 作为资源打入 x86_64 .deb,并在 Debian 依赖中声明 FFmpeg 和 COLMAP。
Ubuntu 24.04 Alpha 自动检查位于 .github/workflows/ubuntu.yml。普通 GitHub runner 会执行前端、许可映射、Rust、Clippy、FFmpeg 集成、.deb 构建、包结构校验并上传安装包与 SHA-256;Brush 端到端验证需要具有可用图形后端的主机或自托管 runner。目前完整流水线仅在 NVIDIA 主机上验证,欢迎补充 AMD、Intel 和软件 Vulkan 的测试结果。
在 Apple Silicon Mac 上安装 Node.js、Rust 和 Xcode Command Line Tools 后:
npm ci
npm run setup:engines
npm run verify:engines
npm run verify:licenses
npm run tauri -- dev
setup:engines 从同仓库的固定 GitHub Release 下载完整 arm64 运行时;Homebrew 只用于维护者先执行 npm run setup:build-deps:macos,再执行 npm run build:engines:macos 重建引擎。.github/workflows/macos.yml 构建未签名应用和 DMG,.github/workflows/macos-engines.yml 生成并发布锁定的引擎归档。
# 前端测试
npm test
# 前端生产构建
npm run build
# Rust 测试
cargo test --manifest-path src-tauri\Cargo.toml
# Rust 静态检查
cargo clippy --manifest-path src-tauri\Cargo.toml --all-targets -- -D warnings
# 校验内置引擎版本、哈希和 COLMAP CUDA 运行时
npm run verify:engines
# 校验第一方许可、第三方通知及安装包资源映射
npm run verify:licenses
npm run package:windows
NSIS 安装包输出到:
dist-artifacts\OOOSplat-0.4.0-x64-windows.exe
首次构建前必须运行 npm run setup:engines。beforeBuildCommand 会自动执行引擎校验和前端生产构建,但不会在打包过程中隐式访问网络。
仓库同时提供 splatstudio 诊断 CLI:
# 检查所有内置引擎
cargo run --manifest-path src-tauri\Cargo.toml --bin splatstudio -- health
# 读取视频信息
cargo run --manifest-path src-tauri\Cargo.toml --bin splatstudio -- probe "D:\Videos\orbit.mp4"
# 查看抽帧计划但不写出画面
cargo run --manifest-path src-tauri\Cargo.toml --bin splatstudio -- plan "D:\Videos\orbit.mp4" --quality balanced
# 单独抽帧
cargo run --manifest-path src-tauri\Cargo.toml --bin splatstudio -- extract "D:\Videos\orbit.mp4" "D:\Frames" --quality fast
# 运行完整流水线(自动检测并选择 COLMAP GPU 或 CPU)
cargo run --manifest-path src-tauri\Cargo.toml --bin splatstudio -- generate "D:\Videos\orbit.mp4" --projects-root "D:\Splat Projects" --quality balanced
# 图片序列使用同一命令,传入文件夹即可
cargo run --manifest-path src-tauri\Cargo.toml --bin splatstudio -- generate "D:\Photos\object" --projects-root "D:\Splat Projects" --quality balanced
开发或诊断时可以通过全局参数 --engine-dir <路径>,或环境变量 OOOSPLAT_ENGINE_DIR,覆盖默认引擎目录。
Linux 还可分别使用 OOOSPLAT_FFMPEG、OOOSPLAT_FFPROBE、OOOSPLAT_COLMAP 和 OOOSPLAT_BRUSH 指定可执行文件;未指定时按仓库托管目录和系统 PATH 依次发现。
无需手动选择。应用会检查内置 COLMAP CUDA 运行时、NVIDIA 驱动版本和显卡 Compute Capability,满足要求时自动使�