🇨🇳 中文 | 🇺🇸 English

---

无需在每台设备上安装 App。只需在一台电脑上运行 Sharp GUI，局域网内的手机、平板和VR设备均可通过浏览器直接访问，即刻享受 3D 视觉盛宴。HTTPS 支持确保了陀螺仪等传感器功能在任何设备上都能完美调用。

功能	描述
📸 空间影像生成	上传任意图片，基于 Apple ML-Sharp 自动生成 3D 高斯溅射模型
🖼️ 现代工作流	支持多选/拖拽批量上传，后台队列智能调度，实时进度展示
👁️ 全能查看器	基于 Three.js + Gaussian Splats 3D 的高性能查看器，支持鼠标 / 触摸 / 键盘(WASD) / 陀螺仪全模态控制
📱 移动端优化	完美适配手机/平板，支持陀螺仪体感控制
🥽 VR 预览	支持 WebXR VR 模式，使用 Quest/Vision Pro 等头显沉浸式体验，支持手柄摇杆移动
📤 零门槛分享	一键导出为独立 HTML 文件，将你的空间记忆打包发给朋友，双击即看
🔐 安全与隐私	数据完全本地化，支持一键生成 SSL 证书，保障局域网传输安全
🚀 一键部署运行	自动配置 Python 环境、下载依赖、生成 HTTPS 证书，开箱即用

采用 Apple Human Interface Guidelines 设计理念，精心打造的高级用户体验：

设计元素	描述
毛玻璃效果	全局 backdrop-filter: blur() + 半透明背景，营造层次感
SF Pro 字体	使用苹果系统字体栈，原生级渲染体验
动态粒子背景	Canvas 绘制的浮动粒子，增添科技感
流畅过渡动画	所有交互均有精心调校的 cubic-bezier 缓动曲线
深色模式	自适应系统深色模式偏好

• 骨架屏加载 - 图片缩略图加载时显示渐变骨架动画
• 智能轮询 - 有任务时 2s 轮询，空闲时降至 10s，节省资源
• 拖拽上传 - 将图片直接拖入侧边栏即可开始处理
• 拖拽预览 - 将 .ply/.splat 模型文件拖入预览区直接加载
• 队列管理 - 待处理任务支持删除/取消
• 加载进度条 - 实时显示模型加载百分比
• 删除动画 - 删除项目时平滑的滑出动画效果
• 可折叠控制栏 - 底部控制栏可收起，最大化预览空间
• 操作指南面板 - 右上角帮助按钮，清晰的交互提示

• 🔒 HTTPS 支持 - 自动生成自签名证书，局域网安全访问
• 📦 文件优化 - PLY → Splat 格式转换，减少 43% 文件大小
• 🧹 自动清理 - 已完成任务 1 小时后自动清理，防止内存泄漏
• ⚙️ 可配置路径 - 支持自定义工作区文件夹
• 🖥️ 全屏模式 - 沉浸式 3D 预览体验
• 🥽 VR 模式 - 基于 WebXR 的 VR 预览，支持 Quest/Vision Pro 等头显，手柄摇杆移动控制
• 🌐 国际化支持 - 中英文双语界面，自动检测浏览器语言，支持手动切换

---

侧边栏图库列表 + 3D 模型预览区域 + 底部毛玻璃控制栏

    

左：手机端抽屉式侧边栏 | 右：平板端分栏布局

🎬 相机移动控制

    

左：WASD/QE 键盘移动 (Shift精细) | 右：移动端虚拟摇杆

🎬 批量上传 + 队列处理

拖拽多张图片到侧边栏，队列实时更新处理进度

🎬 陀螺仪体感控制 (移动端)

倾斜手机控制视角，iOS 风格实时指示球反馈

🎬 一键导出分享

点击 Share 导出独立 HTML，双击即可在任何浏览器打开

---

• 🪟 Glass Morphism - 毛玻璃效果控制栏，backdrop-filter: blur(30px)
• ✨ 动态粒子背景 - Canvas 绘制的浮动科技感粒子
• 🎯 iOS 风格指示球 - 移动端陀螺仪实时反馈
• 🎬 流畅动画 - 所有交互均有 cubic-bezier 缓动曲线
• 📱 响应式设计 - 完美适配桌面/平板/手机

---

