# VI2G 使用指南

## 1. 安装与启动

1. 从 [VI2G 官方页面](https://viclant.com/software/vi2g)下载 Windows 压缩包。
2. 完整解压后运行 `VI2G.exe`。
3. 当前发布包未进行商业代码签名，Windows 可能显示“未知发布者”。请只从 `viclant.com` 下载，并核对页面公布的 SHA-256 校验值。

## 2. 直接查看 3DGS

点击 **Open .ply file**，或把 `.ply` 文件拖进窗口。加载后，状态栏会显示文件名和高斯数量。

### Blender 模式

- 鼠标中键：环绕观察。
- Shift + 鼠标中键：平移。
- 滚轮：缩放。
- Shift + B：框选放大。

### WASD 模式

- WASD：前后左右移动。
- 鼠标：转动视角。
- 空格 / Ctrl：上升 / 下降。
- Shift：加速。
- Esc：释放鼠标。

## 3. 从图片生成 3DGS

该功能会安装并调用外部 Apple SHARP 项目。

准备条件：

- Git。
- Python 3.13（ml-sharp 当前推荐版本）。
- 可用磁盘空间和网络连接；首次推理还会下载模型权重。
- CUDA GPU 推荐；CPU 可以执行预测，但速度较慢。

操作步骤：

1. 点击 **Setup ml-sharp**，等待下载与安装完成。
2. 选择输入图片或图片目录。
3. 选择输出目录。
4. 点击 **Run Predict**。
5. 生成完成后，VI2G 会尝试自动打开输出目录中的 `.ply`。

使用 ml-sharp 即表示用户自行接受其代码许可与模型许可。VI2G 不随发布包分发 Apple 代码或模型。

## 4. 预设与本地文件

控制预设保存在程序旁的 `vi2g_presets.json`。VI2G 不上传场景、图片、预设或使用数据；删除该文件即可重置预设。

## 5. 常见问题

### 打不开或黑屏

更新显卡驱动，并确认显卡支持 DirectX 12 或 Vulkan。大型 PLY 可能需要较多显存。

### ml-sharp 安装失败

先确认 Git 和 Python 3.13 可在命令行使用，并检查网络是否能访问 GitHub 与模型下载地址。

### 推理速度很慢

CPU 推理可以运行，但 CUDA GPU 更适合高频使用。
