# ml-sharp

**Repository Path**: nowhere2020/ml-sharp

## Basic Information

- **Project Name**: ml-sharp
- **Description**: Sharp Monocular View Synthesis in Less Than a Second
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-21
- **Last Updated**: 2025-12-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SHARP 中文使用说明

## 🎉 欢迎使用 SHARP

SHARP 是一个强大的单目图像 3D 视图合成工具，可以从单张照片生成高质量的 3D 场景表示。

---

## 🚀 快速开始

### 方法 1: 使用工具箱（推荐）

双击运行 `tools\sharp_toolkit.bat`，然后：
- 选择 `[1]` 运行示例
- 选择 `[3]` 打开查看器查看结果

### 方法 2: 命令行

```bash
# 处理图片
python run_sharp.py predict -i data/teaser.jpg -o output/demo

# 查看结果
# 访问 https://playcanvas.com/supersplat/editor
# 拖拽 output/demo/teaser.ply 到浏览器
```

---

## 📁 项目文件说明

### 主要脚本
- **tools\sharp_toolkit.bat** - 完整工具箱菜单（推荐使用）
- **tools\quick_start.bat** - 一键快速开始
- **tools\open_viewer.bat** - 打开在线查看器
- **tools\run_sharp.py** - 主运行脚本

### 文档
- **docs\HOW_TO_VIEW_PLY.md** - 如何查看 .ply 文件（重要！）
- **docs\QUICK_REFERENCE.md** - 快速参考卡
- **docs\USAGE_GUIDE.md** - 详细使用指南
- **docs\RUN_SUCCESS_REPORT.md** - 运行成功报告
- **docs\MODEL_SETUP.md** - 模型设置说明

---

## 🎯 常用操作

### 处理图片

```bash
# 单张图片
python run_sharp.py predict -i your_photo.jpg -o output/result

# 批量处理
python run_sharp.py predict -i photos_folder/ -o output/batch

# 使用 GPU 加速
python run_sharp.py predict -i photo.jpg -o output/result --device cuda
```

### 查看结果

生成的 `.ply` 文件需要专门的查看器：

**推荐查看器：**
1. **SuperSplat** (最推荐)
   - 网址: https://playcanvas.com/supersplat/editor
   - 直接拖拽 .ply 文件到浏览器

2. **antimatter15** (轻量快速)
   - 网址: https://antimatter15.com/splat/

3. **Polycam** (桌面应用)
   - 下载: https://poly.cam/tools/gaussian-splatting

**快捷方式：**
- 运行 `open_viewer.bat` 自动打开查看器
- 或在 `sharp_toolkit.bat` 中选择 `[3]`

---

## ⚙️ 系统要求

- **Python**: 3.13
- **内存**: 建议 8GB+
- **硬盘**: 至少 5GB 可用空间（模型 2.6GB + 输出）
- **GPU**: 可选（CUDA GPU 可加速 40-50 倍）

---

## 📊 性能参考

| 模式 | 处理速度 | 适用场景 |
|------|----------|----------|
| CPU | 40-60秒/张 | 测试、少量图片 |
| CUDA GPU | <1秒/张 | 批量处理、生产环境 |

---

## 🔧 常见问题

### 1. 批处理文件显示乱码？
**已修复！** 所有批处理文件现在使用 UTF-8 编码，不会出现乱码。

### 2. .ply 文件无法打开？
`.ply` 是 3D Gaussian Splat 格式，需要专门的查看器：
- 使用 `open_viewer.bat` 打开在线查看器
- 详见 `HOW_TO_VIEW_PLY.md`

### 3. 模型文件在哪里？
```
C:\Users\你的用户名\.cache\torch\hub\checkpoints\sharp_2572gikvuh.pt
```

### 4. 如何检查模型是否正确？
- 运行 `sharp_toolkit.bat`
- 选择 `[5]` 检查模型文件
- 大小应为约 2620 MB

### 5. 处理速度太慢？
- 使用 NVIDIA GPU（速度快 40-50 倍）
- 或在后台批量处理

---

## 💡 使用建议

### 输入图片
- ✅ 推荐: 室内、建筑、风景等有明确 3D 结构的场景
- ✅ 分辨率: 1024×768 或更高
- ✅ 质量: 清晰、光照良好
- ❌ 避免: 纯平面、抽象图案、过暗或过曝

### 输出文件
- `.ply` 文件大小: 通常 50-100MB
- 可用各种 3DGS 查看器打开
- 可导出为视频、图片或其他 3D 格式

---

## 📚 详细文档

所有文档都在项目目录中：

1. **查看 .ply 文件** → `HOW_TO_VIEW_PLY.md`
2. **快速命令参考** → `QUICK_REFERENCE.md`
3. **详细使用说明** → `USAGE_GUIDE.md`
4. **模型设置** → `MODEL_SETUP.md`

**快速打开文档：**
- 运行 `sharp_toolkit.bat`
- 选择 `[6]` 查看帮助文档

---

## 🎬 完整工作流示例

```bash
# 1. 准备图片
# 将照片放在某个文件夹，例如 my_photos/

# 2. 批量处理（使用工具箱）
# 运行 sharp_toolkit.bat
# 选择 [2] 运行自定义图片
# 输入路径: my_photos
# 输入输出名称: my_results

# 3. 查看结果
# 在工具箱中选择 [3] 打开在线查看器
# 拖拽 output/my_results/*.ply 到浏览器

# 4. 或使用命令行
python run_sharp.py predict -i my_photos/ -o output/my_results
```

---

## 🌐 在线资源

- **项目主页**: https://apple.github.io/ml-sharp/
- **研究论文**: https://arxiv.org/abs/2512.10685
- **GitHub**: https://github.com/apple/ml-sharp

---

## ✅ 部署状态

- ✅ Python 3.13.5 已安装
- ✅ 所有依赖包已安装
- ✅ 模型文件已下载
- ✅ 成功运行测试
- ✅ 批处理文件编码已修复

**状态**: 🟢 完全就绪

---

## 🆘 获取帮助

1. **查看文档**: 运行 `sharp_toolkit.bat` 选择 `[6]`
2. **命令行帮助**: `python run_sharp.py --help`
3. **在线资源**: 访问项目主页

---

**祝您使用愉快！** 🎨✨

如有问题，请查看相关文档或在线资源。