平台	推理	视频渲染	状态
macOS Apple Silicon	✅ MPS	❌	✅ 已验证
Linux x86_64 无 GPU	✅ CPU	❌	✅ 已验证
Linux x86_64 + NVIDIA	✅ CUDA	✅	❓ 未验证
macOS Intel	✅ CPU	❌	❓ 未验证
Windows	❓ 未验证	❓	❓ 未验证

📢 缺少 GPU 不影响使用！ 3D 模型生成可在纯 CPU 环境下运行，仅视频渲染需要 CUDA。
👉 未验证平台理论上可正常工作，如遇问题欢迎在 Issues 反馈。

从 Releases 页面下载最新版本：

# 1. 下载并解压
unzip sharp-gui-v1.0.0.zip
cd sharp-gui

# 2. 运行安装脚本 (只需 Python 环境)
./install.sh      # Linux/macOS
# 或
install.bat       # Windows

# 3. 启动服务
./run.sh          # Linux/macOS
# 或
run.bat           # Windows

💡 预构建包已包含编译好的前端，无需安装 Node.js，开箱即用。
⚠️ 注意：预构建包基于正式版本发布，可能不包含最新开发中的功能。

# 1. 克隆项目
git clone https://github.com/lueluelue12138/sharp-gui.git
cd sharp-gui

# 2. 运行安装脚本 (自动拉取 ml-sharp 并配置环境)
./install.sh      # Linux/macOS
# 或
install.bat       # Windows

# 3. (可选) 如需修改前端，安装 Node.js 18+ 后运行：
./build.sh        # 构建前端

💡 安装脚本会自动生成 HTTPS 证书，建议使用 HTTPS 模式以获得完整功能。

./run.sh          # Linux/macOS (React 版本)
./run.sh --legacy # 使用原始单文件版本
# 或
run.bat           # Windows

访问 https://127.0.0.1:5050 (推荐) 或 http://127.0.0.1:5050 即可使用 🎉

---

1. 上传图片 - 点击「Generate New」按钮或直接拖拽图片到侧边栏
2. 等待处理 - 观察队列区域的实时进度（首次运行会下载 ~500MB 模型）
3. 预览模型 - 点击图库中的项目即可查看 3D 效果

操作	桌面端	移动端
旋转视角	鼠标左键拖拽	单指滑动
平移画面	鼠标右键拖拽	双指平移
缩放	滚轮	双指捏合
精细缩放	Shift + 滚轮	-
锁定焦点	点击模型	点击模型

控制方式	功能描述
WASD / QE	键盘平移相机（前后左右上下）
Shift + WASD	加速移动模式
Alt + WASD	精细移动模式
虚拟摇杆	移动端触摸平移（点击 Move 按钮开启）

模式	操作	说明
陀螺仪	点击「Gyro」按钮	倾斜手机控制视角
正面视角	点击「Front View」按钮	限制为正面视角，再次点击自由
重置视角	点击「Reset」按钮	恢复初始视角
全屏模式	点击「Fullscreen」按钮	沉浸式预览
VR 预览	点击「VR」按钮	进入 VR 模式（需 VR 设备/模拟器）

点击 Share 按钮，生成独立的 HTML 文件：

• 📦 包含完整的 3D 查看器（Three.js + Gaussian Splats 3D）
• 🌐 无需服务器，双击即可在浏览器打开
• 📉 已优化体积：PLY → Splat 格式转换，减少 43% 大小
• 🔒 包含免责声明，说明内容责任归属

---

可通过界面设置或编辑 config.json (首次运行后生成):

{
  "workspace_folder": "/path/to/workspace"
}

系统会自动在工作目录下创建：

• inputs/ - 上传的图片
• outputs/ - 生成的模型

启用 HTTPS 后可支持局域网设备的陀螺仪功能（浏览器要求安全上下文才能访问传感器 API）。

安装脚本会自动尝试生成证书。如需手动生成：

python generate_cert.py

💡 Windows 用户: 需要先安装 Git for Windows 或 OpenSSL。

生成成功后重启服务，使用 https:// 访问：

模式	本机	局域网	陀螺仪
HTTPS	https://127.0.0.1:5050	https://[IP]:5050	✅ 可用
HTTP	http://127.0.0.1:5050	http://[IP]:5050	❌ 仅本机

