深入 OOOSplat 架构：Tauri 2 + Rust + React 如何打造本地高斯泼溅桌面应用-平芜编程栈

桌面应用
图形学
3D渲染
计算机视觉

【免费下载链接】ooosplat

A local desktop app that turns videos and images into 3D Gaussian Splats in one click.

项目地址：https://gitcode.com/gh_mirrors/oo/ooosplat

OOOSplat 是一款本地桌面应用，把环绕拍摄的视频或图片序列一键转换为 3D Gaussian Splatting（高斯泼溅）模型。它的技术底座是Tauri 2 桌面框架 + Rust 原生后端 + React 19 前端，并内置 FFmpeg、COLMAP、Brush 三套引擎，整条生成流水线全部在本机 CPU/GPU 上运行，素材与模型不出设备。

一图看懂：三层架构如何分工

高斯泼溅应用的核心矛盾是：界面要快（Web 技术擅长），计算要猛（原生 Rust 擅长）。OOOSplat 的解法是经典的"薄前端 + 厚后端"分层，三层各司其职：

层	技术	职责	代码位置
界面层	React 19 + TypeScript + Zustand	任务表单、实时进度、高斯模型预览与编辑	src/
系统层	Tauri 2	窗口、文件对话框、IPC 命令通道、事件推送	src-tauri/tauri.conf.json
计算层	Rust + Tokio 异步运行时	抽帧、相机重建、GPU 训练、进程树管理	src-tauri/src/

对新手来说，只需记住一句话：React 负责"看得见的"，Rust 负责"跑得动的"，Tauri 是两者之间的"传话筒"。

Tauri 2 层：桌面应用的骨架

Tauri 2 是介于 Electron 与纯原生之间的选择：前端跑在系统 WebView 里（Windows 上用 WebView2，macOS 上用 WKWebView），而窗口管理、文件访问、系统能力全部交给 Rust 核心，因此安装包体积和内存占用远低于 Electron 方案。

1. 应用入口：插件 + 状态管理 + 命令注册

Rust 侧的启动逻辑集中在 run_app()。它做了三件关键的事：

挂载single_instance 插件——防止用户双击两次图标就出现两个窗口；
用.manage()注册共享状态：流水线控制器、预览控制器、遥测服务；
通过invoke_handler宏把 40 多个 Rust 函数注册成前端可调用的 IPC 命令，如 start_pipeline、cancel_pipeline、prepare_gaussian_preview等。

2. 安全策略：默认全封闭

桌面应用里内嵌网页，安全是头等大事。tauri.conf.json 中的 CSP（内容安全策略）规定前端只能访问自身资源、本地 IPC 通道和本地资产协议，不开放任何外部网络来源——这正是"隐私不上传"承诺在代码层面的体现。

3. 打包分发：一份配置，三大平台

tauri.conf.json的bundle段定义了 NSIS 安装包和随附资源（许可证文件、离线 HTML 查看器运行时等），另有 tauri.linux.conf.json 与 tauri.macos.conf.json 覆盖 Linux/Debian 与 macOS 平台的差异，实现 Windows、Ubuntu、macOS 三端分发。

Rust 后端层：真正的重活都在这里

Rust 后端是整个项目的"发动机"，依赖 Tokio 异步运行时（负责并发调度）和 Cargo.toml 中锁定的其余依赖。按职责划分，核心模块只有三个值得新手重点关注：

engines/：把三大外部引擎"驯服"

高斯泼溅生成需要三个重量级外部程序，OOOSplat 没有让用户手动安装，而是内置并统一管理它们：

引擎	作用	适配器源码
FFmpeg / FFprobe	分析视频、按档位抽帧	engines/ffmpeg.rs
COLMAP 4.2.1	特征提取、匹配、相机位姿重建	engines/colmap.rs
Brush（OOOBrush）	GPU 训练高斯泼溅模型	engines/brush.rs

engines/health.rs 实现了硬件探测：启动时检测 NVIDIA 驱动版本、Compute Capability、显存档位，自动决定 COLMAP 走 CUDA GPU 还是回退 CPU，并把"为什么没加速"的原因显示在界面上。跨平台差异（Windows 的 Job Object 进程树、Linux 的 process group）则统一封装在 process/ 模块中，保证取消任务时子进程能被干净地"一锅端"。

pipeline/：七步流水线状态机

一条视频如何变成高斯模型？pipeline/runner.rs（5000+ 行的核心文件）实现了完整的流水线状态机：

