ooosplat README

The project's README from github.com/ooolabdev/ooosplat. As one markdown file: README.md.

OOOSplat

中文 | English

OOOSplat Logo

⬇️ 下载 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 始终保留。

核心优势

界面预览

创建与管理任务

OOOSplat 创建新任务与历史任务界面

高斯泼溅预览与调整

OOOSplat 高斯泼溅预览与 Transform 调整界面

主要功能

Gaussian 编辑快捷键

处理流程

输入视频或图片序列
  │
  ├─ 视频：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 检测与运行机制相互独立。

macOS 15+ Alpha（仅限 Apple Silicon）

当前交付为未签名、未公证的 .app/.dmg Alpha，仅支持 M1 或更新的 Apple Silicon Mac，不支持 Intel Mac 或 Universal Binary。

Ubuntu 24.04 Alpha（仅限 x86_64）

本 Alpha 交付由 Ubuntu 24.04 构建的 x86_64 .deb 安装包；不声明支持 Ubuntu 22.04、其他 Linux 发行版或生产环境部署。

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 已包含在安装包中。

安装与使用

  1. Windows 运行 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。
  2. 启动 OOOSplat，确认顶栏中的内置引擎状态正常。
  3. 在“01 创建新任务”的输入类型下拉栏选择“视频”或“图片”，再点击输入框选择视频文件或图片序列文件夹。
  4. 选择项目根目录；程序会记住上次使用的位置。
  5. 选择“快速”“均衡”或“精细”档位。
  6. 查看自动检测到的 COLMAP 加速状态及原因，然后点击“开始生成”。
  7. 在左侧查看实时阶段、指标和日志；完成后，在“02 历史任务”中查看项目并点击“预览”。
  8. 在“03 预览”的“调整”模式中修改模型，Transform 会自动保存；点击“保存”生成或更新 edit.ply。
  9. 切换到“动画”可查看竖屏构图并重新播放效果；点击“导出视频”会在项目目录生成 23 秒竖屏 MP4。

使用提示：

质量档位

档位 保留画面 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/：

本地开发

开发环境

安装依赖并启动开发模式：

npm install
npm run setup:engines
npm run tauri -- dev

Ubuntu 24.04 Alpha 开发

安装上面的 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 的测试结果。

macOS 15+ Apple Silicon Alpha 开发

在 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

生成 Windows 安装包

npm run package:windows

NSIS 安装包输出到：

dist-artifacts\OOOSplat-0.4.0-x64-windows.exe

首次构建前必须运行 npm run setup:engines。beforeBuildCommand 会自动执行引擎校验和前端生产构建，但不会在打包过程中隐式访问网络。

CLI

仓库同时提供 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 使用显卡？

无需手动选择。应用会检查内置 COLMAP CUDA 运行时、NVIDIA 驱动版本和显卡 Compute Capability，满足要求时自动使�

ooosplat (ooolabdev/ooosplat)

Searching Database…

2K ·GitHub
Ooosplat
这是什么？OOOSplat 是一款本地桌面应用，一键就能把普通的环绕拍摄视频或图像序列变成 3D 高斯泼溅（Gaussian Splat）模型，帧提取、COLMAP 相机重建、Brush 训练和 final.ply 导出全部在你自己的电脑上完成。
我怎么让它跑起来？运行对应平台的安装程序：Windows 上运行 OOOSplat-0.4.0-x64-windows.exe，Apple Silicon Mac 上打开 arm64 的 .dmg（拖入“应用程序”文件夹），或在 Ubuntu 24.04 上执行“sudo apt install ./OOOSplat-0.4.0-x64-linux.deb”；然后选择一个视频或图片文件夹、一个项目目录和一个质量预设，点击“Start Generation”（开始生成）。
我需要自己安装 COLMAP、FFmpeg 或特定 GPU 吗？不需要，每个安装程序都内置了 FFmpeg、COLMAP 和 Brush。GPU 并非严格要求，因为 COLMAP 会回退到 CPU，但 Brush 训练需要一个可用的 GPU 图形后端，建议使用独立 GPU 以获得合理的速度。
macOS 和 Linux 版本也和 Windows 版一样稳定吗？不一样，两者都是未签名的 Alpha 版本：macOS 版只能在 Apple Silicon 上运行（不支持 Intel Mac，也没有通用二进制），可能需要右键→打开才能通过 Gatekeeper；而 Ubuntu 包仅针对 Ubuntu 24.04 x86_64 构建和测试，不适用于其他发行版或生产环境。
它实际能在哪些操作系统上运行？Windows 11 x64 是主要且最完整的目标平台；Apple Silicon 上的 macOS 15+ 和 Ubuntu 24.04 LTS x86_64 则以独立的 Alpha 版本发布。
它需要 NVIDIA GPU 才能工作吗？不需要，GPU 是可选的：当存在驱动版本 528.33+、计算能力 5.0+ 的 NVIDIA 显卡时，COLMAP 会自动使用 CUDA 加速，否则回退到 CPU；Brush 则会选用任何可用的图形后端。
Fast、Balanced 和 Fine 质量预设分别是什么？它们控制帧采样和训练时长：Fast 保留 30% 的帧并进行 8,000 次 Brush 迭代，Balanced 保留 50% 并进行 15,000 次迭代，Fine 保留 100% 的帧并进行 30,000 次迭代，训练分辨率最高可达 2,000px。
生成高斯泼溅模型之后我可以编辑它吗？可以，调整（Adjust）模式让你移动、旋转和等比缩放整个模型，并使用矩形、球体或长方体工具无损地裁剪或保留高斯点，支持完整的撤销/重做；编辑结果会写入单独的 edit.ply，原始的 final.ply 永远不会被覆盖。
OOOSplat 会不会回传任何数据？它只发送匿名遥测数据（随机安装 ID、应用版本、操作系统/CPU、事件名称、各阶段耗时、分档统计的帧数），可在“设置→隐私”中关闭；它绝不会发送你的视频、图片、PLY 文件、文件路径或日志。
我能把高斯泼溅模型转成可分享的视频吗？可以，动画（Animate）模式会播放 5 秒的揭晓动画、8 秒的冲击波和相机环绕，并能导出带水印的 1080x1920、30fps、23 秒 H.264 MP4 到项目文件夹。
What are similar projects?spirula-studio, ml-sharp, InsertAny3D, artcraft, WorldSculpt, video-subtitle-remover, gaussian-splatting, nerfstudio
Which topics is it in?3d-gaussian-splatting, gaussian-splatting, image-to-3d, 3d-reconstruction, tauri, video-processing, ffmpeg, 3d, offline, nvidia, computer-vision, cuda
Creator
ooolabdev
Size
12.4 MB
Stars
2K
Updated
CommitOct 18
Age
2mo
Commits · 90 Days