首次访问 HTTPS 时浏览器会提示证书警告（因为是自签名证书），选择「继续访问」即可。

---

sharp-gui/
├── 📄 app.py                 # Flask 后端 + 任务队列系统
├── 📄 install.sh/bat         # 一键安装脚本
├── 📄 run.sh/bat             # 启动脚本 (支持 --legacy 参数)
├── 📄 build.sh/bat           # 前端构建脚本
├── 📄 release.sh/bat         # 发布打包脚本
├── 📄 generate_cert.py       # SSL 证书生成工具
├── 📁 frontend/              # React 现代前端 (v1.0.0+)
├── 📁 templates/             # 原始单文件前端 (Legacy)
├── 📁 static/lib/            # Three.js + Gaussian Splats 3D
├── 📁 ml-sharp/              # (安装后) Apple ML-Sharp 核心
├── 📁 inputs/                # 输入图片
└── 📁 outputs/               # 输出模型 (.ply)

frontend/
├── 📁 src/
│   ├── 📁 api/               # API 客户端 (gallery, tasks, settings)
│   ├── 📁 components/
│   │   ├── 📁 common/        # 通用组件 (Button, Modal, Loading, ParticleBackground)
│   │   ├── 📁 gallery/       # 图库组件 (GalleryList, GalleryItem)
│   │   ├── 📁 layout/        # 布局组件 (Sidebar, ControlsBar, TaskQueue, Settings)
│   │   └── 📁 viewer/        # 查看器组件 (ViewerCanvas, VirtualJoystick, GyroIndicator)
│   ├── 📁 hooks/             # 自定义 Hooks (useViewer, useGyroscope, useKeyboard)
│   ├── 📁 i18n/              # 国际化 (zh.json, en.json)
│   ├── 📁 store/             # Zustand 状态管理
│   ├── 📁 styles/            # 全局样式 (variables, animations)
│   ├── 📁 types/             # TypeScript 类型定义
│   └── 📁 utils/             # 工具函数
├── 📄 vite.config.ts         # Vite 配置 (代码分割)
└── 📁 dist/                  # 构建产物

层级	技术
前端	React 19 + TypeScript + Vite / 原生单文件 (Legacy)
状态管理	Zustand
国际化	i18next + react-i18next
样式	CSS Modules + Apple Glass Morphism
后端	Python 3.10+, Flask, 多线程任务队列
AI 引擎	Apple ML-Sharp (PyTorch, gsplat)
3D 渲染	Three.js + Gaussian Splats 3D

优化项	说明
代码分割	Vite manualChunks: three.js (489KB), gaussian-splats (249KB), react-vendor (4KB)
缩略图系统	自动生成 200px JPEG 缩略图，节省带宽
智能轮询	有任务时 2s 轮询，空闲时 10s，节省资源
格式转换	导出时 PLY → Splat 格式转换，减少 43% 文件体积
内存清理	已完成任务 1 小时后自动从内存中移除
进度优化	进度条只允许前进，避免视觉跳变

---

# 安装依赖
cd frontend
npm install

# 开发模式 (热更新)
npm run dev

# 构建生产版本
npm run build
# 或使用项目脚本
./build.sh

./run.sh           # 使用 React 现代版本 (默认)
./run.sh --legacy  # 使用原始单文件版本

# 自动构建并打包
./release.sh v1.0.0

# 输出: sharp-gui-v1.0.0.zip (包含预构建前端)

---

• Apple ML-Sharp - 核心 3D 生成模型
• Gaussian Splats 3D - Three.js 高斯溅射渲染器
• antimatter15/splat - Splat 格式转换参考

---

欢迎提交 Issue 和 Pull Request！

• 🐛 Bug 反馈 - 在 Issues 中提交问题
• 💡 功能建议 - 通过 Issue 讨论新功能想法
• 🔧 代码贡献 - Fork 项目后提交 PR

如果你在其他平台（Linux/Windows）上测试通过，也欢迎反馈！

---

由于本地部署生成内容无限制，本项目生成的 3D 模型由用户使用 AI 工具生成，模型内容由用户自行负责，与本开源项目及其开发者无关。

严禁将本工具用于生成或传播任何违法、侵权或不当内容。

---

本项目基于 MIT 许可证开源。

请注意：ML-Sharp 模型有单独的 模型许可证，仅限非商业用途。

---