输入视频 / 图片序列 ├─ 1. FFprobe 分析 → 按质量档位制定抽帧计划 ├─ 2. FFmpeg 抽帧并缩放到工作分辨率 ├─ 3. COLMAP 特征提取 + 匹配（GPU 或 CPU） ├─ 4. COLMAP 增量重建 + 注册率验证 ├─ 5. Brush GPU 训练高斯泼溅 └─ 6. 校验 PLY → 原子发布 final.ply

流水线的每个模块都有清晰分工（见 pipeline/mod.rs）：

event.rs：定义事件类型，把"COLMAP 正在匹配第 30%"这类进展变成结构化事件推送给前端；
progress.rs：把各阶段映射到 0–100% 总进度区间；
estimate.rs：基于历史耗时校准，生成"预计还需 12 分钟"的 ETA；
state.rs：把状态持久化到项目目录的state.json，支撑断点续跑。

质量档位（快速/均衡/精细）的参数则集中在 presets/ 与 config/pipeline-optimization.json，"自动优化"会根据显存档位动态选择训练分辨率——新手永远只需选一个档位，调参的事 Rust 替你做了。

其他支撑模块

project/：项目目录管理，每个任务生成独立文件夹（含final.ply、state.json、日志）；
reconstruction/：PLY 解析、模型校验与编辑后的变换写回；
tasks/：多任务注册表、日志环形缓冲与系统通知；
diagnostics/：失败后的脱敏错误报告生成；
telemetry/：默认开启、可关闭的匿名使用统计。

React 前端层：把流水线"翻译"成界面

前端由 React 19 + TypeScript 构建，入口是 src/main.tsx，主组件 App.tsx 组织了"01 创建新任务 / 02 历史任务 / 03 预览"三大工作区。

状态管理：Zustand 单 Store 模型

界面状态集中在 appStore.ts：当前输入路径、质量档位、引擎状态、实时进度、事件流……全部是一个 Zustand store，组件通过 hook 订阅所需切片，避免了 props 层层传递。

前后端通信：invoke 下行，listen 上行

backend.ts 是前端与 Rust 之间唯一的"通道总机"，模式非常直观：

调用：invoke("start_pipeline", {...})触发 Rust 侧同名命令（即 lib.rs 里注册的那个函数）；
监听：listen()订阅 Rust 用 Tauri 事件系统推送的流水线进度事件，驱动进度条和日志面板实时刷新；
资产：convertFileSrc()把本地 PLY 路径转成 WebView 可加载的asset://URL，供预览区读取模型。

高斯泼溅预览：浏览器里的 3D 引擎

预览模块 GaussianViewer/ 使用 PlayCanvas Engine 渲染数百万个高斯片元：支持 WebGPU 优先、WebGL2 回退，提供旋转/平移/缩放、球形与盒形选区删除、Transform 变换、撤销重做，还能把旋转镜头用 WebCodecs 编码导出为 MP4，或打包成单文件离线 HTML 分享（查看器源码见 html-viewer/）。

进阶能力：可选的本地 MCP 服务

0.6.0 起，OOOSplat 还能被本机的 AI Agent"遥控"。mcp/ 模块在 Rust 内嵌了一个 MCP（Model Context Protocol）服务，默认关闭、仅监听127.0.0.1、无需 token。启用后，Codex 等 Agent 通过 7 个工具（创建任务、启动、查进度、读日志、取消）操作与 GUI完全相同的Rust TaskService——AI 创建的任务会实时显示在同一个界面里。详细协议说明见 docs/mcp-v1.md。

架构亮点小结

回顾整套 OOOSplat 架构，它给"本地 AI 工具类桌面应用"提供了一个值得参考的模板：

分层清晰：React 只画界面、Rust 只做计算，Tauri 命令是唯一的契约边界；
引擎托管化：外部引擎固定版本、随包分发、启动即健康检查，用户零配置；
流水线状态机 + 事件驱动：进度、日志、断点续跑全部来自同一套结构化事件；
隐私即架构：CSP 全封闭、无 localhost API（MCP 除外）、数据只写用户自选目录。

如果你想动手体验，仓库提供了从源码构建的完整路径：安装 Node.js 22.12+ 与 Rust stable 后执行npm install→npm run setup:engines（下载并校验 COLMAP、Brush 运行时，见 engines/README.md）→npm run tauri -- dev。相关约定详见 CONTRIBUTING.md。