个人维护的 apple/ml-sharp fork。
给它一张照片，30 秒内（GPU）吐出一个可实时渲染的 3D Gaussian Splatting 场景。不需要深度相机，不需要多角度拍摄，就一张普通照片。
在 Apple 原版 CLI 基础上，这个 fork 加了三件事：一个跑在浏览器里的 3DGS 查看器、一个 FastAPI 预测接口、还有 Docker 一键部署配置。模型代码没动过，新增内容都在 server/、web/、scripts/ 和 docker-compose.yml 里。
| 功能 | 上游 ml-sharp | 本 fork |
|---|---|---|
| CLI 预测 | ✅ | ✅ |
| 视频渲染（CUDA） | ✅ | ✅ |
| 浏览器 3DGS 查看器 | ❌ | ✅ |
| 图片上传 → 自动预测 → 实时预览 | ❌ | ✅ |
.splat / .ksplat / .spz 文件支持 |
❌ | ✅ |
| FastAPI 预测接口 | ❌ | ✅ |
| Docker 一键部署 | ❌ | ✅ |
| CPU / MPS 稳定运行 | 部分 | ✅（修复了无 CUDA 时崩溃问题） |
需要 Python 3.13。
# 创建虚拟环境（推荐 uv）
uv venv --python 3.13 .venv
source .venv/bin/activate
# 或用 conda
conda create -n sharp python=3.13 && conda activate sharp
# 安装依赖
pip install -r requirements.txt
# 验证安装
sharp --help模型权重（~500 MB）首次运行时自动下载，缓存到 ~/.cache/torch/hub/checkpoints/。
也可以手动下载：
wget https://ml-site.cdn-apple.com/models/sharp/sharp_2572gikvuh.ptsharp predict -i /path/to/photo.jpg -o /path/to/output/输出是 .ply 格式的 3D Gaussian Splat 文件，兼容常见的 3DGS 渲染器。
指定手动下载的模型权重：
sharp predict -i photo.jpg -o output/ -c sharp_2572gikvuh.pt# 预测 + 渲染一步完成
sharp predict -i photo.jpg -o output/ --render
# 或从已有的 .ply 出发
sharp render -i output/ -o renderings/gsplat 渲染器第一次启动会初始化一段时间，不是卡死。
浏览器里直接预览 3DGS 场景，不用装任何桌面软件。
支持四种使用方式：
- 上传图片 → 自动预测 → 实时加载（需要后端服务）
- 输入本地
.ply文件路径直接加载（开发模式） - 上传已有的
.ply/.splat/.ksplat/.spz文件 - 自动加载默认示例（
teaser.ply）
快捷键： H 键切换场景统计 HUD（高斯点数、帧率、内存等）。
# 一条命令同时启动后端（8321）和前端（5173）
./scripts/dev-all.sh打开 http://127.0.0.1:5173 即可。
两个服务分别是：
- 前端：Vite 开发服务器，React 19 + Three.js +
@mkkellogg/gaussian-splats-3d - 后端：FastAPI（
server/app.py），接收图片 → 调用sharp predict→ 返回.ply路径
分开启动：
./scripts/dev-backend.sh # 只启后端
./scripts/dev-frontend.sh # 只启前端前端依赖：
cd web && pnpm install前端把图片 POST 到 /api/predict，后端接收后：
- 保存图片到
/tmp/sharp-output/<job_id>/input/ - 调用
sharp predict生成.ply - 返回
{ job_id, ply_path, ply_url, duration_s } - 前端自动加载生成的场景
预测时间参考：MPS（Apple Silicon）约 30 秒，CPU 约 1–3 分钟，首次运行需额外等待模型下载。
docker compose up --buildNginx 在容器内反代前后端，模型权重通过 named volume 持久化，重启不用重新下载。
资源要求：推理峰值内存约 6–7 GB（CPU），预留 2 GB 起步。生产部署建议给 7 GB 以上内存限制，否则大图片容易 OOM。
# docker-compose.yml 中的关键配置
deploy:
resources:
limits:
memory: 7G
reservations:
memory: 2G自定义端口或设备：
SHARP_DEVICE=mps docker compose upcutome-sharp/
├── src/sharp/ # 模型核心代码（来自上游）
│ ├── cli/ # CLI 入口（predict + render）
│ ├── models/ # 神经网络架构
│ └── utils/ # IO、几何工具
├── server/
│ └── app.py # FastAPI 预测 API（本 fork 新增）
├── web/ # 浏览器查看器（本 fork 新增）
│ └── src/
│ ├── App.tsx # 主界面：数据源选择 / 上传 / 预测流程
│ └── components/ # SplatViewer（Three.js 封装）、SceneStats HUD
├── scripts/
│ ├── setup.sh # 首次环境初始化
│ ├── dev-all.sh # 一键启动前后端开发服务器
│ ├── dev-backend.sh # 单独启动后端
│ ├── dev-frontend.sh # 单独启动前端
│ └── predict.sh # CLI 预测快捷脚本
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── requirements.txt
SHARP 使用 OpenCV 坐标系：x 向右，y 向下，z 向前。场景中心大致在 (0, 0, +z)。
接入第三方渲染器时可能需要旋转或缩放以对齐场景中心，具体取决于渲染器的坐标约定。
原始模型来自 Apple 研究团队，论文：
Sharp Monocular View Synthesis in Less Than a Second Lars Mescheder, Wei Dong, Shiwei Li, Xuyang Bai, Marcel Santos, Peiyun Hu, Bruno Lecouat, Mingmin Zhen, Amaël Delaunoy, Tian Fang, Yanghai Tsin, Stephan Richter, Vladlen Koltun arXiv:2512.10685 · Project Page
@inproceedings{Sharp2025:arxiv,
title = {Sharp Monocular View Synthesis in Less Than a Second},
author = {Lars Mescheder and Wei Dong and Shiwei Li and Xuyang Bai and Marcel Santos
and Peiyun Hu and Bruno Lecouat and Mingmin Zhen and Ama\"{e}l Delaunoy
and Tian Fang and Yanghai Tsin and Stephan R. Richter and Vladlen Koltun},
journal = {arXiv preprint arXiv:2512.10685},
year = {2025},
url = {https://arxiv.org/abs/2512.10685},
}模型代码依赖的开源组件详见 ACKNOWLEDGEMENTS。
代码：LICENSE ｜ 模型权重：LICENSE_MODEL