01-快速开始

# 01 · 快速开始

## 1. 目标

把一张图片变成可检查、可导出的 GEIMG 图元数据集。下面的命令按当前 CLI 的四步流程排列；如果使用 GUI，按钮顺序也是设置 → 图片 → 拟合 → 导出。

CLI 可执行文件通常为 `GE_IMG_Tool.exe`。以下示例省略了可执行文件路径，实际使用时替换为本机路径。

## 2. 最小流程

```text
1. 设置项目和对象模式
2. 导入图片并检查尺寸、透明度和网格
3. 选择拟合模式，设置预算，开始拟合
4. 用 inspect 查看结果，必要时做区域补精度
5. 导出数据集
```

一个典型的命令顺序如下：

```bash
GE_IMG_Tool.exe set project-name portrait-demo
GE_IMG_Tool.exe set object-type ui_control
GE_IMG_Tool.exe image add "input/portrait.png"
GE_IMG_Tool.exe image info --json
GE_IMG_Tool.exe image view --grid --out "output/grid.png" --json
GE_IMG_Tool.exe fit recommend --json
GE_IMG_Tool.exe fit mode transparent
GE_IMG_Tool.exe advanced set edge-aware on
GE_IMG_Tool.exe advanced set alternate-bg on
GE_IMG_Tool.exe fit shapes 800
GE_IMG_Tool.exe fit start --until full --json
GE_IMG_Tool.exe inspect --zoom auto --json
GE_IMG_Tool.exe export dataset --out "output/portrait-dataset"
```

`set object-type` 的取值是 `ui_control`（界面控件组）或 `asset_group`（素材组）。`image view` 必须带 `--out`；`--grid` 叠加的网格刻度就是源图像素，是估坐标前的固定动作。

命令名称和可用参数可能随版本变化。遇到不确定的步骤，先运行：

```bash
GE_IMG_Tool.exe status --json
```

以返回的 `available` 命令为准，不要凭记忆猜命令。

## 3. 什么时候换参数

- 整体环境图、背景图，不关心边缘形状：可以从 `standard` 开始，通常关闭 `edge-aware`；是否开 `alternate-bg` 取决于内容里是否有黑色或深色区域。
- 需要保留轮廓的图片：优先尝试 `transparent` + `edge-aware on`。
- 带透明通道的素材：把边缘感知作为必要候选，不要只因为它是 PNG 才决定参数。
- 黑色或深色内容拟合为空或明显偏少：尝试 `alternate-bg on`。近纯黑内容可能只能部分恢复。

## 4. 第一次不要急着追求最高预算

先用较小预算确认流程和模式正确，例如 200 个图元：

```bash
GE_IMG_Tool.exe fit shapes 200
GE_IMG_Tool.exe fit start --until full --timeout 120 --json
GE_IMG_Tool.exe inspect --zoom auto --json
```

确认模式、透明边缘和坐标都正确后，再提高目标图元数。图元预算按同一时间、同一屏的总量考虑；3000 以内只是常用起步参考，不是硬上限。

## 5. 收工前至少检查

- 图片不是全透明或空白输入。
- 拟合状态已经到目标阶段，而不是只完成初步阶段。
- `inspect` 中轮廓、细线和深色区域符合预期。
- 没有把 RMSE 或匹配度单独当作验收结论。
- 导出的 `shapes.json`、`manifest.json` 和预览文件都存在。
- 如果使用了高分辨率或长时间拟合，记录本机、版本、参数和耗时，便于以后复现。