bring-shrubbery/ml-sharp-web

# ml-sharp-web  一个基于 Apple SHARP 构建的浏览器端高斯溅射生成器。✨ 此项目可以： - 上传一张图片 - 在浏览器中生成高斯溅射 - 预览结果 - 下载 .ply 文件 ## 链接 - 项目仓库：[bring-shrubbery/ml-sharp-web](https://github.com/bring-shrubbery/ml-sharp-web) - 在 X 上关注作者：[@bringshrubberyy](https://x.com/bringshrubberyy) - 上游 SHARP 仓库 (Apple)：[apple/ml-sharp](https://github.com/apple/ml-sharp) - SHARP 项目页面：[apple.github.io/ml-sharp](https://apple.github.io/ml-sharp/) - SHARP 论文：[arXiv:2512.10685](https://arxiv.org/abs/2512.10685) ## 开始之前（重要的许可证说明） Apple 的 SHARP 仓库对代码和模型权重有单独的许可证。 - SHARP 代码许可证：[LICENSE](https://github.com/apple/ml-sharp/blob/main/LICENSE) - SHARP 模型许可证：[LICENSE_MODEL](https://github.com/apple/ml-sharp/blob/main/LICENSE_MODEL) 如果您使用 Apple 发布的 SHARP 检查点/权重，必须遵循 `LICENSE_MODEL`（适用研究使用限制）。 ## 您需要准备的 - 安装 [Bun](https://bun.sh/) - 现代桌面浏览器（推荐 Chrome 或 Edge） - 足够的磁盘空间和内存来运行 SHARP 模型（导出的 ONNX 辅助文件较大，约 2.4 GB） ## 快速开始（运行应用）🚀 ### 2. 安装依赖 ``` bun install ``` 这还会自动将 ONNX Runtime Web WASM 资源复制到 `public/ort/`。 ### 3. 启动应用 ``` bun dev ``` 打开 Vite 显示的 URL（通常是 `http://localhost:5173`）。 ### 4. 使用应用 1. 上传一张图片。 2. 点击 `Generate Splat`。 3. 预览结果并下载 .ply 文件。 ## 重要的模型文件说明（`.onnx` + `.onnx.data`） SHARP 导出通常会产生**两个文件**： - `sharp_web_predictor.onnx` - `sharp_web_predictor.onnx.data` 这两个文件必须从同一文件夹（例如 `public/models/`）一起提供服务。 这很重要的原因是： - `.onnx` 文件只是图和元数据。 - `.onnx.data` 文件包含大部分模型权重。 因此，应用默认使用托管模型。 直接在浏览器中仅上传 `.onnx` 文件通常无法工作，因为 `.onnx.data` 辅助文件是分开的。 ## 将 SHARP 模型导出为 ONNX（适合初学者的步骤） 一切都在浏览器中运行，但您仍然需要一个导出的 SHARP ONNX 模型。 ### 1. 克隆 Apple 的 SHARP 仓库（参考代码） ``` git clone https://github.com/apple/ml-sharp /tmp/ml-sharp-upstream ``` ### 2. 准备 Python 环境用于导出 您需要 Python + SHARP 依赖项 + ONNX 导出依赖项。 最简单的方法是先按照上游 SHARP 的设置进行，然后从此仓库运行导出脚本。 ### 3. 导出浏览器预测器 ONNX 从此仓库运行： ``` python3 scripts/export_sharp_onnx.py \ --sharp-repo /tmp/ml-sharp-upstream \ --output public/models/sharp_web_predictor.onnx ``` 如果模型很大（确实很大），脚本还会写入： ``` public/models/sharp_web_predictor.onnx.data ``` ### 可选的导出标志 - `--checkpoint /path/to/sharp_2572gikvuh.pt` 使用手动下载的检查点 - `--device cuda` 在 GPU 上导出（如果您的环境支持） - `--opset 20` 更改 ONNX opset（默认是 `20`） ## 静态构建（可选） 如果您想要静态构建而不是运行 `bun dev`： ``` bun run build bun run preview ``` 注意： - `bun run build` 会将 `public/` 复制到 `dist/`，包括模型文件。 - 如果存在 `sharp_web_predictor.onnx.data`，构建输出将会非常大。 ## 工作原理（概览） - React + TypeScript UI（`src/`） - ONNX Runtime Web worker 用于推理（`src/workers/sharpWorker.ts`） - 浏览器端 SHARP 后处理（NDC -> 度量高斯转换） - 浏览器端 PLY 写入器 - 使用 [`@mkkellogg/gaussian-splats-3D`](https://github.com/mkkellogg/GaussianSplats3D) 的页面内预览 ## 故障排除 🛠️ ### "expected magic word ... found 3c 21 64 6f"（WASM 错误） 这意味着 WASM 文件请求返回了 HTML 而不是文件。 尝试： - 使用 `bun dev` 运行应用（而不是 `file://...`） - 在 `bun install` 后重启开发服务器 - 验证这些文件可以在浏览器中加载： - `/ort/ort-wasm-simd-threaded.asyncify.mjs` - `/ort/ort-wasm-simd-threaded.asyncify.wasm` ### 加载外部数据文件失败: sharp_web_predictor.onnx.data 这意味着 ONNX 辅助文件缺失或未正确提供。 检查： - `public/models/sharp_web_predictor.onnx` - `public/models/sharp_web_predictor.onnx.data` - 应用可以访问您的部署/浏览器环境中的托管模型文件 ### 应用可以运行，但生成非常慢或崩溃 SHARP 很大，浏览器推理很重。 尝试： - Chrome 或 Edge（桌面版） - 在 UI 中使用更小的 `Max gaussians` - 关闭其他占用内存多的标签页/应用 - 首次运行多等待一些时间（模型和运行时初始化可能需要时间） ## 技术栈 - [Bun](https://bun.sh/) - [React](https://react.dev/) - [TypeScript](https://www.typescriptlang.org/) - [Vite](https://vite.dev/) - [ONNX Runtime Web](https://onnxruntime.ai/) - [GaussianSplats3D 查看器](https://github.com/mkkellogg/GaussianSplats3D) ## 项目状态 可工作的原型/实验性版本。🧪 应用可以在浏览器中端到端运行，但性能和兼容性很大程度上取决于浏览器的 WebGPU/WASM 支持以及您机器上可用的内存。

标签：3D图形, 3D重建, Apex, Apple SHARP, Bun, Gaussian Splats, ONNX Runtime, PLY文件, Vite, WebGL, 图像处理, 机器学习, 模型部署, 浏览器端推理, 深度学习, 点云, 神经网络, 自动化攻击, 计算机视觉, 逆向工具, 高斯溅射