SharpViewer

SharpViewer 是一个本地离线的 SHARP 推理与 3D 预览工具。将图片拖入窗口或 Ctrl+V 粘贴即可在本地调用 Apple 开源 SHARP 模型生成 3D 信息，并通过可交互视角展示“3D 化效果”。

具备预览高斯和导出高斯或点云ply的功能,高斯点云为通用标准,可以通过现有的其他插件直接导入UE/unity/Blender/...

目录结构

/sharp-viewer/
  /src/
    /viewer/              # GUI 与渲染
    /infer/               # SHARP 推理封装
    /common/              # 日志/缓存/hash/配置
  /models/                # 默认权重目录（可为空）
  /output/                # 输出缓存（按 hash 分目录）
  /scripts/               # 工具脚本（可选）
  demo.jpg
  SharpViewer.spec
  requirements.txt
  README.md
  run.bat
  build.bat

环境要求

• Windows 10/11 x64
• Python 3.11
• 建议显卡：NVIDIA GPU + 最新驱动（CUDA 可选）
• 若需要 CUDA 推理，请安装对应 CUDA 版的 PyTorch（见下文）

开发环境一键搭建

1. 打开项目目录后，直接运行：

build.bat

2. 该脚本会创建 .venv、安装依赖并调用 PyInstaller。

如需 CUDA 版 PyTorch，可在执行前设置环境变量：

set TORCH_INDEX_URL=https://download.pytorch.org/whl/cu121

然后再执行 build.bat 或 run.bat。

运行方式

• 开发调试：

run.bat

• CLI 推理接口：

python -m src.infer.run --input <path> --outdir <dir> --resolution 1024 --device auto --format manifest

首次运行权重下载/放置说明

• 默认会从 Apple 官方链接下载模型权重到： %LOCALAPPDATA%\SharpViewer\models_cache\
• 若你已手动下载权重，可放在： models/ 或 %LOCALAPPDATA%\SharpViewer\models_cache/
• 如果没有网络，程序会提示并允许你选择本地权重文件（.pt）。

缓存机制

• 以图片内容 hash 为键，输出缓存在 output/。
• 同一图片重复导入会显示“命中缓存”，秒开结果。

打包产物说明

构建完成后输出目录：

dist/SharpViewer/
  SharpViewer.exe
  demo.jpg
  models/          # 若存在本地权重会一起拷贝
  (依赖 DLL/库文件)

双击 SharpViewer.exe 即可运行，无需安装 Python/conda。

常见错误排查

1. CUDA 不可用

   • 检查显卡驱动是否为最新版本
   • 确认已安装 CUDA 版 PyTorch
   • 确认显卡未被禁用或显存不足

2. DLL 缺失

   • 重新运行 build.bat，确保依赖已完整安装
   • 检查是否缺少 Microsoft VC++ 运行库

3. OpenGL 初始化失败

   • 更新显卡驱动
   • 远程桌面环境可能会限制 OpenGL

4. 显存不足

   • 使用更小分辨率（例如 1024）
   • 关闭其他占用显存的程序

5. 权重校验失败或下载失败

   • 重新下载权重到 models/ 或 %LOCALAPPDATA%\SharpViewer\models_cache\
   • 断网情况下，请手动选择本地权重文件

备注

• 默认优先使用 CUDA：device="cuda" if torch.cuda.is_available() else "cpu"。
• 日志位置：logs/app.log 与 logs/infer.log。
• 若需要迁移模型缓存，请复制 %LOCALAPPDATA%\SharpViewer\models_cache\。